File Usage

In most applications, users need to upload and manage files such as profile pictures, documents, or attachments. Laraventus provides a simple and extensible way to handle file uploads through the AventusFile class.

This system integrates directly with Laravel’s Eloquent casting mechanism, allowing you to store files as model attributes while automatically managing their upload, storage, and access.

AventusFile

AventusFile is an abstract base class that implements Laravel’s CastsAttributes interface. It provides a clean and consistent way to bind uploaded files to model attributes and to handle their lifecycle.

When a model attribute uses AventusFile as its cast type, Laraventus automatically:

• Converts the stored file path (URI) from the database into an object instance on retrieval
• Handles file uploads automatically on save
• Generates a unique filename and saves it using Laravel’s filesystem
• Stores the public URL of the file for frontend access

Creating a Custom File Type

<?php

namespace App\Models;

use Aventus\Laraventus\Models\AventusFile;

class UserPicture extends AventusFile
{
    protected function get_save_directory($model): string
    {
        // All uploaded pictures will be stored in the "users" directory
        return "users";
    }
}

This defines a file handler that will store uploaded files under storage/app/public/users.

Using a File in a Model

Once your custom file class is created, you can easily attach it to a model.

<?php

namespace App\Models;

use Aventus\Laraventus\Models\AventusModel;

/**
 * @property UserPicture $picture
 */
class User extends AventusModel
{
    protected $fillable = [
        'picture'
    ];

    protected function casts(): array
    {
        return [
            'picture' => UserPicture::class
        ];
    }
}

Uploading a File

When sending data to your backend (for example, from AventusJs or a REST client), you can provide a structure like:

{
  "picture": {
    "uri": "",
    "upload": <binary file>
  }
}

Laraventus will:

1. Save the uploaded file in the defined directory (users/)
2. Generate a unique file name using a UUID
3. Store the public URL in the database (e.g., /storage/users/abcd-efgh.jpg)
4. Automatically make that URL available on the frontend through $user->picture->uri

Customization Options

You can customize AventusFile by overriding its protected methods:

Method	Description
define_filesystem()	Choose which filesystem disk to use (Storage::disk('public') by default)
get_save_directory($model)	Define where files will be stored (must be implemented)
get_file_name(UploadedFile $upload)	Customize how filenames are generated
get_uri(string $path)	Control how the file’s public URL is built

Example Result

When saving a User with an uploaded picture:

$user = new User();
$user->picture = [
    'upload' => $request->file('picture')
];
$user->save();

The resulting database entry might look like:

id	picture
1	/storage/users/2f8a9d8e-9a7f-4f21-abc2-fc98d71a36e7.jpg

And on the frontend (via AventusJs):

{
  "$type": "App.Models.User",
  "picture": {
    "$type": "App.Models.UserPicture",
    "uri": "/storage/users/2f8a9d8e-9a7f-4f21-abc2-fc98d71a36e7.jpg"
  }
}

AventusImage

While AventusFile provides a flexible foundation for handling any kind of uploaded file, images often need additional processing, such as resizing or format conversion.

That’s where AventusImage comes in.

AventusImage extends AventusFile and adds built-in image manipulation features using the powerful Intervention Image library. It allows you to define maximum dimensions, enforce file formats (like converting all uploads to .webp), and automatically handle compression and storage, all with minimal setup.

Example

Let’s define an image class that automatically resizes pictures to a maximum of 800×800 pixels and converts them to WebP format.

<?php

namespace App\Models;

use Aventus\Laraventus\Models\AventusImage;

class UserPicture extends AventusImage
{
    protected function get_save_directory($model): string
    {
        // Store all user pictures under "users"
        return "users";
    }

    protected function max_size()
    {
        // Resize down to a maximum of 800x800 pixels
        return ["width" => 800, "height" => 800];
    }

    protected function force_extension(): bool|string
    {
        // Convert all images to webp format
        return "webp";
    }
}

This ensures all uploaded images are resized and saved as optimized .webp files.

Just like with AventusFile, you can use your image class as a cast in an AventusModel:

<?php

namespace App\Models;

use Aventus\Laraventus\Models\AventusModel;

/**
 * @property UserPicture $picture
 */
class User extends AventusModel
{
    protected $fillable = [
        'picture'
    ];

    protected function casts(): array
    {
        return [
            'picture' => UserPicture::class
        ];
    }
}

Available Methods to Customize

You can override these methods to control the image behavior:

Method	Type	Description
max_size()	array	Defines maximum width and height. If both are null, the image keeps its original size.
force_extension()	bool or string	Return a string (e.g. "webp", "jpg") to convert all images to that format. Return false to keep the original extension.