Cache Plugin Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require saloonphp/cache-plugin
   

   Register the plugin in your Saloon v4 HTTP client:

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

2. First Use Case Cache a simple GET request with a 5-minute TTL (Saloon v4 syntax):

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

3. Where to Look First

   • Plugin Documentation (updated for Saloon v4)
   • CachePlugin::class source in src/Plugins/CachePlugin.php (check for v4 compatibility)
   • Default config in config/saloon.php (if published; verify Saloon v4 config structure)

Implementation Patterns

Common Workflows

1. Basic Caching (Saloon v4)

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

2. Custom TTL per Request (Saloon v4)

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

3. Conditional Caching (Saloon v4)

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

4. Cache Invalidation (Saloon v4)

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

Integration Tips

• Saloon v4 Compatibility: Ensure your HttpClient extends \Saloon\HttpClient (not Saloon\Client).
• Laravel Cache Config: Verify config/cache.php uses a supported driver (e.g., file, redis).
• Request Deduplication: Use endpoint() or requestId() (Saloon v4 methods) to avoid collisions.
• Debugging: Enable CachePlugin::DEBUG_MODE to log cache hits/misses (unchanged).

Gotchas and Tips

Pitfalls

1. Cache Key Collisions (Saloon v4) Default key format: saloon_{endpoint}_{requestId}. Override with cacheKey() in your request (unchanged):

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

2. TTL Misconfiguration (Saloon v4) Default TTL is null (no caching). Explicitly set TTL (unchanged):

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

3. Saloon v4 Breaking Changes

   • Replace cached() → isCached().
   • Replace fresh() → forceFresh().
   • Ensure HttpClient extends \Saloon\HttpClient (not legacy Saloon\Client).

4. Stale Data in Distributed Systems (unchanged) Use Cache::rememberForever() for immutable data or shorter TTLs for volatile data.

Debugging

• Log Cache Events (unchanged):

  CachePlugin::setDebugMode(true);
  

• Clear Cache (unchanged):

  php artisan cache:clear
  

  Or programmatically:

  Cache::flush();
  

Extension Points

1. Custom Cache Store (unchanged) Override in plugin config:

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

2. Cache Events (unchanged) Listen for hits/misses:

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

3. Pre-Cache Responses (unchanged) Manually cache responses:

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