Core Laravel Package

Getting Started

1. Install the package with Composer and run its install command. In v1.1.2 the install command also registers the orphan sweeper in the scheduler, so check the generated schedule entry rather than adding it manually.
2. Publish and review the package config before running migrations. The sweeper’s grace period, batch size, storage disk, and model/resource mappings are the settings you are most likely to need to tune.
3. Run migrations, then verify the schedule was registered with php artisan schedule:list. In Laravel 11+ this is typically in routes/console.php or bootstrap/app.php; in older applications it may be in app/Console/Kernel.php.
4. Look first at the raw-delete cleanup documentation added in v1.1.2. That section explains the core problem: Eloquent deletes fire model events and can clean up related files automatically, but raw deletes bypass those events. The orphan sweeper is the safety net for those cases.
5. First use case: create a record with an associated file, delete the database row with a raw query such as DB::table('posts')->where('id', $id)->delete(), then run the sweeper manually and confirm the orphaned file is removed. This gives you a quick end-to-end verification of the package’s main workflow.

Implementation Patterns

• Use normal Eloquent deletes where possible. Model observers and package integrations handle cleanup immediately. Reserve raw deletes for bulk operations, imports, maintenance scripts, or performance-sensitive paths, and rely on the sweeper to reconcile the leftovers.
• Run the sweeper on a schedule for raw-delete paths. With v1.1.2 the install command wires this up automatically for new installs. For existing applications, add the command to the scheduler explicitly and confirm it appears in schedule:list.
• Run the sweeper manually after risky maintenance. Bulk deletes, data migrations, tenant offboarding, and one-off cleanup scripts are good candidates for an immediate php artisan sweeper run rather than waiting for the next scheduled pass.
• Keep a grace period. Configure the sweeper to ignore recently created or recently modified records so files that are still being referenced, uploaded, or processed are not removed prematurely.
• Scope the sweeper in multi-tenant applications. If the package supports tenant or model scoping, run the sweeper per tenant or ensure its queries are constrained. A global sweep in a shared database can be expensive and harder to reason about.
• Test raw-delete paths explicitly. Use Storage::fake() and a test that performs a raw delete, runs the sweeper, and asserts the file is gone. This is the most valuable regression test for this package because it covers the failure mode the sweeper exists to handle.
• Integrate with deployment and CI carefully. v1.1.2 removes a deployment script from the project structure. If your pipeline referenced that script, replace it with your own deployment steps and continue running migrations and scheduler checks as usual.
• Monitor sweeper output. Log deleted orphan counts and failures. A sudden spike usually means a raw-delete path is bypassing expected cleanup, while zero deletions over time may mean the scheduler is not running or the grace period is too aggressive.

Gotchas and Tips

• Auto-scheduling only applies during install. Existing applications upgrading to v1.1.2 will not automatically gain the schedule entry. Check schedule:list after upgrading and add the entry manually if it is missing.
• Re-running the install command can duplicate schedule entries. Inspect the scheduler file after reinstalling or re-publishing rather than assuming the command is idempotent.
• The scheduler requires a running cron or queue worker. Registering the sweeper does not run it. Confirm schedule:run is invoked every minute in production and that the scheduler is not silently disabled in local or staging environments.
• Raw deletes inside transactions can race the sweeper. If a transaction deletes rows and the sweeper runs before commit, the sweeper may not see the orphaned rows. Prefer running the sweeper after the transaction commits.
• Beware of overlapping sweeper runs. Large tables can make a sweep take longer than the scheduled interval. Use withoutOverlapping() or a suitable lock to prevent concurrent sweeps.
• Grace periods protect against false positives. A very short grace period can delete files that are still referenced by in-flight uploads or queued jobs. A very long one leaves storage growing. Tune this against your upload and job latency.
• Configuration caching can hide changes. After editing sweeper config or schedule settings, run php artisan config:clear and php artisan schedule:list to verify the effective configuration.
• Soft deletes need deliberate handling. A soft-deleted model still has a database row, so the sweeper may not treat its files as orphaned. Decide whether soft-deleted records should retain files until force deletion.
• The removed deployment script is a pipeline concern, not a runtime one. Search your CI configuration, Dockerfiles, and operational runbooks for references to the old script and replace them with your own deployment commands.