PHPackages christopheraseidl/laravel-auto-filer - 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. christopheraseidl/laravel-auto-filer ActiveLibrary[File & Storage](/categories/file-storage) christopheraseidl/laravel-auto-filer ==================================== A simple package for automating the organization of files associated with models. v0.3.0(11mo ago)10[4 PRs](https://github.com/christopheraseidl/laravel-auto-filer/pulls)MITPHPPHP ^8.3CI passing Since Jul 18Pushed 5mo ago1 watchersCompare [ Source](https://github.com/christopheraseidl/laravel-auto-filer)[ Packagist](https://packagist.org/packages/christopheraseidl/laravel-auto-filer)[ Docs](https://github.com/christopheraseidl/laravel-auto-filer)[ GitHub Sponsors](https://github.com/christopheraseidl)[ RSS](/packages/christopheraseidl-laravel-auto-filer/feed)WikiDiscussions main Synced today READMEChangelog (1)Dependencies (15)Versions (6)Used By (0) Automated file organization for Eloquent Models =============================================== [](#automated-file-organization-for-eloquent-models) [![Latest Version on Packagist](https://camo.githubusercontent.com/75641ec543154f74d0fe74ed0bd9c593ad0e08c79b0a99ec5759ab4ee9f57ebf/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6368726973746f7068657261736569646c2f6c61726176656c2d6175746f2d66696c65722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/christopheraseidl/laravel-auto-filer)[![GitHub Tests Action Status](https://camo.githubusercontent.com/65a65f210a39c336aebee339cb9db4d7b041b0a5a4fd6227590a4a528d9b083d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6368726973746f7068657261736569646c2f6c61726176656c2d6175746f2d66696c65722f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/christopheraseidl/laravel-auto-filer/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/b48f89c2db94d6360b23081b45a3e2199bef37eabc48c12c202adeb3a97b2563/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6368726973746f7068657261736569646c2f6c61726176656c2d6175746f2d66696c65722f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/christopheraseidl/laravel-auto-filer/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/9c36c2c9dd99aa77008799ef264d4020daefd8048c506765037460d88999a5e9/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6368726973746f7068657261736569646c2f6c61726176656c2d6175746f2d66696c65722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/christopheraseidl/laravel-auto-filer) Laravel Auto Filer is a simple package that automates file organization for your Eloquent models. It handles file uploads, moves them to organized directories, and automatically cleans up files when they are deleted from the model or when their models are deleted. ### Key features [](#key-features) - **Automatic file organization**: files are organized in a predictable structure: `model_type/model_id/subfolder/filename`. - **Automatic file movement**: files are automatically moved from temporary to permanent locations when models are saved. - **Automatic cleanup**: files are deleted when their associated models are deleted or when the files have been removed from the model. - **Rich text field support**: automatically handles files embedded in rich text content. - **Thumbnail generation**: automatic thumbnail creation for images with automatic cleanup. - **Circuit breaker protection**: built-in circuit breaker prevents cascading failures. - **Laravel 10, 11, and 12 support**: compatible with recent Laravel versions. Installation ------------ [](#installation) You can install the package via composer: ``` composer require christopheraseidl/laravel-auto-filer ``` You can optionally publish the config file: ``` php artisan vendor:publish --tag="laravel-auto-filer-config" ``` Usage ----- [](#usage) Add the `HasAutoFiles` trait to your model and define which attributes should handle file uploads: ``` use christopheraseidl\AutoFiler\HasAutoFiles; class Product extends Model { use HasAutoFiles; protected $fillable = [ 'images', 'current_report', 'description', ]; protected function casts(): array { return [ 'images' => 'array', ]; } // Option 1: Using a property protected $file = [ 'images' => 'images', 'current_report' => 'documents' ]; // Option 2: Using a method public function files(): array { return [ 'images' => 'images', 'current_report' => 'documents' ]; } // Property for rich text fields protected $richText = [ 'description' => 'content', ]; // Or using a method public function richTextFields(): array { return [ 'description' => 'content', ]; } } ``` ### How it works [](#how-it-works) 1. **File upload**: Upload files to a temporary location and store the paths in your model attributes. 2. **Model save**: When the model is saved, files are automatically moved to their permanent location. 3. **Path structure**: Files are organized as `disk://products/1/images/filename.jpg`. 4. **File deletion**: When a file is removed from a model attribute, it is deleted from the disk. 5. **Model delete**: When a model is deleted, all associated files and their thumbnails are automatically removed. 6. **Rich text processing**: Files referenced in rich text fields are automatically managed. 7. **Thumbnail management**: When enabled, thumbnails are automatically created for images and cleaned up when originals are removed. ### Example usage [](#example-usage) ``` // Creating a new product with file uploads $product = new Product([ 'name' => 'Awesome Product', 'images' => [ 'uploads/temp/image1.jpg', 'uploads/temp/image2.jpg', ], 'current_report' => 'uploads/temp/current_report.pdf', ]); $product->save(); // Files are now moved to: // - products/1/images/image1.jpg (with thumbnail: image1-thumb.jpg if enabled) // - products/1/images/image2.jpg (with thumbnail: image2-thumb.jpg if enabled) // - products/1/documents/current_report.pdf // Updating files $product->images = ['uploads/temp/new-image.jpg']; $product->save(); // Old images and their generated thumbnails are deleted, // new one is moved to products/1/images/new-image.jpg // and a new thumbnail is automatically created if enabled // Deleting the model $product->delete(); // All associated files and their thumbnails are automatically deleted ``` ### Thumbnail generation [](#thumbnail-generation) The package automatically generates thumbnails for image files when enabled in the config. Thumbnails are created during file moves and automatically cleaned up when the original files are deleted. When enabled, uploading an image will automatically create a thumbnail alongside the original: - Original: `products/1/images/photo.jpg` - Thumbnail: `products/1/images/photo-thumb.jpg` Thumbnails are automatically managed: when you delete or replace the original image, the corresponding thumbnail is also removed. ### File Cleanup [](#file-cleanup) You may schedule the `CleanOrphanedUploads` job by following [Laravel's documentation on scheduling jobs](https://laravel.com/docs/12.x/scheduling#scheduling-queued-jobs). Configuration ------------- [](#configuration) The package supports extensive configuration options. Here are the key settings: ``` return [ // Storage configuration 'disk' => 'public', 'temp_directory' => 'uploads/temp', // Queue configuration 'queue_connection' => null, 'queue' => null, 'broadcast_channels' => null, // File validation 'max_size' => 5120, // 5MB in KB 'mimes' => [ 'image/jpeg', 'image/png', 'image/svg+xml', 'application/pdf', 'application/msword', 'text/plain', 'video/mp4', 'audio/mpeg', // ... more MIME types ], 'extensions' => [ 'jpg', 'jpeg', 'png', 'svg', 'ico', 'pdf', 'doc', 'docx', 'odt', 'rtf', 'txt', 'md', 'mp4', 'mp3', ], // Thumbnail generation 'thumbnails' => [ 'enabled' => false, 'width' => 400, 'height' => null, 'suffix' => '-thumb', 'quality' => 85, ], // Cleanup configuration 'cleanup' => [ 'enabled' => false, 'dry_run' => true, 'threshold_hours' => 24, 'schedule' => 'daily', ], // Retry and throttling 'maximum_file_operation_retries' => 3, 'retry_wait_seconds' => 1, 'throttle_exception_attempts' => 10, 'throttle_exception_period' => 10, // minutes ]; ``` Testing ------- [](#testing) ``` ./vendor/bin/pest ``` Changelog --------- [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. Credits ------- [](#credits) - [Chris Seidl](https://github.com/christopheraseidl) - [All Contributors](../../contributors) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 30 — LowBetter than 62% of packages Maintenance61 Regular maintenance activity Popularity2 Limited adoption so far Community7 Small or concentrated contributor base Maturity45 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% 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 Unknown Total 1 Last Release 352d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/73406146?v=4)[Chris](/maintainers/christopheraseidl)[@christopheraseidl](https://github.com/christopheraseidl) --- Top Contributors [![christopheraseidl](https://avatars.githubusercontent.com/u/73406146?v=4)](https://github.com/christopheraseidl "christopheraseidl (1 commits)") --- Tags laravelchristopheraseidllaravel-auto-filer ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/christopheraseidl-laravel-auto-filer/health.svg) ``` [![Health](https://phpackages.com/badges/christopheraseidl-laravel-auto-filer/health.svg)](https://phpackages.com/packages/christopheraseidl-laravel-auto-filer) ``` ### Alternatives [spatie/laravel-permission Permission handling for Laravel 12 and up 12.9k102.4M1.4k](/packages/spatie-laravel-permission)[spatie/laravel-pdf Create PDFs in Laravel apps 1.0k4.8M47](/packages/spatie-laravel-pdf)[dedoc/scramble Automatic generation of API documentation for Laravel applications. 2.1k11.2M102](/packages/dedoc-scramble)[spatie/laravel-passkeys Use passkeys in your Laravel app 471890.7k39](/packages/spatie-laravel-passkeys)[rawilk/profile-filament-plugin Profile & MFA starter kit for filament. 3914.6k](/packages/rawilk-profile-filament-plugin)[wnx/laravel-backup-restore A package to restore database backups made with spatie/laravel-backup. 213421.4k2](/packages/wnx-laravel-backup-restore) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)