Purge the rendered HTML when a site-wide resource changes (#232)

[silverbackdan]

Closes #232. Front-end counterpart: components-web-app/cwa-nuxt-module#289

The gap

The module tags each cached page with the resource IRIs the render touched, so a write to any of them already drops the affected pages. That misses resources which shape every page without ever entering the module's resource store — site config above all. Change siteName and every cached page kept the old one until its TTL lapsed.

The fix

A write to a class listed in the new http_cache.purge_rendered_html_classes also purges the constant surrogate key cwa-html, which the module puts on every cacheable page. No new endpoint: the bundle already holds the purge connection, it just needed to know which resource types invalidate all rendered pages rather than only their own IRI.

silverback_api_components:
    http_cache:
        personalised_resource_classes: [...]   # existing
        purge_rendered_html_classes:           # new, default [SiteConfigParameter::class]
            - Silverback\ApiComponentsBundle\Entity\Core\SiteConfigParameter

The node mirrors personalised_resource_classes beside it, including is_a(..., true) so subclasses match.

Once per purge, by construction

HttpCachePurger carries a single bool set in collectResource() and appended in propagate(). A bool cannot be added twice, so N listed resources written in one flush produce exactly one tag — a structural guarantee rather than a filter.

Across requests it is once per write. propagate() is bound to postFlush and SiteConfigParameter has no batch operation, so saving four parameters is four requests and four purges. That is harmless — the key is already gone after the first — and coalescing would need cross-request state on a shared service, which is the FrankenPHP worker-mode bug class this codebase has been bitten by before. Deliberately not done.

One correction to the original design during implementation: propagate()'s early return now tests the assembled list rather than $this->tags. With the original ordering, a listed resource whose IRI resolution threw would leave tags empty, return early, and never reset the flag — so the next unrelated flush would spuriously drop the whole HTML cache. Covered by a regression test.

POST on SiteConfigParameter now requires the admin permission

This is a behaviour change for existing applications. #[Post] carried no security: at all — only the application firewall gated it — so any authenticated user could create site config. With the purge tag attached to that write, any authenticated user could also flush the entire HTML cache. It now requires publishable.permission, matching Put/Patch/Delete.

It is securityPostDenormalize:, not security:. AP4 evaluates a plain security expression in the provider stage with no object yet, and SiteConfigParameterVoter::supports() requires $subject instanceof SiteConfigParameter — so a null subject makes every voter abstain, and AffirmativeStrategy denies on all-abstain, locking out admins as well. securityPostDenormalize runs with the denormalized object available.

The existing features/main/security.feature scenarios (anonymous POST → 401, admin POST → 201) both still pass unedited.

The tag is a cross-repo contract

cwa-html, as HttpCachePurger::RENDERED_HTML_TAG. The module asserts the same literal in http-cache.spec.ts. A mismatch fails silently by matching nothing, so it gets the same written-down treatment as explicitAllowOnly and SouinPurger::SEPARATOR.

It is deliberately not namespaced in the kind:value style #227 proposes for manifest keys — those prefixes are a kind qualifying a value, and this tag has no value part, so cwa:html would only look consistent. Collision with a resource IRI is impossible: every collected tag is a path beginning with /.

List only leaf resources — ones not reachable as a Doctrine association of another resource. collectResource() is also reached for associated entities, so a listed class that is reachable as an association would let unrelated writes drop the whole HTML cache. Inert for SiteConfigParameter, which has no associations.

Tests

• PHPUnit: 678 (was 671) — new tests/HttpCache/HttpCachePurgerTest.php, which did not exist before
• Behat: 527 scenarios, 3854 steps (was 522) — new features/main/purge_rendered_html.feature

ProfilerContext::collectPurgedTags() is extracted as a single parser and the existing purge step rebuilt on it, so there is one implementation rather than two. It reads whichever of xkey/surrogate-key is present and splits on /[,\s]+/ — the test harness uses the Varnish xkey purger with space glue while production uses Souin with ', ', so the steps are deliberately header- and separator-agnostic.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.73%. Comparing base (df98167) to head (d9ffc81).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff              @@
##               main     #235      +/-   ##
============================================
+ Coverage     87.70%   87.73%   +0.03%     
- Complexity     2653     2658       +5     
============================================
  Files           257      257              
  Lines          7653     7673      +20     
============================================
+ Hits           6712     6732      +20     
  Misses          941      941              

Flag	Coverage Δ
behat	68.61% <56.52%> (-0.04%)	⬇️
phpunit	35.35% <100.00%> (+0.62%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.