Running It Safely
The package deletes files, so every default leans towards keeping a file when in doubt. This page collects the checks in one place.
Before the first clean
- List every column that can point to a file as a source. Search your code for
->store(,->storeAs(,Storage::putandStorage::disk(to find them. - Run
php artisan orphan:scanand look at the ratio. A ratio close to 90% or higher almost always means a source is missing. - Run
orphan:explainon a few files you know are in use and a few reported orphans. - Run
orphan:cleanwithout--forceand read the list.
Dry run by default
orphan:clean changes nothing unless you add --force. The dry run prints the same table as a scan, the first 15 files it would move, and the safety warnings it would hit.
Trash, not delete
By default a clean moves files to .orphan-trash/{disk}/{date}/ with their original paths. Nothing is lost until orphan:purge-trash removes trash older than 30 days.
php artisan orphan:restore --list # what's in the trash
php artisan orphan:restore avatars/jane.jpg # put one file back
php artisan orphan:restore --all --date=2026-11-15 # undo a whole dayDelete mode
'mode' => 'delete' or --mode=delete skips the trash. There's no undo. Keep trash mode until you've done several cleans and restored nothing.
The grace period
Files modified less than 24 hours before the database was read are skipped. That covers uploads whose row isn't saved yet: a file stored in step one of a form, or by a job that hasn't finished. Because the age is counted from when the database was read, an upload that arrives during a long clean is also safe.
The safety limit
If more than 90% of a disk would be cleaned, orphan:clean --force stops before moving anything. The usual cause is a source that's missing from the config, or one pointing at the wrong disk.
--force-ratio
--force-ratio skips the check for one run. Use it only after orphan:explain has confirmed, file by file, that the reported orphans are really unused, for example after deleting a large feature on purpose.
Other checks
- A configured table or column that doesn't exist stops the run before anything is read.
- Only the disks and folders under
disksare scanned.--dircan narrow them but never widen them. - Rows are read from the primary database connection, so a lagging read replica can't hide a reference.
- Soft-deleted rows still count as references.
- If a stored URL's host isn't recognised, files matching the end of the URL path are kept (
match_unknown_hosts). - Normalizers can only add ways to read a stored value. A buggy one keeps too much, it can't cause a deletion.
Found a file that was cleaned by mistake?
Restore it, then run orphan:explain on it to see why it counted as an orphan. Usually a source is missing. Please report a real bug privately as described in the package's SECURITY.md, since a bug that loses data is treated as a security issue.