Statamic Advanced Invalidator Laravel Package

Getting Started

This is a Statamic addon, not a standalone Laravel package — it only earns its keep once static caching is enabled. If you are on a plain Laravel app with no Statamic install, stop here.

1. Install into a Statamic 4/5 site:

   composer require visuellverstehen/statamic-advanced-invalidator
   

   v1.1.0 exists primarily to declare Laravel 12 compatibility; the feature surface is unchanged from 1.0.x. If your app is still on Laravel 10/11 you gain nothing by upgrading, but there is also no known downside.

2. Turn static caching on in config/statamic/static_caching.php (strategy => 'full' or 'half'). Without it the addon has nothing to invalidate.

3. Publish and read the config file (check the README for the exact publish tag — addon tag conventions vary):

   php artisan vendor:publish --provider="Visuellverstehen\AdvancedInvalidator\ServiceProvider"
   

4. First use case: you have a blog collection with a listing page at /blog. Statamic core invalidates the entry's own URL (/blog/my-post) on save, but not the listing, the taxonomy term pages, or the homepage teaser. That gap is exactly what this addon closes — declare the extra URIs per collection and let it handle the fan-out.

Look at the config file first, then the addon's invalidation class(es). Everything day-to-day is config, not code.

Implementation Patterns

Rule-per-collection. The dominant pattern: map a collection handle to the URIs that must be flushed whenever an entry in it changes. Listing pages, paginated variants, taxonomy term pages, and any "latest posts" block on the homepage belong in that list. Treat the config as the source of truth and review it whenever you add a new listing route.

Dynamic segments. Hardcoded URI lists rot. Prefer rules that resolve from the entry being saved — its slug, its date archive segments, its taxonomy values — so /blog/2024/06 and /tags/laravel are derived rather than enumerated. Where the addon only supports static strings, keep a small custom invalidator (see extension points) rather than a 40-line array.

Piggyback on the save lifecycle. Invalidation should run on the same events that Statamic uses for its own static cache work — published, unpublished, deleted, and (importantly) unpublished transitions, since an entry disappearing from a listing is as much a cache problem as one appearing. Verify the unpublish path explicitly; it is the most commonly missed case in production.

Multisite fan-out. If you run multiple sites, an entry in one site frequently appears in another site's listings. Either scope rules per site or write rules that invalidate across all sites for shared listings. Test with two sites pointed at the same collection before trusting it.

CDN purge tail. A common integration is: let the addon delete the local static files, then hook the result to purge a CDN (Cloudflare, Fastly, Netlify). Keep that in a listener or a queued job rather than inside the invalidation rules, so a slow CDN call never blocks an editor's save.

Testing pattern. Feature-test the behaviour rather than the internals: enable static caching in the test environment, warm the cache, save an entry via Entry::make()->save(), and assert the expected static files are gone. This catches config typos, which are the actual failure mode.

Gotchas and Tips

• Nothing happens without static caching enabled and warmed. The single most common "the addon is broken" report is a dev environment where static_caching is off. Check that first, every time.
• config:cache in production. Deployment pipelines that cache config will happily serve a stale rule set. Add php artisan config:cache after publishing or editing the addon config, and confirm the change took effect.
• Release metadata is inconsistent on this one. The notes are headed v1.1.0 but the changelog link compares v1.0.2...v1.0.3, and the only listed change is the Laravel 12 constraint bump plus a first-time contributor. Before upgrading, verify the actual tag on Packagist and read the composer.json constraint — don't infer the supported Statamic/Laravel matrix from the heading.
• No deprecations, no breaking changes signalled. The only entry is chore: support laravel 12, which is additive. A routine composer update on an existing site is low risk; pin if you have a policy of not taking minor bumps unattended.
• URI format matters. Rules are matched against request paths, not full URLs — leading slash, no domain, no trailing slash unless your routes actually produce one. A rule with https://example.com/blog will silently never match.
• Strategy differences. full caching stores whole responses and deletion is file-based; half caches fragments and invalidation behaves differently at the edges. If invalidation "works in staging but not prod", compare the strategy before the rules.
• Cache driver assumptions. The addon's file deletion assumes the default local static cache path. If you have moved the static cache to a different store or a custom path, verify deletions still land where you expect.
• Debugging recipe. Temporarily log inside the invalidation path, reproduce a save, and compare the resolved URI list against what you expected, then check the filesystem under the static cache directory (path varies by strategy — public/static for full caching). Nine times out of ten the list is right and the URIs are wrong.
• Extension points. Where the config schema runs out, register your own invalidation logic as a listener on Statamic's entry/term/global save events, or subclass the addon's invalidator, rather than forking. Forking a small addon is tempting but leaves you owning a Laravel 13 compatibility bump later.
• Watch the upstream repo. With a single maintenance-level change and a first-time contributor in this release, keep an eye on the issue tracker — if Laravel 13 or Statamic 6 needs a constraint bump, it may not arrive quickly, and that is a planning risk for long-lived sites.