Quick Start
This walks through a typical first setup: user avatars on the public disk and comment images stored as JSON.
If you haven't installed the package yet, run composer require erag/laravel-orphan-files and then php artisan orphan:install. The installation page explains both.
1. Tell it where files live
In config/orphan-files.php, list the disks and the folders that hold uploads:
'disks' => [
'public' => ['avatars/', 'comments/'],
],Only these folders are ever scanned or cleaned. Use the narrowest folders you can; don't list a disk root that also holds exports, logs or cached files.
2. Tell it which columns point to files
'sources' => [
['table' => 'users', 'column' => 'avatar', 'type' => 'path', 'disk' => 'public'],
['table' => 'comments', 'column' => 'images', 'type' => 'json', 'key' => '*.path', 'disk' => 'public'],
],users.avatar holds a path like avatars/jane.jpg. comments.images holds JSON like [{"path": "comments/41/a.jpg"}], and key picks the paths out of it. See Sources for HTML and URL columns.
Find every column first
A file whose column you forgot looks like an orphan. Search your code for ->store(, ->storeAs( and Storage::put to find every place that saves an upload, and add each column it writes to.
3. Scan
php artisan orphan:scanThe scan only reads. On the demo app it prints:
+--------+---------------------+-------+------------+---------+-----------+-----------+-------------+--------+
| Disk | Directories | Files | Referenced | Orphans | Protected | Cleanable | Reclaimable | Ratio |
+--------+---------------------+-------+------------+---------+-----------+-----------+-------------+--------+
| public | avatars/, comments/ | 43 | 23 | 20 | 0 | 20 | 6.8 MB | 46.51% |
+--------+---------------------+-------+------------+---------+-----------+-----------+-------------+--------+
WARN 20 orphaned files (6.8 MB) can be cleaned. Preview with: php artisan orphan:clean.4. Spot-check a few files
Pick one file you know is in use and one reported orphan, and ask about each:
php artisan orphan:explain avatars/jane.jpgIf a file you use shows up as an orphan, a source is missing. Add it and scan again.
5. Preview the clean
php artisan orphan:cleanThis is a dry run. It lists up to 15 of the files it would move (-v lists all of them) and changes nothing.
6. Clean
php artisan orphan:clean --forceThe files move to .orphan-trash/public/{today's date}/ with their original paths. If something was moved by mistake:
php artisan orphan:restore avatars/jane.jpgAfter 30 days, orphan:purge-trash deletes the trash for good. See Scheduling to run all of this weekly.