Filament Clear Cache Laravel Package

Getting Started

1. Match the version branch to your Filament major first. This is the single biggest source of "it doesn't work" reports:

On a Filament 3 app, composer require cms-multi/filament-clear-cache will pull 3.x and fail the Filament constraint. Pin explicitly:

composer require cms-multi/filament-clear-cache:^2.1
# or, on Filament 4/5
composer require cms-multi/filament-clear-cache:^3.0

2. Install and publish.

composer require cms-multi/filament-clear-cache
php artisan vendor:publish --provider="CmsMulti\FilamentClearCache\FilamentClearCacheServiceProvider"

Publish early, even if you don't change anything — the session key for the change-counter badge and the command list live there, and having the file in VCS makes config drift visible in code review.

3. Register the plugin in the panel provider (app/Providers/Filament/AdminPanelProvider.php):

use CmsMulti\FilamentClearCache\FilamentClearCachePlugin;

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

Where to look first: config/filament-clear-cache.php (commands + session key), then CmsMulti\FilamentClearCache\FilamentClearCachePlugin (it's tiny), then CmsMulti\FilamentClearCache\Http\Livewire\ClearCache — that component is where the actual Artisan::call() loop and the redirect live, and it's what you'll end up testing.

First use case: the button is a staging/dev convenience that replaces "SSH in, run php artisan optimize:clear, refresh." Ship it gated to non-production on day one:

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

When disabled, the plugin stays registered but the button is not rendered — no fatal errors, no dangling hooks.

Implementation Patterns

Environment gating is the primary knob. enabled() takes a plain bool evaluated at panel-registration time. Since panel() runs during request bootstrapping, avoid auth()->user() inside it on Filament 4/5 — the guard may not be resolved yet, and you'll get inconsistent results between the initial page load and Livewire subsequent requests. Drive it from config/env instead:

FilamentClearCachePlugin::make()
    ->enabled(config('app.clear_cache_button', App::environment('local', 'staging'))),

If you genuinely need per-role access, expose it through a config flag set by an environment variable, or wrap the whole thing behind a Gate checked in a panel middleware / custom policy — there is no built-in authorization hook on this plugin, so don't assume enabled() is a security boundary.

Per-panel registration. The button renders in the panel header, so register it in the panel where operators actually work. If you run both AdminPanelProvider and a staff/AppPanelProvider, register it in both explicitly — it doesn't leak between panels, and "the button is missing on my second panel" is almost always this.

Add your app's own cache commands. optimize:clear alone won't know about your custom caches. Register extra Artisan commands from any service provider's boot():

use CmsMulti\FilamentClearCache\Facades\FilamentClearCache;

public function boot(): void
{
    FilamentClearCache::addCommand('page-cache:clear');
    FilamentClearCache::addCommand('cache:clear');
}

This is the real integration point — it turns the button from a curiosity into "the one way our app clears its caches." Keep the list in one provider (or a dedicated CacheClearServiceProvider) so the button's behavior matches what optimize:clear does in CI.

Badge counter for "cache is stale" awareness. The button tracks a change count (capped at 99+) in a session key defined in config. Your own code can nudge it after a write that invalidates cached output:

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

// Livewire v2
$this->emit('clearCacheIncrement');

In practice this is most useful as a lightweight "something changed since you last cleared" indicator in a CMS workflow — e.g. dispatch it from a saved() hook on a settings resource.

Testing pattern. The Livewire component is testable and small enough to assert on directly:

Livewire::test(\CmsMulti\FilamentClearCache\Http\Livewire\ClearCache::class)
    ->call('clearCache')
    ->assertDispatched('cache-cleared');

Mock Artisan::shouldReceive('call') around it if you want to assert your addCommand() list is being executed in order, rather than actually wiping the test cache store mid-suite.

Gotchas and Tips

The default behavior changed in 2.1.0 — this is the biggest footgun. Historically the button ran optimize:clear; 2.1.0 changed defaults to clear config only to fix an optimize freeze. So on current versions, clicking the button is not equivalent to php artisan optimize:clear. If you need view/route/compiled clearing, add them explicitly:

FilamentClearCache::addCommand('view:clear');
FilamentClearCache::addCommand('route:clear');

Verify by reading config/filament-clear-cache.php in your installed version rather than trusting the README's "optimize:clear is called" line.

Clearing config cache mid-request. After config:clear, Laravel re-reads .env on subsequent requests. If your production setup relies on a cached config for boot speed, or if .env differs from the deployed cached config, one click can silently change application behavior until the next deploy re-caches. Consider not registering config:clear in production panels at all.

Session/cache driver sharing. If SESSION_DRIVER=cache or you use the database/Redis cache store for sessions or rate limiters, clearing the cache can log users out and reset rate-limit counters. Use a distinct cache prefix for application data, or gate the button out of production entirely. Never ship this ungated on a public-facing admin panel.

The full redirect after clearing is intentional. It exists to defeat stale Livewire-cached resources. Don't "fix" it by converting the component to a partial refresh — you'll reintroduce stale asset/navigation state.

Button invisible? Check, in order: (a) plugin registered on that panel, (b) enabled() evaluated to false, (c) 3.0.3+ hides the button on simple pages — a bare Page without a panel header will not show it, (d) Filament version branch mismatch, (e) stale compiled views — php artisan view:clear.

Localization instead of view overrides. The tooltip uses a translation key and ships with a German translation. Customize the label by publishing/overriding the package's lang files rather than overriding the Blade view — the view was touched in 3.0.0 and is the most churn-prone part of the package.

OPcache and queue workers are not cleared. This button clears Laravel caches, not PHP OPcache and not long-running queue:work processes. After a deploy, you still need php-fpm reload and php artisan queue:restart. Don't let the button create a false sense of "everything refreshed."

Debugging what actually ran. Temporarily wrap your addCommand() list or log inside a listener around the Livewire call; the package gives you a success notification but not per-command output. If a command needs parameters, note that parameterized commands were fixed back in v1.0.5 — pass the full command string ('my:cmd --flag') and confirm it works on your branch.

Maturity note for the assessment: 54 stars, zero dependents, one maintainer plus drive-by contributors, and a release cadence dominated by Dependabot bumps. The feature surface is genuinely small (a header action, a Livewire component, a command array), which limits risk — but treat version upgrades as "re-read the changelog," since default-command behavior has changed twice (1.0.1, 2.1.0). It's fine as an internal ops convenience; don't build critical cache-invalidation logic exclusively on top of it, and keep the Artisan equivalents in your deploy scripts as the source of truth.