Simplytestable Pagecache Bundle Laravel Package

Getting Started

Install the package via Composer and confirm the service provider is auto-discovered:

composer require vendor/package

Look first at the CacheableResponseFactory class and its createResponse() signature. The second argument is the array of parameters used to derive a unique cache hash for the request. Start with a simple public listing endpoint, keying the response by the request’s filters, pagination, and locale:

use Vendor\Package\CacheableResponseFactory;

public function index(Request $request, CacheableResponseFactory $factory)
{
    return $factory->createResponse($request, [
        'page' => $request->integer('page', 1),
        'filters' => $request->only(['status', 'sort']),
        'locale' => app()->getLocale(),
    ]);
}

The first useful scenario is caching expensive read-only endpoints where the same response can be served for the same parameter set. If you omit the parameters array, the factory will likely hash only the request (or nothing), so make the key explicit from day one.

Implementation Patterns

Use explicit, stable parameter arrays. The release adds support for null, arrays, and objects implementing __toString() or JsonSerializable, so you can pass richer values directly:

$response = $factory->createResponse($request, [
    'user' => $request->user(),          // Eloquent model implements JsonSerializable
    'team' => $team,                     // Eloquent model
    'filters' => $request->only(['status', 'sort']),
    'page' => $request->integer('page', 1),
    'include_archived' => $request->boolean('archived') ?: null,
]);

Prefer building a dedicated method that normalizes parameters before passing them in. This keeps controllers readable and makes cache keys predictable:

protected function cacheParameters(Request $request): array
{
    return [
        'user_id' => $request->user()?->id,
        'filters' => $request->only(['status', 'sort']),
        'page' => $request->integer('page', 1),
    ];
}

Use the factory in controllers, invokable actions, or a small response-caching middleware. For personalized endpoints, include a user or tenant identifier in the parameter array; otherwise all users share the same cached response. For route model binding, pass the model’s primary key rather than the model object unless you intentionally want model state to invalidate the cache:

'post' => $post->id,
// or, if the whole model state should invalidate the cache:
'post' => $post,

When testing, call the endpoint twice with identical parameters and assert the same response. For the new object support, add a test that passes a JsonSerializable DTO and an object with __toString() to confirm the cache key remains stable.

Gotchas and Tips

• Objects passed as parameters must implement __toString() or JsonSerializable. Passing any other object will likely throw an exception or produce an invalid key. Validate your parameter array before calling createResponse().
• null is now accepted, but null and '' may hash differently. Pick one representation per logical value and stay consistent.
• Array order matters in the derived hash. If you pass an associative array built from request input, normalize the key order first if order is not semantically meaningful.
• Eloquent models implement JsonSerializable, so passing a model works, but jsonSerialize() includes visible attributes, timestamps, and may change after unrelated updates. Prefer IDs or explicit attribute arrays for stable keys.
• __toString() implementations must be deterministic. Avoid including random values, object hashes, or memory addresses.
• Debug cache misses by logging the normalized parameter array and comparing it between requests. The common culprits are unordered arrays, null versus empty string, and model timestamps.
• Do not cache responses that set cookies, session data, or user-specific flash messages unless the parameter array fully differentiates the responses.
• If the package exposes a customization point for hashing or normalization, use it to enforce deterministic ordering. Otherwise, wrap the factory in your own service and normalize before delegating.
• Be careful with array_filter() on parameters: filtering out null values changes the cache key. Apply it intentionally and document the behavior for your team.