Laravel Page Cache Laravel Package

Getting Started

Install the package with Composer, publish its config if the package exposes one, and register the page-cache middleware on the routes or middleware group you want cached. Start with a small, public, guest-only page such as a marketing or docs route.

Look first at:

1. The package README and published config file — especially cache store, TTL, allowed query parameters, and ignored paths.
2. The middleware registration point — route-level middleware is usually safer than global middleware when you are first evaluating behavior.
3. The cache store used by the package — file, Redis, or database — and how you will clear it during development.

First use case: cache a public GET page for guests, confirm a MISS then HIT via response headers or logs, and verify that authenticated or personalized pages are not cached.

For v1.3.0 specifically: if you use Vite::cspNonce() with laravel-security-headers 2.1+, add a quick smoke test that a cached page still loads its inline scripts under the CSP header. Apps without a CSP nonce need no change.

Implementation Patterns

• Route-scoped caching: Apply the middleware only to explicit public routes or a dedicated web route group. Avoid caching the entire application until exclusions are proven.
• Guest-only caching: Exclude authenticated users, CSRF-heavy forms, flash messages, and session-dependent output. A common pattern is a middleware check for Auth::check() or a custom cache bypass rule.
• Invalidation workflow: Clear or tag the cache when content changes. If the package supports tags, tag by model or section; otherwise use targeted path purging or short TTLs.
• Cache warming: After deployments or content publishes, hit important URLs in a queued job or deploy hook so the first real visitor gets a HIT.
• CSP nonce integration: With laravel-security-headers 2.1+, ensure the page-cache middleware runs before the middleware that builds the CSP header. On a HIT, v1.3.0 restores the nonce that was present in the cached HTML so the later CSP header matches the cached inline scripts.
• Vite nonce usage: Continue using Vite::cspNonce() normally in Blade. The package preserves the rendered nonce in the cached response; do not manually strip or rewrite nonces in cached markup.
• Testing pattern: Add feature tests for MISS then HIT, guest vs. authenticated responses, excluded routes, and — if CSP is enabled — that cached HTML nonces match the emitted CSP header.

Gotchas and Tips

• Middleware order matters for CSP: v1.3.0 assumes the CSP header is built after the page-cache middleware. If your CSP header middleware runs before the page cache, the restored nonce will not be used and inline scripts may be blocked.
• Only nonce-aware apps are affected: Apps without Vite::cspNonce() or without a CSP nonce need no migration. The release is additive; no breaking changes are indicated.
• Do not cache personalized output: User names, carts, notifications, CSRF tokens, and flash messages are common leaks. Prefer explicit allowlists of cacheable routes.
• Watch response headers and cookies: Cached responses can preserve Set-Cookie or other per-request headers if not handled. Verify your cache profile strips or ignores them.
• Query strings can explode the cache: Restrict cache keys to meaningful query parameters and ignore tracking parameters such as utm_*.
• Debugging a suspected nonce mismatch: Inspect the cached HTML for the nonce value, inspect the emitted Content-Security-Policy header, and confirm middleware order. Clear the cache after changing CSP or Vite configuration.
• Invalidation is the usual production issue: Content edits, deploys, and permission changes must clear affected entries. Prefer tag-based invalidation or short TTLs over manual purging.
• Extension points to look for: Custom cache profiles, cache key generators, bypass callbacks, and events around HIT/MISS. These are the safest places to adapt behavior without forking the middleware.