Statamic Widget Cache Controller Laravel Package

Getting Started

composer remove webographen/statamic-widget-cache-controller   # only if coming from v2
composer require stoffelio/statamic-widget-cache-controller
php artisan vendor:publish   # pick the stoffelio cache-controller config tag

The addon is auto-discovered by Statamic — no manual provider registration in config/app.php or config/statamic/providers.php. After install, clear caches (php artisan cache:clear, and php artisan config:clear if you use config:cache in this environment) and reload the Control Panel dashboard to confirm the widgets still render.

First places to look:

1. vendor/stoffelio/statamic-widget-cache-controller/README.md — the authoritative source for the config keys and the widget API in this exact version.
2. vendor/stoffelio/statamic-widget-cache-controller/src/ — the service provider (to see which config/view namespaces are registered) and any Widget base class you are meant to extend.
3. config/stoffelio/… after publishing — this is where TTLs and enable/disable flags live.

First use case: the dashboard widget that calls a slow third-party API (analytics, Stripe, an external status feed). Those are the ones that make the CP feel broken at 9am. Cache them, leave the native Statamic widgets (content stats, recent entries) alone — they are already cheap and benefit more from being live.

Implementation Patterns

Wrap only the expensive part. Keep the widget class doing its Statamic work (title, icon, permissions, view) and let the cache controller wrap just the data fetch. Structure widgets so the expensive call is a single method/action you can cache and forget — that makes invalidation trivial later.

Per-widget TTL, not a global one. A "deploys today" widget wants 60s; a "monthly revenue" widget is happy with an hour. Set the default in config, then override per widget so the blast radius of a wrong number is one widget.

Namespace your cache keys. Include the things that change the answer: site/locale for multisite, and user ID or role for anything scoped to a person. A shared key on a per-user widget is the classic way this package leaks one editor's data to another. If a widget genuinely can't be keyed safely, turn caching off for it.

Invalidate from Statamic events rather than waiting for TTL. If a widget shows entry counts or "recently published", hook Statamic\Events\EntrySaved / EntryDeleted (and the Term/Asset equivalents) and forget the relevant keys. TTLs then become a backstop, not the primary mechanism.

Warm the cache out-of-band. The first CP load after a cold cache is as slow as no caching at all. A small scheduled command (->dailyAt('07:45') or every 15 minutes) that renders/forgets the hot widgets means the first editor in each morning isn't the one paying for it.

Be deliberate with drivers. File cache is fine single-server; on multi-server CP deployments use Redis so every node sees the same values, otherwise each node warms independently and invalidation only hits one. Never ship with the array driver and conclude the addon is broken — it works per-request and looks like it does nothing.

View overrides go to resources/views/vendor/stoffelio/. Publish-then-tweak is the extension point for markup; resist editing anything under vendor/ since the next composer update eats it.

Gotchas and Tips

v3 is a pure rename — but it is still breaking if you customised anything. The PHP namespace is now Stoffelio\CacheController\ and the view namespace is stoffelio::. Concretely:

• Any use Webographen\CacheController\... in your own widget classes must become Stoffelio\CacheController\....
• Any view('webographen::...') reference must become view('stoffelio::...').
• Move overridden views: resources/views/vendor/webographen/ → resources/views/vendor/stoffelio/. If you don't, your custom markup silently stops being used and you get the package default — which reads as a "bug in v3" but isn't.

Remove the old package before requiring the new one. If both are installed you get two service providers registering overlapping config and view namespaces; the failure mode is confusing (whichever registers last wins). After the swap, run composer dump-autoload — stale webographen classes in the autoloader produce "class not found" errors that survive a page refresh.

statamic:stache:clear does not clear this. The stache is Statamic's content index; widget cache lives in the Laravel cache store. Debugging "my widget won't refresh" with stache commands wastes an afternoon. Use php artisan cache:clear (destructive — clears everything) or target the specific keys/tags. If you're on a taggable store (Redis, Memcached), tag your widget keys from day one and you'll be able to clear one widget instead of the whole app cache.

Config changes require a config cache bust in any environment running config:cache — including most deploys. A TTL change that "didn't take" is almost always this.

Permission checks belong outside the cached blob. Cache the data, not the authorisation decision. If you cache rendered HTML that includes a permission gate, a role change won't reflect until TTL expiry. Cache raw values and gate at render time.

Don't cache the widgets that must be live — system status, active updates, "who's online". Caching those turns a monitoring tool into a source of false confidence.

Debugging stale data: check the config TTL for that widget first, then whether an event listener is forgetting the key, then whether the cache store is actually shared across your web nodes. Add a timestamp to the widget view during development; if the timestamp moves, the cache isn't being hit and the problem is upstream (key mismatch, driver, TTL of zero).

Extension points worth knowing: the published config (TTLs, enable flags), the widget view via the stoffelio:: namespace, and your own Statamic event listeners for invalidation. Those three cover most real requirements without subclassing anything.