Laravel Trash Cleaner Laravel Package

Getting Started

Minimal Steps

1. Installation: Run composer require omaralalwi/laravel-trash-cleaner to add the package to your Laravel project.
2. First Command: Execute php artisan trash:clean to immediately clean debug files (Clockwork, Debugbar) and compiled caches.
3. Check Config: Review the published config at config/trash-cleaner.php (after running php artisan vendor:publish --tag=laravel-trash-cleaner) to verify default paths.

First Use Case

Use this package post-deployment or in a CI/CD pipeline to ensure no stale debug files or caches persist in production. Example:

# Run in a deploy script or cron job
php artisan trash:clean --debug --force

• --debug shows verbose output.
• --force skips confirmation prompts.

Implementation Patterns

Core Workflows

1. Scheduled Cleanup Add to app/Console/Kernel.php to run nightly:

   protected function schedule(Schedule $schedule)
   {
       $schedule->command('trash:clean')->dailyAt('2:00');
   }
   

   • Useful for automated maintenance.

2. Post-Deployment Hook Integrate with Laravel Forge/Envoyer or custom scripts:

   # Example in a deploy script
   php artisan trash:clean --assets --force
   

   • --assets clears frontend build directories (e.g., public/build).

3. Custom Cleanup Logic Extend the package by binding your own cleanup logic:

   // app/Providers/TrashCleanerServiceProvider.php
   public function boot()
   {
       TrashCleaner::extend('custom', function () {
           // Add your custom cleanup logic here
           File::delete(storage_path('custom-cache/*.cache'));
       });
   }
   

   Then call:

   php artisan trash:clean --custom
   

Integration Tips

• Laravel Telescope: Automatically clean Telescope entries by adding storage/framework/views and database/telescope_entries to the paths array in config.
• Frontend Assets: Use --assets flag to trigger rebuilds (if configured) after cleaning:

  php artisan trash:clean --assets --rebuild
  

  • Requires npm, yarn, or pnpm to be installed on the server.

Gotchas and Tips

Pitfalls

1. Permission Issues

   • Ensure the Laravel storage directory (storage/) has writable permissions (chmod -R 755 storage/).
   • Debugbar/Clockwork folders may require 775 permissions for group access.

2. Missing Dependencies

   • If using --assets --rebuild, verify npm, yarn, or pnpm is installed and accessible in the PATH.
   • Example error: Command "npm run dev" not found → Install Node.js or configure the correct path in trash-cleaner.php.

3. Overzealous Cleaning

   • Avoid running trash:clean during development if you rely on cached views or debug files.
   • Use --dry-run to preview files before deletion:

     php artisan trash:clean --dry-run
     

4. Config Overrides

   • If paths in trash-cleaner.php are misconfigured, the package may silently skip directories.
   • Validate paths with:

     php artisan trash:clean --debug
     

Debugging

• Verbose Output: Use --debug to see which files are being processed.
• Log Errors: Check storage/logs/laravel.log for permission or path-related issues.
• Custom Logging: Extend the package to log cleanup events:

  TrashCleaner::extend('log', function () {
      Log::info('Custom cleanup triggered', ['action' => 'log_cleanup']);
  });
  

Extension Points

1. Custom Directories Add new directories to the paths array in trash-cleaner.php:

   'paths' => [
       storage_path('logs'),
       storage_path('framework/views'),
       // Add your custom path
       base_path('custom-cache'),
   ],
   

2. Pre/Post Hooks Use Laravel’s registering and booting events in a service provider to run logic before/after cleanup:

   TrashCleaner::registering(function () {
       // Pre-cleanup logic (e.g., backup files)
   });
   
   TrashCleaner::booting(function () {
       // Post-cleanup logic (e.g., notify Slack)
   });
   

3. Conditional Cleanup Dynamically enable/disable cleanup based on environment:

   // In a service provider
   if (app()->environment('production')) {
       TrashCleaner::enable();
   }