Installation
Requirements
| Laravel | PHP |
|---|---|
| 12.x | 8.2, 8.3, 8.4 |
| 13.x | 8.3, 8.4 |
S3, MinIO, RustFS and other S3-compatible disks also need league/flysystem-aws-s3-v3, covered below.
Install the package
Two commands set everything up:
composer require erag/laravel-orphan-files
php artisan orphan:installLaravel discovers the service provider and the OrphanFiles facade on its own.
What orphan:install does
- It creates
config/orphan-files.phpwith the package defaults. - If that file already exists, it asks before overwriting it. Answer no, or run it without a terminal, and your config is kept.
--forceoverwrites the file without asking.- It prints the next steps.
- It never touches your database and creates no migrations.
INFO Published config/orphan-files.php.
Next steps
1. In config/orphan-files.php, list your upload folders under 'disks' and the columns that store file paths under 'sources'.
2. Run php artisan orphan:scan to see how many orphaned files you have.
3. Run php artisan orphan:clean for a dry run, then php artisan orphan:clean --force to move the orphans to the trash.
Docs: https://erag.in/laravel-orphan-files/Out of the box the config scans nothing: disks and sources are empty until you fill them in. The quick start shows a first setup, and the orphan:install page lists its options.
Alternative
You can also publish the config with Laravel's own command: php artisan vendor:publish --tag=orphan-files-config. It creates the same file but skips the overwrite question and the next steps.
S3, MinIO and RustFS
Laravel's S3 driver needs the Flysystem adapter. If your app already uses an s3 disk, you have it.
composer require league/flysystem-aws-s3-v3 "^3.0"MinIO and RustFS use the same S3 driver with a custom endpoint. See MinIO and RustFS for the disk config.
Check that it works
php artisan list orphanYou should see six commands:
orphan:clean Trash or delete orphaned storage files (dry run unless --force).
orphan:explain Show whether a file is referenced, and where, or why it counts as an orphan.
orphan:install Publish the orphan-files config file and show the next steps.
orphan:purge-trash Permanently delete trashed orphan files older than the retention period.
orphan:restore Restore trashed orphan files to their original paths.
orphan:scan Find storage files that no database row references.AI agents and Laravel Boost
The package ships a Laravel Boost guideline and an orphan-files-setup skill. If your app uses Boost, php artisan boost:install or php artisan boost:update adds them for your coding agent. The guideline tells agents to preview with a scan or dry run and to ask before using --force, delete mode or --force-ratio. The package doesn't require laravel/boost.