PHPackages toneflix-code/laravel-fileable - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [File & Storage](/categories/file-storage) 4. / 5. toneflix-code/laravel-fileable ActiveLibrary[File & Storage](/categories/file-storage) 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.1.7(10mo ago)24.9k↓100%[3 PRs](https://github.com/toneflix/laravel-fileable/pulls)2MITPHPPHP ^8.1|^8.2|^8.3CI passing Since Sep 2Pushed 1mo agoCompare [ Source](https://github.com/toneflix/laravel-fileable)[ Packagist](https://packagist.org/packages/toneflix-code/laravel-fileable)[ Docs](https://github.com/toneflix/laravel-fileable)[ RSS](/packages/toneflix-code-laravel-fileable/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (10)Dependencies (13)Versions (58)Used By (2) Laravel Fileable ================ [](#laravel-fileable) [![ServBay](https://private-user-images.githubusercontent.com/52163001/395575543-030fcfad-95dc-40db-89b2-7ca1e8be3dce.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzQyMzM0MjUsIm5iZiI6MTc3NDIzMzEyNSwicGF0aCI6Ii81MjE2MzAwMS8zOTU1NzU1NDMtMDMwZmNmYWQtOTVkYy00MGRiLTg5YjItN2NhMWU4YmUzZGNlLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjAzMjMlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwMzIzVDAyMzIwNVomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTE2OGIwZTU3YTk3Y2U0ODFkNmVkNWJjODFjYzcxMGI0ZWY0OTFlYTNlZTQzNWNjNzhkOWI5YWMyMWQwZWQ1ODImWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0In0.wk3aO_lJJE2brKmqmmfV_KwIB4kT4yBjvPr95lQGZYg)](https://www.servbay.com)[![Test & Lint](https://github.com/toneflix/laravel-fileable/actions/workflows/run-tests.yml/badge.svg?branch=main)](https://github.com/toneflix/laravel-fileable/actions/workflows/run-tests.yml)[![Latest Stable Version](https://camo.githubusercontent.com/84c5175c4edd6914db3eb2ed5b3a2d100eda40d2c78798e298307f0eb969a8ee/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f746f6e65666c69782d636f64652f6c61726176656c2d66696c6561626c652e737667)](https://packagist.org/packages/toneflix-code/laravel-fileable)[![Total Downloads](https://camo.githubusercontent.com/0bb6a568c6d0aed925d3a34bc8680b7a13ed5eb8d3cf90ee5ac5fccbf3c265e8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f746f6e65666c69782d636f64652f6c61726176656c2d66696c6561626c652e737667)](https://packagist.org/packages/toneflix-code/laravel-fileable)[![License](https://camo.githubusercontent.com/3b9dacc7aa979a12d9210a62b0fd44611baf12ba64893c3f23bc9c0f455468fe/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f746f6e65666c69782d636f64652f6c61726176656c2d66696c6561626c652e737667)](https://packagist.org/packages/toneflix-code/laravel-fileable)[![PHP Version Require](https://camo.githubusercontent.com/a24901fabb53a14cd2adc5499190109395a98a1db9e04b7d04f7d01e65ff5511/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f746f6e65666c69782d636f64652f6c61726176656c2d66696c6561626c652f706870)](https://packagist.org/packages/toneflix-code/laravel-fileable)[![codecov](https://camo.githubusercontent.com/7d41257f00d8507e61895e0cf532c5789cbc811304689f0bb63d06dfca2532af/68747470733a2f2f636f6465636f762e696f2f67682f746f6e65666c69782f6c61726176656c2d66696c6561626c652f67726170682f62616467652e7376673f746f6b656e3d324f376146756c513950)](https://codecov.io/gh/toneflix/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 with support for uploading base64 encoded files. Installation ------------ [](#installation) You can install the package via composer: ``` composer require toneflix-code/laravel-fileable ``` Package Discovery ----------------- [](#package-discovery) 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 ``` Upgrading --------- [](#upgrading) Version 2.x is not compatible with version 1.x, if you are ugrading from version 1.x here are a few notes: ### Config [](#config) 1. If you published the configuration file, remove `image_templates`. Templates are no longer needed, just set you responsive image sizes using the `image_sizes` property. 2. Add `responsive_image_route` and set the value `route/path/{file}/{size}`, `route/path` can be whatever you want it to be, `{file}/{size}` can be anything you want to name them but both are required. Configuration ------------- [](#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 [](#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 [](#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 [](#image-sizes) This package uses [Intervention Imagecache](https://github.com/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](https://image.intervention.io/v2/usage/cache) for information about customizsing this feature. ### File Route Secure [](#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 [](#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 [](#secure-file-middleware) The `file_route_secure_middleware` config option sets which middleware to apply when using the protected files collection. ### Symlinks [](#symlinks) The `symlinks` option maps where [Intervention Imagecache](https://github.com/Intervention/imagecache) should search for images in your app, this does not overide your current [Intervention Imagecache](https://github.com/Intervention/imagecache) configuration, it appends. ### Image Templates [](#image-templates) The `image_templates` option generates image filters based on [Intervention Imagecache](https://github.com/Intervention/imagecache) templates, this also does not overide your current [Intervention Imagecache](https://github.com/Intervention/imagecache) configuration, it appends. Usage ----- [](#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', ]); } } ``` ### fileableLoader. [](#fileableloader) The `fileableLoader` is responsible for mapping your model to the required collection and indicates that you want to use Laravel Filable to manage your model files. The `fileableLoader()` method accepts an 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 ``, the `value` should be an existing collection in your Laravel Fileable configuration. #### Single collection initialization. [](#single-collection-initialization) ``` $this->fileableLoader([ 'avatar' => 'avatar', ]); ``` #### Multiple collection initialization. [](#multiple-collection-initialization) ``` $this->fileableLoader([ 'avatar' => 'avatar', 'image' => 'default', ]); ``` #### String parameter initialization. [](#string-parameter-initialization) The `fileableLoader()` method also accepts the `key` as a string first parameter and the `value` as a string as the second parameter. ``` $this->fileableLoader('avatar', 'default'); ``` #### Default media. [](#default-media) COnfigured default files are not loaded by default, to load the default file for the model, the `fileableLoader` exposes a third parameter, the `useDefault` parameter, setting it to true will ensure that your default file is loaded when the model's file is not found or missing. ``` $this->fileableLoader('avatar', 'default', true); ``` OR ``` $this->fileableLoader([ 'avatar' => 'avatar', ], 'default', true); ``` #### Supporting old setup (Legacy Mode) [](#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 or system before the introduction of the fileable trait. ``` $this->fileableLoader('avatar', 'default', true, true); ``` OR ``` $this->fileableLoader([ 'avatar' => 'avatar', ], 'default', true, true); ``` #### Custom Database field. [](#custom-database-field) There are times when you may want to use a different file name from your database field name, an instance could be when your request includes two diffrent file requests for different models that have the same database field names, the last parameter of the `fileableLoader` was added to support this scenario. The 5th parameter of the `fileableLoader` is a string that should equal to the database field where you want your file reference stored in or an array that maps the request file name to the database field name. Take a look at this example. ``` ``` ``` $this->fileableLoader('admin_avatar', 'default', true, true, 'image'); ``` OR ``` $this->fileableLoader([ 'admin_avatar' => 'avatar', ], 'default', true, true, 'image'); ``` OR ``` $this->fileableLoader([ 'cover' => 'cover', 'admin_avatar' => 'avatar', ], 'default', true, true, [ 'cover' => 'cover_image', 'admin_avatar' => 'image', ]); ``` In the last example, `cover_image` is an existing database field mapped to the `cover` input request file name and `image` is an existing database field mapped to the `admin_avatar` input request file name. ### Model Events [](#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 [](#model-attributes) Laravel Fileable exposes 3 model Attributes which will help with accessing your saved files #### defaultImage() [](#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() [](#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() [](#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() [](#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() [](#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() [](#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 [](#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`; ### Manually saving files [](#manually-saving-files) You can also skip the interface and use the `save` method of `Media` library to manually create your files, the `save` method returns the name of the file as saved in your configured storage. ``` use ToneflixCode\LaravelFileable\Media; use App\Models\User; $user = User::find(1); $user->image = \ToneflixCode\LaravelFileable\Facades\Media::save('media', "image", $user->image); $user->saveQuietly(); ``` In the above example `media` is the target collection where your file should be saved while `image` is the name of the input from the request holding your file. #### Manually saving from wildcard request array. [](#manually-saving-from-wildcard-request-array) Consider the following two scenarios in a controller. ``` ['users' => $fields] = $this->validate($request, [ 'users.*.id' => ['required', 'exists:users,id'], 'users.*.image' => ['nullable', 'image', 'mimes:png,jpg'], ]); foreach ($fields as $i => $form) { $user = \App\Models\User::find($form['id']); $user->image = \ToneflixCode\LaravelFileable\Facades\Media::save('media', "users.*.image", $user->image, $i); $user->saveQuietly(); } ``` ``` $valid = $this->validate($request, [ 'files' => ['required', 'array'], 'files.*' => ['required', 'file', 'mimes:mp3,wav'], ]); foreach ($valid['files'] as $i => $file) { $file = new \App\Models\Audio(); $file->image = \ToneflixCode\LaravelFileable\Facades\Media::save('audio', "files.*", null, $i); $file->saveQuietly(); } ``` What we have done is save the files from within a loop, the 4th parameter of the `save` method \[`index`\] indicates where the file we want to save can be found in the requests uploaded file list. Events ------ [](#events) Everytime a file is saved, we emit the `\ToneflixCode\LaravelFileable\Events\FileSaved` event which you can listen to and perform further actions. The event signature, includes the current instance of the model that was saved, the associated `mediaFileInfo()` and the original filename from the upload request file. *EventServiceProvider* or anywhere else you listen to events ``` public function boot(): void { Event::listen(function (\ToneflixCode\LaravelFileable\Events\FileSaved $event) { dd($event->model, $event->fileInfo, $event->file_name); }); } ``` ### Testing [](#testing) ``` composer test ``` ### Changelog [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently. Contributing ------------ [](#contributing) Please see [CONTRIBUTING](CONTRIBUTING.md) for details. ### Security [](#security) If you discover any security related issues, please email instead of using the issue tracker. Credits ------- [](#credits) - [Toneflix Code](https://github.com/toneflix) - [All Contributors](../../contributors) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 51 — FairBetter than 96% of packages Maintenance79 Regular maintenance activity Popularity23 Limited adoption so far Community13 Small or concentrated contributor base Maturity75 Established project with proven stability Bus Factor1 Top contributor holds 89.7% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~20 days Recently: every ~41 days Total 52 Last Release 311d ago Major Versions 1.4.1 → 2.0.0-beta2024-02-07 PHP version history (3 changes)1.0.0PHP ^8.0|^8.1 1.3.5PHP ^8.0|^8.1|8.2 2.0.0-betaPHP ^8.1|^8.2|^8.3 ### Community Maintainers ![](https://www.gravatar.com/avatar/4638f9de973d94753ebff641af3009e1049064f9a6bd76fe87e58d0d8ddd7ca7?d=identicon)[3m1n3nc3](/maintainers/3m1n3nc3) --- Top Contributors [![3m1n3nc3](https://avatars.githubusercontent.com/u/52163001?v=4)](https://github.com/3m1n3nc3 "3m1n3nc3 (279 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (17 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (15 commits)") --- Tags toneflix-codelaravel-fileableversion 2.x ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/toneflix-code-laravel-fileable/health.svg) ``` [![Health](https://phpackages.com/badges/toneflix-code-laravel-fileable/health.svg)](https://phpackages.com/packages/toneflix-code-laravel-fileable) ``` ### Alternatives [unisharp/laravel-filemanager A file upload/editor intended for use with Laravel 5 to 10 and CKEditor / TinyMCE 2.2k3.3M73](/packages/unisharp-laravel-filemanager)[stechstudio/laravel-zipstream A fast and simple streaming zip file downloader for Laravel. 4633.7M3](/packages/stechstudio-laravel-zipstream)[spatie/laravel-google-cloud-storage Google Cloud Storage filesystem driver for Laravel 2408.9M12](/packages/spatie-laravel-google-cloud-storage)[flarum/core Delightfully simple forum software. 211.3M1.9k](/packages/flarum-core)[azure-oss/storage-blob-laravel Azure Storage Blob filesystem driver for Laravel 63582.2k1](/packages/azure-oss-storage-blob-laravel)[erag/laravel-disposable-email A Laravel package to detect and block disposable email addresses. 226102.4k](/packages/erag-laravel-disposable-email) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)