Cache Plugin Laravel Package

Technical Evaluation

Architecture fit

• Pros:
  • Aligns with Laravel’s PSR-6/PSR-18 ecosystem (e.g., Symfony HttpClient, Guzzle 6+ via php-http/guzzle7-adapter).
  • Leverages Laravel’s built-in caching (e.g., Illuminate\Cache\CacheManager) via PSR-6 adapters (e.g., predis/predis for Redis, cache/array-adapter for testing).
  • Supports ETag/Last-Modified validation (RFC 7234), reducing redundant API calls for immutable resources (e.g., public APIs, CDN assets).
  • Blacklist/whitelist paths via regex (blacklisted_paths) enables fine-grained control (e.g., exclude /auth or /webhooks).
  • Cache listeners (e.g., AddHeaderCacheListener) add observability without custom middleware.
• Cons:
  • No Laravel-specific optimizations: Requires manual PSR-6 adapter setup (e.g., wrapping Laravel’s cache manager in a PSR-6 pool).
  • Stream handling: Detaches streams to avoid serialization warnings (v1.8.0+), but may complicate large payloads (e.g., file downloads).
  • ETagCachePlugin (v2.1.0+) adds complexity for use cases needing strict ETag-only caching (e.g., versioned API responses).

Integration feasibility

• High for Laravel projects using:
  • HTTPlug-compatible clients (e.g., php-http/guzzle7-adapter, symfony/http-client).
  • PSR-6 cache pools (e.g., Redis, Memcached, or cache/array-adapter for testing).
• Low for:
  • Projects using raw Guzzle v5 (requires HTTPlug migration).
  • Custom caching logic (e.g., file-based caching without PSR-6).

Technical risk

• Minor:
  • Dependency stability: Actively maintained (PHP 8.1–8.5, Symfony 5–8, PSR-6 v1–3).
  • Backward compatibility: Deprecations clearly documented (e.g., respect_cache_headers → respect_response_cache_directives).
• Moderate:
  • Stream detachment: May impact memory usage for large responses (mitigated by CacheKeyGenerator customization).
  • Cache invalidation: Relies on Cache-Control headers; requires manual TTL management for non-HTTP-cached data (e.g., database-backed APIs).
• Critical:
  • No Laravel-specific tests: Unclear how it handles Laravel’s request lifecycle (e.g., middleware, service container).
  • ETagCachePlugin: Limited adoption (introduced in v2.1.0); validate use case before adoption.

Key questions

1. Laravel compatibility:
   • Does the plugin conflict with Laravel’s HTTP middleware (e.g., App\Http\Middleware\HandleCors)?
   • How does it interact with Laravel’s Cache facade (e.g., Cache::remember)?
2. Performance:
   • What’s the overhead of stream detachment/reattachment for large responses (e.g., >1MB)?
   • How does it handle conditional requests (e.g., If-None-Match) in Laravel’s request pipeline?
3. Observability:
   • Can X-Cache headers be logged via Laravel’s LogResponse middleware?
   • Are there metrics for cache hit/miss rates (e.g., Prometheus integration)?
4. Edge cases:
   • How does it handle failed cache writes (e.g., Redis connection drops)?
   • Does it support cache warming (preloading responses at startup)?
5. Alternatives:
   • Compare with Laravel’s built-in Cache::remember() or packages like spatie/laravel-cache-control.

Integration Approach

Stack fit

• Laravel-native components:
  • HTTP Clients: Works with:
    • symfony/http-client (via php-http/symfony-client-adapter).
    • Guzzle 7+ (via php-http/guzzle7-adapter).
    • Laravel’s Http facade (if wrapped in HTTPlug).
  • Cache Backends: Compatible with Laravel’s PSR-6 adapters:
    • Redis (predis/predis or phpredis/phpredis).
    • Memcached (php-memcached/memcached).
    • File system (cache/file-adapter).
    • Database (cache/db-adapter).
• Non-native:
  • Avoid if using Guzzle v5 or raw cURL without HTTPlug.

Migration path

1. Adopt HTTPlug (if not already using it):

   composer require php-http/guzzle7-adapter symfony/http-client
   

   Wrap Laravel’s Http client:

   use Http\Client\Common\Plugin\PluginStack;
   use Http\Client\Common\Plugin\PluginClient;
   use Http\Client\Common\Plugin\CachePlugin;
   use Http\Client\Common\Plugin\Cache\CachePool;
   
   $client = new PluginClient(
       new PluginStack(ClientDiscovery::find()),
       [
           new CachePlugin(new CachePool(new PredisAdapter()))
       ]
   );
   

2. Configure Laravel’s cache manager as PSR-6:

   use Cache\Adapter\Redis\RedisCachePool;
   use Illuminate\Support\Facades\Cache;
   
   $redis = Cache::store('redis')->getConnection();
   $cachePool = new RedisCachePool($redis);
   

3. Integrate with Laravel services:
   • Replace Http::get() with the cached client:

     $response = $cachedClient->sendRequest(new Request('GET', 'https://api.example.com/data'));
     

   • Use dependency injection to inject the cached client into services.

Compatibility

• PHP: 8.1–8.5 (Laravel 10+).
• Laravel: Tested with Symfony 5–8 (Laravel 8–11).
• PSR Standards:
  • PSR-6 (Cache), PSR-17 (Stream), PSR-18 (HTTP Client).
• Known conflicts:
  • Guzzle v6: Use php-http/guzzle6-adapter (deprecated in favor of v7).
  • Custom middleware: Ensure middleware respects Cache-Control headers.

Sequencing

1. Phase 1: Validate with a non-critical API (e.g., public weather data).
2. Phase 2: Implement blacklisted paths for sensitive endpoints.
3. Phase 3: Add cache listeners for observability (e.g., X-Cache headers).
4. Phase 4: Optimize TTLs based on cache hit/miss metrics.

Operational Impact

Maintenance

• Pros:
  • MIT license: No vendor lock-in.
  • PSR standards: Future-proof against HTTP client changes.
  • Laravel-friendly: Uses existing cache drivers (Redis, etc.).
• Cons:
  • No Laravel-specific support: Issues require community/HTTPlug maintainers.
  • Cache invalidation: Manual TTL tuning needed for non-HTTP-cached data.
  • ETagCachePlugin: Limited documentation; validate with tests.

Support

• Debugging:
  • Use cache_listeners to log hits/misses:

    $plugin = new CachePlugin($cachePool, [
        'cache_listeners' => [new AddHeaderCacheListener()]
    ]);
    

  • Check X-Cache headers in responses (e.g., X-Cache: HIT).
• Fallbacks:
  • Disable caching for critical paths via blacklisted_paths.
  • Use default_ttl => 0 to disable caching entirely.

Scaling

• Horizontal scaling:
  • Stateless: Cache backend (Redis/Memcached) handles distribution.
  • Cold starts: Pre-warm cache for high-traffic endpoints (e.g., cron job).
• Performance:
  • Benchmark: Compare latency with/without caching (e.g., ab or Laravel Forge).
  • Memory: Stream detachment adds ~100–200B overhead per response (negligible for most use cases).

Failure modes

Ramp-up

• Onboarding:
  • Documentation: Link to [php