orphan:installClean up the uploads your database forgot.
Replaced avatars, images from deleted posts and abandoned uploads stay on your disk and keep costing money. This package finds every file no database row points to and moves it to a trash folder you can restore from.
composer require erag/laravel-orphan-filesinstall$ php artisan orphan:scan
+------+-------+------------+---------+-------------+
| Disk | Files | Referenced | Orphans | Reclaimable |
+------+-------+------------+---------+-------------+
| s3 | 320 | 160 | 160 | 593.1 MB |
+------+-------+------------+---------+-------------+
WARN 160 orphaned files (593.1 MB) can be cleaned.
$ php artisan orphan:clean --force
INFO Moved to the trash: 160 files (593.1 MB).
Restore them with php artisan orphan:restore.
$ 

orphan:clean --force moves them to the trash, orphan:purge-trash --all deletes them, and the second scan finds nothing left. The problem
Laravel stores the file and your table stores its path. When the row changes or goes away, nothing removes the file. Over months these orphans add up to gigabytes you pay for and back up.
The row now points to the new file. The old one stays on the disk.
The row is gone, but its cover and gallery images are still in storage.
The editor drops the img tag. The uploaded file is never cleaned up.
The file is stored before the form is submitted, and the form is abandoned.
avatars/jane-v2.jpgusers.avatar, row 12avatars/jane-v1.jpgreplaced by a new avatarposts/launch.jpgimg tag in posts.body, row 7posts/old-banner.jpgits post was deletedcomments/a1.jpgcomments.images, row 31comments/tmp-4821.pngthe form was never saved3 of 6 files have no row pointing at them. In the recording above it was 160 of 320 images on a MinIO bucket, or 593.1 MB.
How it works
Each run compares the two from scratch. No table of its own, no listeners on your models, nothing stored between runs.
Reads every column you list as a source, 1,000 rows at a time, and keeps each file path as a hash.
Streams the file listing of each configured disk and folder, so a bucket with millions of objects is fine.
A file that no reference matches is an orphan, unless an exclusion, the grace period or a file rule keeps it.
A scan only reports. A clean previews the list, and with --force moves the files to .orphan-trash/.
Where paths live
Plain paths, JSON arrays, rich text and full URLs. Pick a column type to see what goes in the config and which files it keeps.
avatars/jane-v2.jpg
['table' => 'users', 'column' => 'avatar', 'type' => 'path', 'disk' => 'public']
avatars/jane-v2.jpgSafe by default
Deleting files is the risky part, so every default leans towards keeping a file. And when a file does move, it can still come back.
orphan:clean without --force lists every file it would move and changes nothing.
Files move to .orphan-trash/ on the same disk. orphan:restore puts them back at their old path.
Files changed in the 24 hours before the database was read are skipped, so fresh uploads are safe.
A clean stops if more than 90% of a disk would go. That almost always means a source is missing.
orphan:purge-trash only deletes trashed files older than 30 days. You choose when it runs.
Rows are only read, from the primary connection. Soft-deleted rows still keep their files.
A table or column that does not exist stops the run before a single file is touched.
A URL on a host you never configured still keeps the file whose path it ends with.
Why a package
Comparing one column with one folder takes ten lines. The cases that delete live files are the ones you only find later.
Also included
Every app stores files a little differently. These cover the setups that usually break a simple cleanup.
exclude_patternsExclusions and globsPaths and patterns like defaults/* or *.pdf are never cleaned.only_extensionsSize and type rulesOnly clean files within a size range, or with the extensions you pick.FileFilterCustom filtersYour own FileFilter class can return a reason to keep any file.extractorsCustom source typesAdd an extractor for a format your app invented, next to path, json, html and url.normalizersNormalizersTeach it another way your app writes paths. They can only add files to keep.prefixScoped and prefixed disksA disk's root and a scoped disk's prefix are used when matching URLs and deleting.case_sensitiveCase-insensitive storageSet case_sensitive to false for macOS volumes or a case-insensitive MySQL collation.trash.diskTrash on another diskPoint trash.disk at a separate disk, and set how many days the trash is kept.--dateRestore by path or dateBring back one file, a whole folder, or only the copy trashed on a given day.--mode=deleteDelete modeSkip the trash with --mode=delete. S3 objects are removed 1,000 keys per request.OrphanFiles::Facade and eventsCall scan, clean and explain from PHP, and listen for trashed or deleted files.explainSpot broken referencesorphan:explain also tells you when a row points to a file that is missing from the disk.Six commands
No web UI, no migrations. Pick a command to see what it prints on the demo app.
$ php artisan orphan:install
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/
Large buckets
Tables are read in chunks and storage listings are streamed, so memory stays flat as your storage grows.
Automate it
Scan weekly, clean on a quiet night, and empty old trash every day.
Schedule::command('orphan:scan --json')->weekly(); Schedule::command('orphan:clean --force') ->weekly()->sundays()->at('03:00') ->withoutOverlapping(); Schedule::command('orphan:purge-trash')->daily();
--queuerun a scan or clean as a queued job--jsonprint the scan summary for scripts and alerts--export=csvwrite every orphan to a CSV file--older-than=7dreplace the grace period for one run Events for alerts: OrphanScanCompleted, OrphanFilesTrashed and OrphanFilesDeleted. Prefer PHP? Call it from code.
Laravel Boost + AI agents
The package ships a Laravel Boost guideline and an orphan-files-setup skill. After php artisan boost:install, agents like Claude Code, Cursor or Copilot set it up the way the docs describe instead of guessing.
Installing, writing the config, listing every column that stores files, the first scan, checking files with explain, and scheduling.
Agents preview with a scan or a dry run, and ask you before using --force, delete mode or --force-ratio.
Clean up the unused uploads in our MinIO bucket.
I ran php artisan orphan:scan: 160 of 320 files are orphans, 593.1 MB in total.
The dry run with orphan:clean lists them all. Nothing has changed yet.
orphan:clean --force moves them to .orphan-trash/, where you can restore them. Should I run it?
Questions
By default it only reports. A clean needs --force and moves files to a trash folder you can restore from. Files changed in the last 24 hours are skipped, and a run stops if more than 90% of a disk would go. Start with a scan and check a few files with orphan:explain.
No. It only reads your tables. Very large runs create one temporary table, which is dropped at the end. Set diff.driver to memory if you would rather avoid it.
No. Tables are read 1,000 rows at a time and storage listings are streamed. Referenced paths are kept as hashes, about 25 MB for 250,000 of them, and move to a temporary table past diff.memory_limit.
No. The HasStorageFiles trait only declares which columns hold files. Files are only removed when you run orphan:clean --force.
Yes. Global scopes are ignored, so a soft-deleted row still counts as a reference. Restoring the row should bring its file back too.
Trash mode moves them inside the bucket, so they never leave S3. Delete mode uses DeleteObjects with up to 1,000 keys per request.
In .orphan-trash/{disk}/{date}/{original path}, on the same disk or on the disk you set as trash.disk. Scans never look inside it, and orphan:purge-trash empties it after 30 days.
Laravel 12 on PHP 8.2 or newer, and Laravel 13 on PHP 8.3 or newer. S3, MinIO and RustFS disks also need league/flysystem-aws-s3-v3.
Something else? Read the full FAQ, the troubleshooting guide, or open an issue.
Get started
$ composer require erag/laravel-orphan-files$ php artisan orphan:install # creates config/orphan-files.php$ php artisan orphan:scan # read-only, changes nothingLaravel 12 on PHP 8.2+, or Laravel 13 on PHP 8.3+. S3, MinIO and RustFS also need league/flysystem-aws-s3-v3.