Filament Cache Plugin Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require mohammedjalal99/filament-cache-plugin
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="MohammedJalal99\FilamentCachePlugin\FilamentCachePluginServiceProvider"
   

2. Enable Plugin Register the plugin in app/Providers/Filament/AdminPanelProvider.php:

   return [
       // ...
       'plugins' => [
           \MohammedJalal99\FilamentCachePlugin\FilamentCachePlugin::make(),
       ],
   ];
   

3. First Use Case

   • Navigate to any Filament admin panel page (e.g., /admin/resources/posts). The plugin will automatically cache the page.
   • Verify caching by inspecting the HTTP response headers for X-Cache: HIT or X-Cache: MISS.

Where to Look First

• Config File: config/filament-cache-plugin.php (adjust cache drivers, TTL, or excluded routes).
• Documentation: Check the GitHub README for advanced usage (e.g., manual cache invalidation).
• Plugin Dashboard: If available, the plugin may add a Filament widget for cache management.

Implementation Patterns

Core Workflows

1. Automatic Caching

   • The plugin auto-caches all Filament pages (Resources, Pages, Widgets) by default.
   • Example: A PostsResource page will cache its list, create/edit forms, and related actions.

2. Manual Cache Invalidation

   • Invalidate cache for specific models or routes:

     use MohammedJalal99\FilamentCachePlugin\Facades\FilamentCache;
     
     // Invalidate cache for a model (e.g., after update)
     FilamentCache::invalidateModelCache(Post::class);
     
     // Invalidate cache for a specific route
     FilamentCache::invalidateRouteCache('/admin/resources/posts');
     

3. Conditional Caching

   • Exclude routes from caching in config/filament-cache-plugin.php:

     'excluded_routes' => [
         'admin/resources/posts/create',
         'admin/pages/*',
     ],
     

4. Cache TTL Customization

   • Override default TTL (e.g., 5 minutes) per route or globally:

     'cache_ttl' => [
         'default' => 300, // 5 minutes
         'admin/resources/posts' => 600, // 10 minutes for Posts
     ],
     

5. Integration with Filament Events

   • Listen to Filament events (e.g., ResourceCreated) to invalidate cache programmatically:

     use Filament\Notifications\Actions\Action;
     use Filament\Resources\Resource;
     
     public static function getPages(): array
     {
         return [
             'create' => CreatePage::make()->afterSave(function (Resource $resource) {
                 FilamentCache::invalidateModelCache($resource::class);
             }),
         ];
     }
     

Advanced Patterns

1. Dynamic Cache Keys

   • Extend the plugin to generate custom cache keys for complex queries:

     FilamentCache::setCustomCacheKey(
         'admin/resources/posts',
         fn () => 'posts_' . request()->query('search')
     );
     

2. Cache Dependencies

   • Use Laravel’s cache tags to invalidate related caches:

     Cache::tags(['posts'])->put('posts_list', $data);
     FilamentCache::invalidateCacheTags(['posts']);
     

3. Partial Page Caching

   • Combine with Filament’s @cache directive for granular control:

     @cache(['key' => 'posts_list'], now()->addMinutes(10))
         {{ $postsTable }}
     @endcache
     

4. Multi-Tenant Caching

   • Scope cache keys by tenant ID:

     FilamentCache::setCachePrefix('tenant_' . auth()->user()->tenant->id);
     

Gotchas and Tips

Pitfalls

1. Cache Staleness

   • Issue: Over-aggressive caching may serve stale data after model updates.
   • Fix: Always invalidate cache post-model changes (e.g., in afterSave hooks).
   • Tip: Use shorter TTLs for frequently updated data (e.g., 1–2 minutes).

2. Route Exclusion Misconfiguration

   • Issue: Accidentally excluding critical routes (e.g., /admin/auth/login).
   • Fix: Test exclusions in a staging environment first. Use wildcards sparingly:

     'excluded_routes' => [
         'admin/auth/*', // Exclude all auth routes
     ],
     

3. Cache Driver Conflicts

   • Issue: Plugin assumes default Laravel cache driver (e.g., file). Custom drivers (e.g., Redis) may need config:

     'cache_driver' => env('CACHE_DRIVER', 'redis'),
     

   • Tip: Verify the driver is listed in config/cache.php.

4. Debugging Cache Hits/Misses

   • Issue: Unclear whether caching is working.
   • Fix: Enable debug mode in config:

     'debug' => true,
     

     Check browser console for FilamentCachePlugin logs or HTTP headers.

5. Plugin Overrides

   • Issue: Conflicts with other caching packages (e.g., Laravel’s built-in @cache directives).
   • Fix: Disable duplicate caching layers or use excluded_routes to avoid overlap.

Debugging Tips

1. Log Cache Events Add to AppServiceProvider:

   FilamentCache::onCacheHit(fn ($key) => \Log::debug("Cache HIT: {$key}"));
   FilamentCache::onCacheMiss(fn ($key) => \Log::debug("Cache MISS: {$key}"));
   

2. Clear Cache Programmatically

   php artisan cache:clear
   

   Or via Tinker:

   FilamentCache::clear();
   

3. Inspect Cache Storage

   • For file driver: Check storage/framework/cache.
   • For Redis: Use redis-cli to inspect keys:

     redis-cli KEYS "filament*"
     

Extension Points

1. Custom Cache Strategies Override the default strategy by binding a custom class:

   $this->app->bind(
       \MohammedJalal99\FilamentCachePlugin\Contracts\CacheStrategy::class,
       \App\Services\CustomCacheStrategy::class
   );
   

2. Add Cache Widgets Extend the plugin to include Filament widgets for cache stats:

   FilamentCachePlugin::make()->widgets([
       \App\Widgets\CacheStatsWidget::class,
   ]);
   

3. Support for Filament Spas If using Filament Spas, configure the plugin to cache API responses separately:

   'spa_routes' => [
       'api/admin/posts',
   ],
   

4. Cache Warmup Pre-load cache during deployment:

   php artisan filament-cache-plugin:warmup