Filament Clear Cache Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require cms-multi/filament-clear-cache
   

2. Register the plugin in your Panel configuration (e.g., app/Providers/Filament/AdminPanelProvider.php):

   use CmsMulti\FilamentClearCache\FilamentClearCachePlugin;
   
   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               FilamentClearCachePlugin::make(),
           ]);
   }
   

3. Publish config (optional):

   php artisan vendor:publish --provider="CmsMulti\FilamentClearCache\FilamentClearCacheServiceProvider"
   

First Use Case

• After installation, a trash-can icon appears in the Filament admin toolbar.
• Clicking it triggers optimize:clear (default), clearing Laravel's cache (config, route, view, etc.).
• A success notification appears, and the UI refreshes automatically.

Implementation Patterns

Core Workflow

1. Default Usage:

   • The plugin adds a toolbar button that executes Artisan::call('optimize:clear') on click.
   • No additional code is needed for basic functionality.

2. Conditional Activation:

   • Restrict visibility to specific environments (e.g., local, staging):

     FilamentClearCachePlugin::make()
         ->enabled(app()->environment(['local', 'staging']))
     

3. Custom Commands:

   • Extend functionality by adding custom Artisan commands in a service provider:

     use CmsMulti\FilamentClearCache\Facades\FilamentClearCache;
     
     public function boot()
     {
         FilamentClearCache::addCommand('page-cache:clear');
         FilamentClearCache::addCommand('route:clear');
     }
     

   • Note: Commands must be registered before the plugin is used.

4. Dynamic UI Updates:

   • Use Livewire events to update the button's cache count badge:

     // Livewire v3+
     $this->dispatch('clearCacheIncrement')->to(\CmsMulti\FilamentClearCache\Http\Livewire\ClearCache::class);
     

Integration Tips

• Filament Panels: Works seamlessly with Filament v3, v4, and v5.
• Multi-Panel Apps: Register the plugin in each panel separately if needed.
• Localization: Supports translations (e.g., German via config/filament-clear-cache.php).
• Testing: Mock the FilamentClearCache facade to test cache-clearing logic:

  $this->mock(FilamentClearCache::class)
       ->shouldReceive('clearCache')
       ->once();
  

Gotchas and Tips

Pitfalls

1. Command Execution:

   • The plugin runs Artisan commands synchronously. For large caches, this may cause UI lag.
   • Workaround: Use --queue flag for async execution (requires custom command setup).

2. Livewire Caching:

   • Livewire components may retain cached state after clearing. Force a refresh with:

     $this->dispatch('refresh')->to(YourComponent::class);
     

3. Environment Mismatches:

   • The plugin defaults to optimize:clear. If you override commands, ensure they’re compatible with your Laravel version (e.g., route:clear may not exist in older versions).

4. Button Visibility:

   • The button hides automatically on "simple pages" (e.g., login screens) by default (v3.0.3+). Override in config:

     'visible' => true, // Force-show on all pages
     

Debugging

• Check Commands: Verify registered commands with:

  php artisan list --show-hidden
  

• Logs: Enable Laravel debug mode (APP_DEBUG=true) to inspect cache-clearing output.

Extension Points

1. Custom Styling:

   • Override the button’s Blade template by publishing assets:

     php artisan vendor:publish --tag="filament-clear-cache-views"
     

   • Modify resources/views/vendor/filament-clear-cache/clear-cache.blade.php.

2. Event Listeners:

   • Listen for cache-clearing events (e.g., cache-cleared) via Laravel’s event system:

     event(new CacheClearedEvent());
     

3. Permissions:

   • Restrict access using Filament’s policy system:

     FilamentClearCachePlugin::make()->visible(fn () => auth()->user()->can('clear-cache'));
     

Pro Tips

• Environment-Specific Commands: Dynamically add commands based on the environment:

  if (app()->environment('production')) {
      FilamentClearCache::addCommand('cache:clear --tags=production');
  }
  

• Cache Count Badge: Customize the badge logic by extending the Livewire component:

  use CmsMulti\FilamentClearCache\Http\Livewire\ClearCache as BaseClearCache;
  
  class CustomClearCache extends BaseClearCache
  {
      public function getCacheCountAttribute()
      {
          return Cache::stats()['total'] ?? 0;
      }
  }
  

  Then bind it in your panel:

  FilamentClearCachePlugin::make()->livewire(CustomClearCache::class);