Cache Plugin Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require saloonphp/cache-plugin
   

   Register the plugin in your Saloon HTTP client:

   use Saloon\Plugins\CachePlugin;
   
   $client = new YourHttpClient([
       CachePlugin::class,
   ]);
   

2. First Use Case Cache a simple GET request with a 5-minute TTL:

   $response = $client->send(new GetUserRequest('123'));
   $response->cached(); // Check if cached
   $response->fresh(); // Force fresh request
   

3. Where to Look First

   • Plugin Documentation (if available)
   • CachePlugin::class source code in src/Plugins/CachePlugin.php
   • Default config in config/saloon.php (if published)

Implementation Patterns

Common Workflows

1. Basic Caching

   $response = $client->send(new GetPostsRequest());
   // Automatically cached with default TTL (e.g., 1 hour)
   

2. Custom TTL per Request

   $request = new GetUserRequest('123');
   $request->withCacheTTL(300); // 5 minutes
   $response = $client->send($request);
   

3. Conditional Caching

   $request = new GetUserRequest('123');
   $request->shouldCache(function ($request) {
       return $request->userId !== 'admin';
   });
   

4. Cache Invalidation

   $client->send(new InvalidateUserCacheRequest('123'));
   // Or manually:
   Cache::forget("saloon_{$request->endpoint()}_{$request->userId}");
   

Integration Tips

• Laravel Cache Config: Ensure config/cache.php is properly configured (e.g., file, redis, or database driver).
• Request Deduplication: Use requestId() or endpoint() to avoid duplicate cached entries for similar requests.
• Debugging: Enable Saloon\Plugins\CachePlugin::DEBUG_MODE to log cache hits/misses.

Gotchas and Tips

Pitfalls

1. Cache Key Collisions

   • Default cache key format: saloon_{endpoint}_{requestId}.
   • Override with cacheKey() in your request:

     public function cacheKey(): string {
         return "custom_key_{$this->userId}";
     }
     

2. TTL Misconfiguration

   • Default TTL is null (no caching). Always explicitly set TTL:

     $request->withCacheTTL(60); // 1 minute
     

3. Stale Data in Distributed Systems

   • Use Cache::rememberForever() for immutable data (e.g., static configs).
   • Prefer shorter TTLs for volatile data (e.g., user sessions).

4. Race Conditions

   • CachePlugin uses Cache::get()/Cache::put(), which are atomic in Laravel.
   • For critical sections, use Cache::lock() if needed.

Debugging

• Log Cache Events:

  CachePlugin::setDebugMode(true);
  // Check logs for `CachePlugin` entries.
  

• Clear Cache:

  php artisan cache:clear
  

  Or programmatically:

  Cache::flush();
  

Extension Points

1. Custom Cache Store Override the default store in the plugin config:

   'cache' => [
       'store' => 'redis', // or 'database', 'memcached'
   ],
   

2. Cache Events Listen for cache hits/misses:

   CachePlugin::onCacheHit(function ($response) {
       Log::info("Cache hit for {$response->request()->endpoint()}");
   });
   

3. Pre-Cache Responses Use Cache::put() manually before sending requests:

   Cache::put($request->cacheKey(), $data, $ttl);