Stale Cache Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle:

   composer require bedrockstreaming/stale-cache-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Bedrock\StaleCacheBundle\BedrockStaleCacheBundle::class => ['all' => true],
   ];
   

2. Configure a Stale Cache Service (config/packages/bedrock_stale_cache.yaml):

   bedrock_stale_cache:
       decorated_cache_pools:
           app.stale_cache:  # Service ID for your stale cache
               cache_pool: cache.app  # Underlying cache pool (e.g., Symfony's default)
               max_stale: 3600       # Stale period in seconds (1 hour)
   

3. First Use Case: Replace a cache service dependency in your controller/service with the new stale cache:

   use Symfony\Contracts\Cache\CacheInterface;
   
   public function __construct(
       private CacheInterface $staleCache // Inject 'app.stale_cache'
   ) {}
   

Implementation Patterns

Workflow Integration

1. Tag-Aware Caching: If your cache implements TagAwareCacheInterface, leverage it for invalidation:

   $this->staleCache->deleteTag('product_123');
   

2. Graceful Degradation: Use stale cache for non-critical data (e.g., product listings, user profiles) where stale data is acceptable temporarily.

3. Layered Caching: Combine with Symfony’s cache pools (e.g., cache.app for primary storage, app.stale_cache for fallback):

   # config/packages/cache.yaml
   framework:
       cache:
           pools:
               app.stale_cache: ~  # Auto-configured by the bundle
   

4. Dependency Injection: Prefer constructor injection for stale cache services to ensure consistency:

   public function __construct(
       private CacheInterface $staleCache,
       private CacheInterface $fallbackCache
   ) {}
   

5. Contextual Stale Logic: Override get() to conditionally use stale cache based on runtime logic:

   $item = $this->staleCache->get('key', function() {
       return $this->fetchExpensiveData();
   }, 3600); // TTL
   

Gotchas and Tips

Pitfalls

1. Error Handling:

   • Only errors extending Bedrock\StaleCacheBundle\Exception\UnavailableResultException trigger stale fallback.
   • Custom exceptions must be explicitly whitelisted in the bundle’s config (check src/Exception/UnavailableResultException.php for reference).

2. Debugging:

   • Enable enable_debug_logs: true to trace stale cache hits/misses and regeneration failures.
   • Logs appear in debug channel; filter with:

     bin/console debug:logs --channel=debug | grep StaleCache
     

3. Configuration Quirks:

   • No Nested Stale Caches: Avoid wrapping another stale cache service—it may cause infinite regeneration loops.
   • TTL vs. Stale Period: The max_stale setting extends the TTL, not replaces it. Example:
     • TTL: 300s, max_stale: 3600s → Item is stale after 300s but usable until 3900s total.

4. Performance:

   • Stale cache adds overhead for regeneration checks. Benchmark with:

     bin/console debug:cache
     

Extension Points

1. Custom Exceptions: Extend UnavailableResultException for domain-specific errors:

   class DatabaseUnavailableException extends UnavailableResultException {}
   

2. Regeneration Hooks: Override the bundle’s StaleCacheItem to inject custom logic:

   // src/StaleCache/StaleCacheItem.php
   class CustomStaleCacheItem extends \Bedrock\StaleCacheBundle\StaleCache\StaleCacheItem {
       protected function regenerate(): mixed {
           // Custom logic here
           return parent::regenerate();
       }
   }
   

3. Dynamic Stale Periods: Use a closure in config (requires custom bundle extension):

   max_stale: "%kernel.debug% ? 60 : 3600"  # Debug mode = 1m, prod = 1h
   

4. Testing: Mock the stale cache in tests to verify fallback behavior:

   $this->staleCache->shouldReceive('get')
       ->once()
       ->andThrow(new UnavailableResultException('Test failure'));