Http Cache Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require datafactory/http-cache-bundle
   

   Enable the bundle in config/bundles.php:

   DataFactory\FOSHttpCacheBundle\DataFactoryFOSHttpCacheBundle::class => ['all' => true],
   

2. Configuration Publish the default config:

   php bin/console fos:http-cache:install
   

   Edit config/packages/datafactory_fos_http_cache.yaml to define:

   • Cache profiles (e.g., short, long).
   • Cache backend (e.g., proxy_client, vary).
   • Invalidation endpoints (e.g., purge_url).

3. First Use Case Cache a route response with a short profile:

   use Symfony\Component\HttpFoundation\Response;
   use DataFactory\FOSHttpCacheBundle\Annotation\Cache;
   
   class MyController
   {
       /**
        * @Cache(profile="short")
        */
       public function index(): Response
       {
           return new Response('Cached content');
       }
   }
   

Implementation Patterns

Annotation-Based Caching

• Route-Level Caching: Use @Cache on controller methods or routes (@Route).

  # config/routes.yaml
  my_route:
      path: /cached
      controller: App\Controller\MyController::index
      methods: GET
      cache: { profile: "long" }
  

• Dynamic Profiles: Pass profiles via request parameters:

  $this->cache->setProfile($request->query->get('cache_profile'));
  

Cache Invalidation

• Manual Invalidation: Trigger via CLI or controller:

  php bin/console fos:http-cache:purge /path/to/invalidate
  

  $this->cache->purge('/path/to/invalidate');
  

• Event-Driven Invalidation: Listen to fos_http_cache.purge events:

  use DataFactory\FOSHttpCacheBundle\Event\PurgeEvent;
  
  $eventDispatcher->addListener(PurgeEvent::class, function (PurgeEvent $event) {
      // Custom logic (e.g., log, notify)
  });
  

Advanced Profiles

• Conditional Caching: Use vary headers dynamically:

  $this->cache->setVary(['Accept-Language', 'User-Agent']);
  

• TTL Overrides: Extend profiles in runtime:

  $this->cache->setTTL(3600); // Override for 1 hour
  

Integration with Symfony Components

• HttpCache: Use HttpCache service directly:

  $this->httpCache->getResponse($request);
  

• Reverse Proxy: Configure proxy_client backend for Varnish/Nginx:

  # config/packages/datafactory_fos_http_cache.yaml
  proxy_client:
      backend: varnish
      host: 127.0.0.1
      port: 6081
  

Gotchas and Tips

Common Pitfalls

1. Cache Headers Conflicts

   • Ensure Cache-Control headers from the bundle don’t clash with other middleware (e.g., Symfony’s HttpCache).
   • Fix: Explicitly set private/public in profiles:

     profiles:
         short:
             max_age: 3600
             public: true
     

2. Invalidation Race Conditions

   • Purge requests may fail if the cache backend is unreachable.
   • Fix: Use purge_batch for bulk invalidations:

     php bin/console fos:http-cache:purge_batch /path1 /path2
     

3. Vary Headers Overhead

   • Excessive Vary headers can bloat responses and reduce cache efficiency.
   • Tip: Limit vary to critical headers (e.g., Accept-Language).

Debugging

• Check Headers: Use bin/console debug:headers to verify cache headers.
• Log Purges: Enable debug mode for purge events:

  # config/packages/dev/datafactory_fos_http_cache.yaml
  debug: true
  

Extension Points

1. Custom Backends Extend DataFactory\FOSHttpCacheBundle\Cache\Backend\AbstractBackend for new cache types (e.g., Redis).

2. Profile Factories Dynamically generate profiles via ProfileFactoryInterface:

   $factory = $this->container->get('fos_http_cache.profile_factory');
   $profile = $factory->create('dynamic_profile', ['ttl' => 7200]);
   

3. Event Subscribers Hook into fos_http_cache.response to modify responses before caching:

   public static function getSubscribedEvents()
   {
       return [
           'fos_http_cache.response' => 'onCacheResponse',
       ];
   }
   

Performance Tips

• Edge Caching: Prefer proxy_client for edge caches (Varnish, Cloudflare) over vary.
• Static Assets: Exclude static files from dynamic caching:

  profiles:
      static:
          max_age: 31536000
          vary: []