longestdrive / laravel-maintenance-tools
Artisan commands for Laravel housekeeping: clean temp files and old logs on a schedule, find duplicate classes, repair the migrations table and find legacy @test methods.
Package info
github.com/longestdrive/laravel-maintenance-tools
pkg:composer/longestdrive/laravel-maintenance-tools
Fund package maintenance!
Requires
- php: ^8.3
- illuminate/contracts: ^11.0||^12.0||^13.0
- laravel/sail: ^1.44
- spatie/laravel-package-tools: ^1.16
Requires (Dev)
- larastan/larastan: ^3.0
- laravel/pint: ^1.14
- nunomaduro/collision: ^8.1.1
- orchestra/testbench: ^11.0||^10.0||^9.0
- pestphp/pest: ^3.0||^4.0
- pestphp/pest-plugin-arch: ^3.0||^4.0
- pestphp/pest-plugin-laravel: ^3.0||^4.0
- phpstan/extension-installer: ^1.3
- phpstan/phpstan-deprecation-rules: ^2.0
- phpstan/phpstan-phpunit: ^2.0
- phpunit/phpunit: ^12.0||^11.5
- spatie/laravel-ray: ^1.35
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
A set of Artisan commands for keeping a Laravel application tidy during development and deployment.
Laravel apps collect clutter over time: temporary upload folders fill up, rotated log archives pile up in storage/logs, copied classes leave duplicate names, and the migrations table drifts out of sync with the migration files. This package gives you a command for each of these jobs. It can also schedule the clean-up commands for you, so housekeeping runs without any extra cron entries.
Features
| Command | What it does |
|---|---|
clean:tempfiles |
Empties the temporary directories you configure |
clean:logs |
Deletes archived log files older than a set number of days |
scan:duplicates |
Finds duplicate PHP class names and file names in a folder |
migration:repair |
Adds migration files missing from the migrations table so they're marked as run |
scan:nonTestMethods |
Finds test methods that rely on the @test docblock annotation |
clean:tempfiles and clean:logs are scheduled to run weekly by default. You can change or turn off the schedule in the config file.
Requirements
- PHP 8.3+
- Laravel 11, 12 or 13
Note: Laravel 11 is end-of-life and no longer gets security fixes. It's still supported here, but upgrading your application to Laravel 12 or 13 is strongly recommended.
Installation
Install the package via Composer:
composer require longestdrive/laravel-maintenance-tools
The service provider is registered automatically through Laravel package discovery.
To change the defaults, publish the config file to config/maintenance-tools.php:
php artisan vendor:publish --tag="laravel-maintenance-tools-config"
Configuration
The published config file looks like this:
return [ // Directories emptied by clean:tempfiles 'temp_files' => [ storage_path('temp'), storage_path('app/temp'), ], // File extension clean:logs looks for in storage/logs 'log_file_extension' => '.gz', // Days of log archives clean:logs keeps (overridable with --days) 'log_retention_days' => 30, // Automatic scheduling (see "Scheduling" below) 'schedule' => [ 'clean_temp_files' => [ 'enabled' => true, 'frequency' => 'weekly', 'day' => 'monday', 'time' => '01:00', ], 'clean_old_logs' => [ 'enabled' => true, 'frequency' => 'weekly', 'day' => 'monday', 'time' => '02:00', ], ], ];
Usage
clean:tempfiles
Removes all files and subdirectories inside each directory listed in maintenance-tools.temp_files. The directories themselves are kept.
php artisan clean:tempfiles
If a configured directory doesn't exist, or a file can't be removed, the command logs an error and exits with a non-zero status. That makes it safe to use in deployment scripts.
Warning: everything inside the configured directories is deleted. Only list directories that hold disposable files.
clean:logs
Deletes log files in storage/logs that match maintenance-tools.log_file_extension (default .gz) and were last modified longer ago than maintenance-tools.log_retention_days (default 30). It's meant for compressed log archives left behind by log rotation. Your active .log files are left alone.
The retention period from the config also applies to scheduled runs. Pass --days to override it for a single run.
# Use log_retention_days from the config (default 30) php artisan clean:logs # Keep the last 7 days php artisan clean:logs --days=7
scan:duplicates
Recursively scans a folder for PHP files that share a class name or file name. This is handy for catching copy-paste leftovers or classes that will clash once namespaces are flattened.
php artisan scan:duplicates app
The folder is relative to your project root. Results are written to a numbered report, e.g. storage/logs/duplicate_scan_1.log:
Duplicate class names:
UserService:
- /var/www/app/Services/UserService.php
- /var/www/app/Legacy/UserService.php
Duplicate file names:
Helpers.php:
- /var/www/app/Support/Helpers.php
- /var/www/app/Http/Helpers.php
migration:repair
Compares the files in database/migrations with the migrations table. Any migration missing from the table is inserted into a new batch, which marks it as already run.
php artisan migration:repair
Use this when the schema is already in place but the migrations table isn't, for example after importing a database dump or restoring from a backup. Afterwards, php artisan migrate won't try to re-run those migrations.
Warning: this command does not run any migrations. It only records them as run. Make sure the schema really matches before you use it. The
migrationstable must already contain at least one entry.
scan:nonTestMethods
Scans every PHP file under tests/ and lists public methods that are marked as tests only by a @test docblock annotation, rather than a test name prefix.
php artisan scan:nonTestMethods
PHPUnit 12 no longer reads docblock annotations, so these tests are silently skipped. Use the report to find them and either rename them with a test prefix or add the #[Test] attribute. Results are written to a numbered report, e.g. storage/logs/non_test_methods_1.log:
Class: UserTest in /var/www/tests/Feature/UserTest.php
- it_creates_a_user
- it_deletes_a_user
Scheduling
The package registers clean:tempfiles and clean:logs with Laravel's scheduler. By default they run every Monday, at 01:00 and 02:00 respectively. Laravel's scheduler must be running for this to work:
* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1
Each entry under schedule in the config supports:
enabled:trueorfalsefrequency:daily,weekly,monthly,quarterly,yearlyorcustomday: day of the week, forweeklyonlytime: 24-hourHH:MMcron: a cron expression, forcustomonly
'clean_old_logs' => [ 'enabled' => true, 'frequency' => 'custom', 'cron' => '0 2 * * 1,4', // 2:00 AM on Mondays and Thursdays ],
To see the registered tasks, run php artisan schedule:list. For more examples, see SCHEDULING.md.
Testing
composer test
Changelog
Please see CHANGELOG for more information on what has changed recently.
Security Vulnerabilities
If you discover a security vulnerability, please email raygun.crane@gmail.com rather than opening a public issue.
Credits
Built on spatie/laravel-package-tools.
License
The MIT License (MIT). Please see License File for more information.