Download the PHP package angelleger/laravel-response-cache without Composer

Laravel Response Cache

Key-based full response caching for Laravel 10+ applications. The package stores complete GET/HEAD responses in the configured cache store using deterministic keys. It offers a small helper API, middleware, and artisan commands for managing cached responses without relying on cache tags.

Requirements

• PHP 8.2 or higher
• Laravel 10.x

Installation

Configuration

config/response_cache.php

Configuration Notes

• ttl: default time-to-live for cached responses when no explicit value is supplied.
• store: cache store to use; null uses the application's default store.
• key_prefix: string prepended to every cache key and route index entry.
• guest_only: when true, authenticated users are skipped unless the middleware parameter auth=true is provided.
• vary_on_headers / vary_on_cookies: header and cookie names that should contribute to the cache key.
• include_query_params: if non-empty, only these query parameters are considered when building the key.
• ignore_query_params: query parameters to discard; supports a trailing * wildcard.
• status_whitelist: response status codes eligible for caching.
• max_payload_kb: maximum size of the response body; larger responses are bypassed.
• etag: toggle automatic generation of an ETag header when caching.
• lock_seconds / lock_wait: when lock_seconds > 0, generation is wrapped in an atomic lock to prevent cache stampedes.
• debug: when enabled, exposes additional debug headers.

Cache Key Strategy

Keys follow the pattern:

The query segment is created by sorting parameters, removing ignored keys, and injecting vary_on_headers/vary_on_cookies values as pseudo parameters (h_header / c_cookie). The active authentication guard name (or guest) and the request locale are appended to avoid collisions.

Middleware

Apply the resp.cache middleware to any GET/HEAD route that should be cached.

Middleware Parameters

• ttl=<seconds> – override the default TTL for this route.
• auth=true – cache authenticated responses even if guest_only is enabled.

Responses are cached only when:

• The HTTP method is GET or HEAD.
• The response status code appears in status_whitelist.
• The response size does not exceed max_payload_kb (when set).
• The request does not contain Cache-Control: no-store.

Cached responses include an X-Cache: HIT header for debugging. You can disable caching on a per-request basis by sending Cache-Control: no-store from the client or controller.

Helper API

• makeKey(Request $request, array $overrides = []) – build the cache key used for the request.
• rememberResponse(Request $request, Closure $callback, DateTimeInterface|int $ttl) – return the cached response or execute the callback and store the result.
• forgetByKey(string $key) – remove a cached response.
• forgetRoute(string $routeName) – remove all cached responses for the route (uses a bounded key index, max 1000 entries).

Artisan Commands

• response-cache:clear – clear by exact key or by route name (uses the internal index).
• response-cache:stats – show basic cache information such as the underlying driver.

Caveats

• The package uses key-based invalidation only; cache flush() is intentionally avoided because it clears unrelated data.
• Streamed responses or those not meeting cache rules (status, size, etc.) are skipped automatically.
• Route indexes are capped to the most recent 1000 keys to remain memory safe.
• Use caution when changing configuration in production; mismatched prefixes or stores can orphan keys.

License

MIT