Cache Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require austral/cache-bundle
   

   Register the bundle in config/bundles.php:

   Austral\CacheBundle\AustralCacheBundle::class => ['all' => true],
   

2. Configuration: Publish the default config:

   php bin/console austral:cache:install
   

   Edit config/packages/austral_cache.yaml to define cache pools (e.g., default, redis, memcached).

3. First Use Case: Inject the cache service in a controller or service:

   use Austral\CacheBundle\Cache\CacheInterface;
   
   class MyController extends AbstractController
   {
       public function __construct(private CacheInterface $cache) {}
   
       public function cachedAction(): Response
       {
           $key = 'my_cached_data';
           $data = $this->cache->get($key, fn() => $this->fetchExpensiveData());
   
           return $this->json($data);
       }
   }
   

Implementation Patterns

Core Workflows

1. Tag-Based Invalidation: Use tags to invalidate related cache entries:

   $this->cache->set('user:123', $userData, 'user_data', 3600);
   $this->cache->invalidateTags(['user_data']); // Clears all tagged entries
   

2. Cache Warming: Preload critical data during deployment:

   php bin/console austral:cache:warmup --env=prod
   

3. Cache-Driven API Responses: Combine with Symfony’s ResponseCache middleware for HTTP caching:

   # config/packages/framework.yaml
   framework:
       http_cache:
           cache_control:
               rules:
                   - path: ^/api/
                     headers:
                         cache: ['max_age: 300, public']
   

Integration Tips

• Laravel-Specific: Override the default cache manager to use the bundle’s adapter:

  // config/cache.php
  'default' => env('CACHE_DRIVER', 'austral'),
  

  Extend the bundle’s CacheManager to support Laravel’s cache tags:

  use Austral\CacheBundle\Cache\CacheManager;
  
  class LaravelCacheManager extends CacheManager
  {
      public function getTaggedKeys(string $tag): array
      {
          return Cache::tags($tag)->getKeys();
      }
  }
  

• Event-Driven Invalidation: Listen to CacheInvalidationEvent to trigger side effects:

  use Austral\CacheBundle\Event\CacheInvalidationEvent;
  use Symfony\Component\EventDispatcher\EventSubscriberInterface;
  
  class CacheSubscriber implements EventSubscriberInterface
  {
      public static function getSubscribedEvents(): array
      {
          return [CacheInvalidationEvent::NAME => 'onCacheInvalidate'];
      }
  
      public function onCacheInvalidate(CacheInvalidationEvent $event): void
      {
          if ($event->isTagInvalidation('user_data')) {
              // Log or notify
          }
      }
  }
  

Gotchas and Tips

Pitfalls

1. Tag Naming Collisions: Avoid generic tags like data or content. Use namespaced tags (e.g., user:profile, product:inventory).

2. Redis/Memcached Quirks:

   • Ensure your austral_cache.yaml config matches your server’s actual pool names.
   • Test with php bin/console austral:cache:clear before deploying to avoid stale configs.

3. Laravel Cache API Incompatibility: The bundle doesn’t fully replicate Laravel’s Cache::remember() syntax. Use:

   $this->cache->get('key', fn() => $expensiveOperation, 3600);
   

Debugging

• Check Cache Hits/Misses: Enable debug mode in austral_cache.yaml:

  debug: true
  

  Logs will appear in var/log/dev.log.

• Inspect Stored Keys: Use the debug command:

  php bin/console austral:cache:debug
  

Extension Points

1. Custom Cache Pools: Create a new pool by extending Austral\CacheBundle\Cache\Pool\AbstractPool:

   class CustomPool extends AbstractPool
   {
       protected function getItem(string $key): ?ItemInterface
       {
           // Custom logic (e.g., database fallback)
       }
   }
   

   Register it in austral_cache.yaml:

   pools:
       custom:
           class: App\Cache\CustomPool
   

2. Override Invalidation Logic: Extend Austral\CacheBundle\Cache\CacheManager to add pre/post-invalidation hooks:

   class CustomCacheManager extends CacheManager
   {
       protected function doInvalidateTags(array $tags): void
       {
           // Custom logic (e.g., analytics)
           parent::doInvalidateTags($tags);
       }
   }
   

3. Laravel Service Provider Bridge: Bind the bundle’s cache to Laravel’s container in AppServiceProvider:

   public function register(): void
   {
       $this->app->bind(CacheInterface::class, function ($app) {
           return $app->make('austral.cache.default');
       });
   }
   

Configuration Quirks

• Environment-Specific Pools: Use placeholders in austral_cache.yaml:

  pools:
      default: '%env(CACHE_POOL)%'
  

  Set the env var in .env:

  CACHE_POOL=redis://localhost:6379
  

• Fallback Pools: Define a fallback pool for when the primary fails:

  pools:
      default:
          pool: redis
          fallback: file_system