toneflix-code/laravel-fileable

Laravel Fileable exposes methods that make handling file upload with Laravel filesystem even easier, it also exposes a trait that automatically handles file uploads for you.

2.0.2-beta 2024-02-08 06:37 UTC

Requires

• php: ^8.1|^8.2|^8.3
• illuminate/filesystem: ^8.1|^9.0|^10.0
• illuminate/support: ^8.1|^9.0|^10.0
• intervention/image: ^3.3

Requires (Dev)

• fakerphp/faker: ^1.21
• illuminate/contracts: ^9.0|^10.0
• laravel/pint: ^1.0
• orchestra/testbench: ^8.8
• pestphp/pest: 2.x-dev
• pestphp/pest-plugin-laravel: ^2.0

MIT

• Legacy

• laravel-fileable
• toneflix-code
• version 2.0.0-beta

README

Laravel Fileable exposes methods that make handling file upload with Laravel filesystem even easier, it also exposes a trait that automatically handles file uploads for you with support for uploading base64 encoded files.

Installation

You can install the package via composer:

composer require toneflix-code/laravel-fileable

Installation

Laravel automatically discovers and publishes service providers but optionally after you have installed Laravel Fileable, open your Laravel config file config/app.php and add the following lines.

In the $providers array add the service providers for this package.

ToneflixCode\LaravelFileable\FileableServiceProvider::class

Add the facade of this package to the $aliases array.

'Fileable' => ToneflixCode\LaravelFileable\Facades\Fileable::class

Configuration

By default Laravel Fileable avatar and media directories and symlinks to your storage/app/public directories, and also adds the file directory to your storage/app directory. You may change this or decide to modify the directories that will be created by running the following artisan command.

php artisan vendor:publish --provider="ToneflixCode\LaravelFileable\FileableServiceProvider"

The configuration file is copied to config/toneflix-fileable.php. With this copy you can alter the settings for your application locally.

Generating symlinks

After publishing and modifying the configuration, both of which are optional you will need to run the following artisan command to actually generate the required symlinks by running the following artisan command.

php artisan storage:link

Collections

The collection config option define where files should be stored and optionally a default file that should be returned when the requested file is not found.

Image Sizes

This package uses Intervention Imagecache to generate responsive images for image files on demand, the image_sizes config option defines which responsive sizes to generate, you are not limited to use the defined sizes, take a look at Intervention Imagecache Documentation for information about customizsing this feature.

File Route Secure

The file_route_secure config option sets the route from which secure images should be loaded from. The route accepts one parameter, the {file} parameter.

File Route Open

The file_route_open config option sets the route from which secure images which do not require authentication or authorization should be loaded from. The route accepts one parameter, the {file} parameter.

Secure File Middleware

The file_route_secure_middleware config option sets which middleware to apply when using the protected files collection.

Symlinks

The symlinks option maps where Intervention Imagecache should search for images in your app, this does not overide your current Intervention Imagecache configuration, it appends.

Image Templates

The image_templates option generates image filters based on Intervention Imagecache templates, this also does not overide your current Intervention Imagecache configuration, it appends.

Usage

To automatically discover files in request and save them to storage and database you will need to add the ToneflixCode\LaravelFileable\Traits\Fileable trait to your models and register the required filables using the fileableLoader() method from the ToneflixCode\LaravelFileable\Traits\Fileable trait.

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use ToneflixCode\LaravelFileable\Traits\Fileable;

class User extends Model
{
    use HasFactory, Fileable;

    public function registerFileable()
    {
        $this->fileableLoader([
            'avatar' => 'default',
        ]);
    }
}

The fileableLoader() method accepts and array of [key => value] pairs that determines which files should be auto discovered in your request, the key should match the name field in your input field E.g <input type="file" name="avatar">, the value should be an existing collection in your Laravel Fileable configuration.

$this->fileableLoader([
    'avatar' => 'avatar',
]);

OR

$this->fileableLoader([
    'avatar' => 'avatar',
    'image' => 'default',
]);

The fileableLoader() method also accepts the key as a string as the first parameter and the value as a string as the second parameter.

$this->fileableLoader('avatar', 'default');

Loading|Not Loading default media.

The third parameter of the fileableLoader() is a boolean value that determines wether to return null or the default image when the requested file is not found.

Supporting old setup (Legacy Mode)

If you had your model running before the introducation of the the Fileable trait, you might still be able to load your existing files by passing a fourth parameter to the fileableLoader(), the Legacy mode attempts to load media files that had been stored or managed by a different logic before the introduction of the fileable trait.

Model Events

If you use listen to laravel events via the boot() you would need to move your event handles to the registerEvents() method of the ToneflixCode\LaravelFileable\Traits\Fileable trait.

This should be defined in your model to overide the default handles.

public static function registerEvents()
{
    static::creating(function ($item) {
        $item->slug = str($item->title)->slug();
    });
}

Model Attributes

Laravel Fileable exposes 3 model Attributes which will help with accessing your saved files

defaultImage()

This attribute exposes the default image of the ToneflixCode\LaravelFileable\Traits\Fileable trait

Depending on the collections you have created, you may need to add the default image file to the respective directories within the collections.

$post = Post::first();
var_dump($post->default_image);

mediaFile()

Returns a single media link from list of all bound files (Usefull especially when you are binding only a single resource)

$user = User::first();
$avatar = $user->media_file;
var_dump($avatar);

mediaFileInfo()

Returns the attribute of a single media file (Usefull especially when you are binding only a single resource)

$post = Post::first();
var_dump($post->media_file_info);

getFiles()

Returns a list of bound files with a little more details like mime, isImage, url, path and size

$post = Post::first();
var_dump($post->get_files);
var_dump($user->get_files['image']);

files()

This attribute exposes all images registered with the fileableLoader() method of the ToneflixCode\LaravelFileable\Traits\Fileable trait

$user = User::first();
var_dump($user->files);
var_dump($user->files['avatar']);

$post = Post::first();
var_dump($post->files['image']);

responsiveImages()

If the registered files are images this attribute exposes responsive images for them or returns the defual image

$user = User::first();
var_dump($user->responsive_images);
var_dump($user->responsive_images['avatar']);

$post = Post::first();
var_dump($post->responsive_images['image']);
var_dump($post->responsive_images['banner']);

Prefixed Media Collections

While the library will try to resolve media files from the configured collection, you can also force media file search from collections different from the configured ones by saving the path reference on the database with a collection:filename.ext prefix, this will allow the system to look for media files in a collection named collection even if the current collection for the model is a collection named images;

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

Credits

• Toneflix Code
• All Contributors

License

The MIT License (MIT). Please see License File for more information.