Cache Plugin Laravel Package

Getting Started

Start by installing the package via Composer: composer require php-http/cache-plugin. You’ll also need a PSR-6 cache implementation (e.g., cache/simple-filesystem-adapter) and a PSR-18 HTTP client (or HTTPlug client). Integrate it by wrapping your HTTP client with the CachePlugin, providing a cache pool and a CacheKeyGenerator. For example:

use Http\Client\HttpClient;
use Http\Plug\CachePlugin;
use Http\Plug\Discovery\ClientDiscovery;
use Http\Plug\Discovery\Exception\NotFoundException;
use Cache\Adapter\PHPArray\ArrayCachePool;

try {
    $client = ClientDiscovery::find();
    $cachePool = new ArrayCachePool();
    $cachePlugin = new CachePlugin($cachePool);
    $cachedClient = $cachePlugin->attachTo($client);
} catch (NotFoundException $e) {
    // Handle missing client
}

Your first use case is likely caching GET responses for static API data—this plugin automatically honors Cache-Control headers and implements RFC 7234 validation/revalidation.

Implementation Patterns

• Decorator pattern: Attach CachePlugin to any HTTPlug-compatible client (e.g., Guzzle, Symfony HttpClient) without modifying core client logic.
• Selective caching: Use CacheKeyGenerator or custom CachePolicy to define which requests to cache (e.g., exclude authenticated endpoints). For granular control, pass RequestOptions with custom metadata to override cache behavior per request.
• Invalidate on write: Chain the cache plugin with a custom plugin that clears cache entries after mutation (POST/PUT/PATCH) requests.
• Testing: Swap ArrayCachePool with MemcachedCachePool or Redis-backed pools in production, while using MockPlugin + empty cache for tests.

Gotchas and Tips

• Cache key collisions: Ensure your CacheKeyGenerator includes all relevant request attributes (method, uri, headers, body for POST/PUT) to avoid unsafe caching of non-idempotent requests.
• Stale-while-revalidate: This plugin respects stale-while-revalidate directives—configure TTLs and background revalidation carefully to avoid serving stale data under load.
• Debugging: Enable detailed logging by wrapping the cache pool with a PSR-3 logger-aware decorator (e.g., via Cache\Logger\CacheLogger). Log cache misses and revalidation attempts.
• Extensibility: Extend AbstractCachePolicy to implement domain-specific rules (e.g., ignore query params like utm_*, or force-cache for known-unchanging resources).
• Memory leaks: Avoid long-running processes reusing clients without periodic cache cleanup—define GarbageCollectionPolicy if using filesystem or database-backed pools.