Cache Plugin Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: The saloonphp/cache-plugin (v3.1.0) remains aligned with response caching for Saloon v4+, targeting architectures requiring rate-limited API optimization, expensive endpoint caching, or read-heavy workloads. The plugin’s middleware-layer design ensures clean separation between HTTP logic (Saloon) and caching, maintaining low coupling.
• Layered Fit: Ideal for microservices, API gateways, or CLI tools where HTTP responses are idempotent and slow. Less suitable for real-time systems or write-heavy workflows.
• Saloon v4+ Specificity: Explicit Saloon v4 support (per release notes) may limit backward compatibility with older Saloon versions, requiring version pinning in composer.json.

Integration Feasibility

• Low-Coupling Design: Integration via withCache() or middleware hooks remains minimalistic, requiring no architectural refactoring.
• Dependency Requirements:
  • Saloon v4+ (now mandatory per v3.1.0).
  • PSR-16 Cache (e.g., predis/predis, php-cache/cache-item-pool).
  • PHP 8.1+ (implied by Saloon v4’s requirements).
• Backward Compatibility:
  • Breaking Change Risk: v3.1.0’s Saloon v4 exclusivity may force dependency updates if using older Saloon versions.
  • MIT License: Permissive reuse, but long-term maintenance remains uncertain (12 stars, no active community).

Technical Risk

• Plugin Maturity:
  • No major changes in v3.1.0 (only Saloon v4 support), but lack of community activity persists.
  • Production Risk: Untested at scale; bug stability unproven.
• Configuration Complexity:
  • Cache key generation (TTL, invalidation) still requires custom logic for edge cases.
  • Race conditions possible if not using atomic cache operations (e.g., remember()).
• Testing Overhead:
  • Mocking PSR-16 caches in unit tests adds complexity.
  • Edge cases: Stale data, cache stampedes, or distributed cache partitions (e.g., Redis cluster splits).

Key Questions

1. Saloon Version Lockdown
   • Are we blocked on Saloon v4? If not, is this plugin worth the dependency upgrade risk?
   • What’s the migration path from Saloon v3 to v4?
2. Cache Strategy Validation
   • Is TTL-based invalidation sufficient, or do we need event-driven invalidation (e.g., webhooks)?
   • How will cache keys handle dynamic query parameters (e.g., /users?role=admin)?
3. Failure Mode Mitigation
   • What’s the fallback if the cache fails (e.g., circuit breaker + retry)?
   • How will stale data be detected/alerted (e.g., ETag validation)?
4. Observability Gaps
   • Are cache metrics (hit/miss rates) critical for monitoring?
   • Will distributed tracing (e.g., OpenTelemetry) track cache interactions?
5. Alternatives Revisited
   • Could Saloon’s built-in retry logic or OPcache suffice for simpler use cases?
   • Is a dedicated reverse proxy (e.g., Varnish) more maintainable long-term?

Integration Approach

Stack Fit

• Best For:
  • PHP 8.1+ apps using Saloon v4+.
  • Rate-limited APIs (e.g., Stripe, Twilio) or expensive endpoints (e.g., weather APIs).
  • CLI/batch jobs with repetitive HTTP calls.
• Poor Fit:
  • Real-time systems (e.g., WebSockets) where stale data is unacceptable.
  • Write-heavy APIs (caching adds no value).
  • Monolithic apps with embedded HTTP logic (better to use Nginx caching).

Migration Path

1. Pre-Migration Check:
   • Verify Saloon v4 compatibility (check composer.json constraints).
   • Audit current Saloon usage to identify cacheable endpoints.
2. Proof of Concept (PoC):
   • Integrate for one non-critical endpoint (e.g., /products).
   • Test with Redis (recommended) and filesystem backends.
   • Measure cache hit ratio and latency improvements.
3. Gradual Rollout:
   • Phase 1: Cache read-only, idempotent endpoints.
   • Phase 2: Add cache invalidation for mutable data (e.g., /user/profile).
   • Phase 3: Optimize TTL and key strategies via metrics.
4. Fallback Strategy:
   • Implement circuit breakers (e.g., saloonphp/circuit-breaker) for cache failures.
   • Use feature flags to toggle caching during rollout.

Compatibility

• Saloon Version:
  • Mandatory: v4+ (v3.1.0 drop support for older versions).
  • Action Required: Update composer.json:

    "saloon/saloon": "^4.0",
    "saloonphp/cache-plugin": "^3.1"
    

• Cache Backends:
  • Supported: PSR-16 (Redis, Memcached, APCu).
  • Unsupported: Database caches (requires custom adapter).
• Middleware Conflicts:
  • Ensure no Saloon middleware conflicts (e.g., auth vs. caching order).
  • Test priority (cache should run after auth but before logging).

Sequencing

1. Dependency Update:

   composer require saloonphp/cache-plugin:^3.1 predis/predis
   

2. Configuration:

   // Global cache setup (Redis example)
   $cache = new PredisClient(['scheme' => 'tcp', 'host' => 'redis']);
   Saloon::withCache($cache);
   
   // Per-request caching
   $response = $request->withCache()->send();
   

3. Cache Key Customization (if needed):

   $request->withCache()->withCacheKeyFn(
       fn () => 'custom_' . $request->endpoint . '_' . md5($request->queryParams)
   );
   

4. Invalidation Logic:
   • For mutable data, delete cache post-write:

     $request->withCache()->send(); // Write operation
     Cache::delete('key_for_' . $request->endpoint);
     

Operational Impact

Maintenance

• Pros:
  • Reduced API costs (fewer calls to rate-limited endpoints).
  • Lower latency for cached responses.
• Cons:
  • Cache management overhead:
    • Manual invalidation may require cron jobs or event listeners.
    • TTL tuning needed to avoid stale data.
  • Plugin updates: Risk of breaking changes if Saloon evolves post-v4.

Support

• Debugging Challenges:
  • Cache-related issues (e.g., "Why is data stale?") require knowledge of:
    • TTL settings.
    • Key collision risks.
    • Cache backend health (Redis restarts).
  • No official docs: Limited community support may slow troubleshooting.
• Tooling Gaps:
  • No built-in cache visualization (e.g., RedisInsight integration).
  • No native health checks for cache dependencies.

Scaling

• Performance:
  • Positive: Cache reduces latency and origin API load.
  • Negative: Cache stampedes possible with short TTLs (many requests hit cache miss simultaneously).
• Horizontal Scaling:
  • Distributed caches (Redis Cluster) required for multi-server setups.
  • Local caches (APCu) may cause inconsistencies in distributed apps.
• Cost:
  • Reduces API costs but adds cache infrastructure costs (e.g., Redis hosting).

Failure Modes