Statamic Cache Evader Laravel Package

Getting Started

Statamic Cache Evader lets you keep Statamic's static/stache caching switched on while "punching holes" in a cached page for content that must be rendered fresh per visitor — a cart count, a logged-in username, a price, a stock level. The cached HTML contains a placeholder plus a signed URL; the browser fetches that URL and the package renders just the dynamic partial server-side.

First steps:

1. composer require alpshq/statamic-cache-evader:^1.4 — pin to at least 1.4.1. The signature-verification fix in 1.4.1 is a security patch, not a feature, so there is no reason to install an earlier 1.x.
2. Publish the config: php artisan vendor:publish --tag="statamic-cache-evader-config" (confirm the exact tag with php artisan vendor:publish --list, since the tag name has varied across Alps packages).
3. Read the README section on "dynamic partials" first — the tag handle, the partial-resolution convention, and the signing/expiry options are the three things you need before writing any template code.
4. First use case: take an already-statically-cached layout (e.g. resources/views/layout.antlers.html) and wrap the single header region that shows user state in the package's dynamic tag, then load the page with static caching enabled and confirm the rest of the page is still served from the static cache while the header is fetched separately.

Do not start by converting a whole page into a dynamic partial — the value of this package is that you convert almost nothing.

Implementation Patterns

Hole-punching a cached layout. Keep the dynamic region as small and as low in the DOM as practical. The layout stays statically cached; only the wrapped include is rendered on the signed request. Anything you move inside the tag loses the benefit of static caching, so move only what genuinely varies per user or per request.

Passing context. Treat the parameters you hand to the partial as a public API: they end up encoded in a URL that the browser will send back. Anything sensitive (user IDs used for authorization decisions, prices used for charging) should be resolved server-side from the session, not taken from the URL, even with signature verification in place.

Endpoint hygiene. The render endpoint must not be cached by a CDN or reverse proxy — it returns per-visitor content. Verify the response carries Cache-Control: private, no-store (or that your edge rules exclude the route entirely). This is the most common way this pattern leaks data across users.

Testing. Write two feature tests against the render route: one asserting a properly signed URL returns 200 with the partial's HTML, and one asserting an unsigned URL, a URL with a tampered parameter, and a URL with a modified signature all return 403. That second test is the regression test for exactly the class of bug fixed in 1.4.1 — keep it.

Signed URL generation. If the package exposes a helper or facade for building the URL, use it in your own Blade/Antlers and in any custom JS. Do not hand-assemble the query string; hand-assembly is how projects silently drift into generating unsigned URLs and either break (post-1.4.1) or, before the patch, expose the endpoint.

Gotchas and Tips

• Upgrade 1.4.1 immediately, then verify. This is a signature-bypass fix. Before the patch, rendering URLs for dynamic partials were not properly validated, meaning a crafted URL could reach partial rendering you did not intend. After upgrading, any URL your app was generating without a valid signature will start returning 403 — which is the correct behaviour, but it will surface as "dynamic regions silently stopped loading" rather than a loud error. Open a page with a dynamic region and check the network tab.
• Expiry versus cached HTML. A subtle trap: if a statically cached page embeds a temporary signed URL, the URL can expire before the page's cache entry does, and every visitor after expiry gets a 403. Either use permanent signatures or generate the URL client-side at hydration time. Check the config's expiry setting against your longest static cache TTL.
• APP_KEY rotation. Signed URLs are derived from the app key (or a dedicated key if the package config allows overriding it). Rotating APP_KEY invalidates every outstanding signed URL; on a multi-server deploy, rotate everywhere at once or use the dedicated key so a cache-evader-only rotation is possible.
• Clear everything after the upgrade: php artisan cache:clear && php artisan view:clear && php artisan route:clear && php artisan config:clear, plus php artisan statamic:static:clear — stale cached HTML can still contain old-format URLs, making the patch look like it broke things.
• Debugging the 403. A 403 means the signature is missing, expired, or mismatched (route/query ordering changes will do this). A 404 almost always means partial-name resolution, not security. Check php artisan route:list for the registered render route and confirm your signature middleware is actually in that route's middleware stack.
• Extension points. If you need custom partial lookup or extra middleware on the render route, do it through the published config / service provider bindings rather than by re-registering the route — re-registering is the fastest way to lose the signature middleware the patch depends on.
• Local development. Static caching is typically off in local, so the bug class this package exists to solve does not reproduce there. Test with STATAMIC_STATIC_CACHING_STRATEGY (or the equivalent) set to a full-file strategy in staging before trusting it.