Skip to content

Using it from code ​

The Artisan commands are thin wrappers around the OrphanFiles facade. You can call the same methods from a controller, a job or a test.

php
use Erag\OrphanFiles\Facades\OrphanFiles;
use Erag\OrphanFiles\Support\Data\CleanOptions;
use Erag\OrphanFiles\Support\Data\ScanOptions;

Scan ​

php
$report = OrphanFiles::scan(new ScanOptions(disks: ['s3']));

$report->totals();
// ['files' => ..., 'referenced' => ..., 'orphans' => ..., 'protected' => ...,
//  'cleanable' => ..., 'total_bytes' => ..., 'orphan_bytes' => ..., 'reclaimable_bytes' => ...]

ScanOptions takes three optional arguments:

ArgumentDefaultMeaning
disksnullDisks to scan. null scans every disk in config/orphan-files.php.
directoriesnullNarrow the scan to these folders. They have to sit inside the configured directories.
minimumAgeMinutesnullReplaces grace_period_hours for this run.

A scan only reads. It fires the OrphanScanCompleted event when it finishes.

Clean ​

php
OrphanFiles::clean(new CleanOptions(mode: 'trash', dryRun: false));

CleanOptions defaults to dryRun: true, so OrphanFiles::clean() with no arguments only reports what it would do. Pass dryRun: false to move files.

ArgumentDefaultMeaning
scannew ScanOptionsWhich disks and directories to clean.
modenull'trash' or 'delete'. null uses the mode from config.
limitnullStop after this many files.
dryRuntrueReport only, don't touch storage.
forceRatiofalseSkip the safety threshold.

To clean one disk, pass a ScanOptions as scan:

php
$result = OrphanFiles::clean(new CleanOptions(
    scan: new ScanOptions(disks: ['s3'], directories: ['avatars']),
    dryRun: false,
));

$result->action->processed; // files moved to the trash
$result->action->bytes;     // total size of those files

A real clean throws Erag\OrphanFiles\Exceptions\SafetyThresholdExceeded if more than max_orphan_ratio percent of a disk would go. A dry run doesn't throw; it lists the problem in $result->ratioViolations instead.

Queue it ​

php
OrphanFiles::queueScan();
OrphanFiles::queueClean(new CleanOptions(dryRun: false));

Both dispatch a job to the connection and queue set under queue in the config. queueClean() follows the same dry-run default, so leave out dryRun: false and the job only reports.

Check a single file ​

php
OrphanFiles::explain('avatars/jane.jpg', 'public')->verdict();
// 'referenced', 'protected', 'orphan' or 'missing'

OrphanFiles::isReferenced('public', 'avatars/jane.jpg'); // true or false

explain() accepts a path or a full URL and returns the matching rows as well as the verdict, the same data orphan:explain prints. isReferenced() stops at the first match, so it is the cheaper choice when you only need a yes or no. Neither changes anything.

Trash ​

php
OrphanFiles::restore('public', ['avatars/jane.jpg']);
OrphanFiles::restoreAll('public');
OrphanFiles::purgeTrash('public', retentionDays: 30, dryRun: true);

These match orphan:restore and orphan:purge-trash. Each returns an ActionResult with processed, failed and bytes.

To add sources, extractors, normalizers or filters from a service provider, see Custom extractors, Normalizers and Filters.