feat!: derive invalidation from what pages read, not from configuration

[Bahbv]

Invalidation is now derived from what pages actually read, instead of from rules describing what they might read. There is no configuration left to write.

Why

The 1.x design kept a hand-maintained map of block types and field handles that had to mirror the templates. It drifted silently. Two examples from meerdervoort's own config: a comment recording that /projecten and /vacatures invalidated nothing because the URIs no longer resolved, and a ['collection' => 'articles', 'field' => 'author'] rule that existed purely to patch a hole the block index had by construction — it only ever read $entry->get('pagebuilder'), so an entry's author, category, hero fieldset and Bard entry links were invisible to it.

The template already knows what it renders. v2 observes that rather than restating it.

How it works

While a page renders, reads are recorded as tags against its URL when it enters the static cache: entry:{id}, collection:{handle}, term:{taxonomy}::{slug}, taxonomy:{handle}, global:{handle}, form:{handle}. On save the changed item resolves to the same tags and every URL carrying one is cleared.

The distinction that keeps it targeted: a query pinned to ids or a uri records only those items, so a reusable block embedded on three pages clears exactly those three. Any other query also records a list tag for its scope, because an entry created tomorrow has an id that is in no tag set yet — that is what clears a "latest three articles" carousel.

Nesting is free. A reusable block's reads are the embedding page's reads at any depth, so a page embedding a block that pulls in a global and another entry carries all three dependencies.

Breaking changes

• Every rule key is gone: pagebuilder_collections, collection_entry_rules, collection_urls, globals_flush_all, navs_flush_all, collection_trees_flush_all, forms_flush_all, global_target_blocks, global_urls, taxonomy_target_blocks, taxonomy_urls.
• The block index and its supporting classes are removed, along with customEntryUrls().
• The cache is no longer flushed wholesale for globals, navigations, form blueprints or collection trees. URLs are invalidated individually so nocache regions survive. A navigation save still clears every cached URL — a reorder changes links in shared layout and no per-page dependency can express that — but it clears rather than flushes.

Upgrade path

Nothing is required beyond composer update. Delete the rule keys from config/cache_invalidation.php when convenient; cache-invalidation:doctor lists any still present.

A statamic.static_caching.invalidation.class pinned at ContentDependencyInvalidator can stay — the addon recognises its own class names and upgrades the pin, so a site that pins the removed class does not fatal. A subclass of your own is still respected.

Expect one round of broad invalidation after deploying, while the graph fills.

Also fixed

• Invalidator::refresh() is honoured. DefaultInvalidator flips a protected flag before delegating to invalidate(), which 1.x overrode without checking, so static_caching.background_recache hard-purged instead of refreshing.
• Relations rendered outside the pagebuilder field now invalidate.
• Form blueprint saves clear the pages rendering that form instead of the entire site.

New

cache-invalidation:why, :affected, :stats, :clear and :doctor. affected answers "what clears if I save this?" before saving — the question the 1.x design could not be asked. doctor exits non-zero when invalidation cannot work, so a broken environment fails a deploy instead of quietly serving stale pages.

CacheTags::add() / ::invalidate() and @cachetags(...) cover data reaching a template from outside Statamic's repositories, where nothing observes the read and nothing knows when it changes.

Verification

82 tests, 149 assertions. Recording is asserted through real queries against real content and invalidation through real save events, including one test that drives a real HTTP request through Statamic's frontend and cache middleware.

That choice is not stylistic. Three defects were found only because the tests refused to use synthetic inputs, and each would have shipped silently:

1. Every rendered page depended on every collection. Statamic resolves each frontend request through findByUri(), an unscoped where('uri', ...) query, so the list-tag rule marked every page as depending on every collection — any entry save anywhere cleared the whole cache, quietly degrading the addon to the behaviour it replaces. Only a real HTTP render exposed it.
2. config:cache broke the addon entirely. mergeConfigFrom is a no-op with cached config, so a site that followed the install instructions — which say there is nothing to publish — had no config namespace at runtime, an empty sqlite path, and a queued invalidation job that threw. Pages stayed stale and nothing reported it.
3. Reusable blocks over-invalidated. The entries fieldtype augments through a StatusQueryBuilder whose status filter adds a nested clause only when the queried ids resolve, so a query built from invented ids looked simple and the buggy rule passed. With real content it leaked a list tag.

The suite was mutation-checked rather than assumed to bite: removing the untracked safety net, the nav clear-all branch, the overflow tag, the graph lookup or getItemUrls each fails exactly the tests that should catch it.

Not covered

• Assets are not tracked; saving one clears nothing extra, matching 1.x.
• Globals are not scoped per site, so on a multisite install saving one clears the pages that read it across every site. Over-invalidation, not staleness.
• Concurrency has not been exercised under load. WAL is enabled on the sqlite driver.
• Not yet run on a production site with a real queue worker — that is the intended next step before tagging.