Getting Started

Install the package:

composer require visavi/cleanup

Publish its configuration. Check the package service provider or README for the exact tag, then inspect config/cleanup.php:

php artisan vendor:publish --tag=cleanup-config

Confirm the actual Artisan signature before scheduling it:

php artisan list | grep -i cleanup
php artisan help cleanup

Open config/cleanup.php first. The important settings are usually:
- enabled cleanup targets: cache, sessions, logs, temp files
- retention periods in days/hours
- custom cleanup paths
- exclusions or protected paths
Run it manually once in a safe environment:

php artisan cleanup -v

If the command supports a dry run, use that first:

php artisan cleanup --dry-run

First practical use case: schedule a nightly cleanup of stale logs and temporary files:

// routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::command('cleanup')
    ->dailyAt('02:30')
    ->withoutOverlapping()
    ->onOneServer();

Keep the first rollout conservative: enable only logs and temp-file cleanup, keep retention generous, then tighten after observing disk usage and command output.

Implementation Patterns

Schedule by target and cadence

If the command exposes target options, avoid one giant cleanup run for everything. Use separate schedules with different retention windows:

Schedule::command('cleanup --logs --days=30')
    ->dailyAt('02:00')
    ->withoutOverlapping();

Schedule::command('cleanup --temp --days=7')
    ->hourly()
    ->withoutOverlapping();

Schedule::command('cleanup --sessions --days=2')
    ->dailyAt('03:00')
    ->withoutOverlapping();

Confirm the actual option names with php artisan help cleanup. If the command only supports config-driven cleanup, create separate config profiles or use environment-specific config values instead.

Keep retention policy in config, not in code

Prefer configuration over hard-coded values:

// config/cleanup.php
return [
    'logs' => [
        'enabled' => true,
        'days' => env('CLEANUP_LOG_DAYS', 14),
    ],
    'temp' => [
        'enabled' => true,
        'days' => env('CLEANUP_TEMP_DAYS', 7),
    ],
    'paths' => [
        storage_path('app/tmp'),
        storage_path('framework/cache/data'),
        // Add app-specific scratch directories here.
    ],
];

This lets ops tune retention per environment without a deployment.

Add application-specific paths safely

Use the package for application scratch data, generated exports, old queue payloads, or temporary uploads only after verifying the path is not user-facing or permanent:

'paths' => [
    storage_path('app/exports/tmp'),
    storage_path('app/imports/tmp'),
    storage_path('framework/testing'),
],

Keep permanent storage such as storage/app/public out of cleanup paths unless you have a very explicit retention policy.

Wire into deployment and maintenance workflows

Useful patterns:

Run cleanup after a deployment that generates temporary assets.
Run cleanup manually during incident response when disk usage is high.
Add a health check or alert if the cleanup command exits non-zero.
Capture output in your scheduler logs and review it weekly.

Example deployment hook:

php artisan cleanup --temp --logs -v

Test with temporary storage

In tests, point cleanup paths at a fake disk or temporary directory and assert both deletion and preservation:

use Illuminate\Support\Facades\Storage;

Storage::fake('local');
Storage::disk('local')->put('tmp/old.txt', 'old');
Storage::disk('local')->put('tmp/new.txt', 'new');

$this->artisan('cleanup --temp --days=1')
    ->assertExitCode(0);

Storage::disk('local')->assertMissing('tmp/old.txt');
Storage::disk('local')->assertExists('tmp/new.txt');

Adjust the command signature to match the package.

Combine with Laravel’s native maintenance commands

Use the package for retention-based pruning, and Laravel’s built-in commands for framework-specific resets:

php artisan cache:clear
php artisan view:clear
php artisan cleanup --logs --temp

Do not duplicate responsibilities blindly. For example, Laravel’s log rotation may already handle daily logs; the package is more useful for aged files, temp directories, and custom application paths.

Gotchas and Tips

Confirm the command signature first. Package docs and command names vary. Run php artisan list | grep cleanup and php artisan help <command> before adding scheduler entries.
Treat cleanup as destructive. Start with logs and temp paths only. Run manually with verbose output and, if available, a dry-run flag before enabling schedules.
Check path normalization. Ensure configured paths are absolute or resolved with storage_path()/base_path(). Avoid relative paths whose meaning depends on the current working directory.
Do not follow symlinks casually. If cleanup recursively deletes directories, a symlink in a temp path can point somewhere unexpected. Verify the package’s traversal behavior or keep cleanup paths free of symlinks.
Retention is usually based on modification time. A file copied recently may look “new” even if its content is old. Conversely, touching files can postpone cleanup indefinitely.
Config cache matters. After editing config/cleanup.php, run php artisan config:clear in local/staging. In production, deploy with the normal config:cache process.
Scheduler requires cron. Schedule::command(...) does nothing without Laravel’s scheduler running. Confirm the server has the standard * * * * * php artisan schedule:run entry.
Use withoutOverlapping() and onOneServer() deliberately. onOneServer() requires a shared cache store. If the cache is file-based, it will not provide cross-server coordination.
Watch for stale overlap locks. A crashed cleanup can leave an overlap lock. If the command stops running, inspect the cache lock or use Laravel’s schedule lock-clearing commands.
Check permissions and ownership. A command run by cron may execute as a different user than PHP-FPM. Files created by the web user may not be deletable by the CLI user, or vice versa.
Avoid deleting active files. Sessions, file cache, and logs may be written while cleanup runs. Keep retention windows large enough that active files are not candidates.
Session and cache drivers change the target. If sessions use Redis or the database, deleting session files is pointless. If cache uses Redis, file-cache cleanup will not reclaim memory. Align config with actual drivers.
Protect framework directories. Be careful with storage/framework/cache, storage/framework/sessions, and storage/logs if the application is under load. Prefer Laravel-native commands for these unless the package explicitly supports safe pruning.
Log the result. Scheduler output is easy to miss. Capture command output to a file or external monitor, and alert on non-zero exit codes.
Test exclusions. If the package supports excluded paths or filename patterns, add tests that prove protected files survive cleanup.
Look for extension points in the service provider. If the package allows custom cleanup targets or callbacks, prefer registering those over modifying vendor code. Otherwise, schedule application-specific cleanup as separate Artisan commands or closures.
Keep a manual escape hatch. Document a safe manual command such as php artisan cleanup --logs --temp -v for on-call use when disk usage spikes.

Cleanup Laravel Package