Ezplatform Http Cache Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ezsystems/ezplatform-http-cache
   

   Ensure you have Ibexa DXP installed as a dependency.

2. Enable the Bundle: Add to config/bundles.php:

   return [
       // ...
       Ibexa\HttpCacheBundle\IbexaHttpCacheBundle::class => ['all' => true],
   ];
   

3. Configure Varnish (Example): Update config/packages/ibexa_http_cache.yaml:

   ibexa_http_cache:
       varnish:
           host: '127.0.0.1'
           port: 6081
           purge_url: 'http://127.0.0.1:6082/purge'
       purge:
           enabled: true
           tags: ['content', 'user']
   

4. First Use Case: Trigger cache invalidation after content updates:

   use Ibexa\HttpCacheBundle\Purger\TagPurger;
   
   // In a service or controller
   $tagPurger = $this->container->get('ibexa.http_cache.purger.tag');
   $tagPurger->purge(['content/123']); // Purge cache for content ID 123
   

Implementation Patterns

Core Workflows

1. Cache Invalidation:

   • Content Updates: Use TagPurger to invalidate cache for specific content or tags:

     $tagPurger->purge(['content/456', 'user/789']);
     

   • Bulk Operations: Leverage UrlPurger for URL-based invalidation:

     $urlPurger = $this->container->get('ibexa.http_cache.purger.url');
     $urlPurger->purge(['/content/123', '/content/456']);
     

2. Vary Headers:

   • Customize VaryHeaderListener to handle dynamic content (e.g., language, user roles):

     # config/packages/ibexa_http_cache.yaml
     ibexa_http_cache:
           vary:
               headers:
                   - 'Accept-Language'
                   - 'X-Ibexa-User-Role'
     

3. Conditional Logic:

   • Extend ConditionalRemoveVaryHeaderListener to exclude headers for specific routes:

     // src/EventListener/CustomVaryHeaderListener.php
     public function onKernelRequest(GetResponseEvent $event)
     {
         $request = $event->getRequest();
         if ($request->getPathInfo() === '/admin') {
             $event->getResponse()->headers->remove('Vary');
         }
     }
     

4. Edge-Side Includes (ESI):

   • Use ESI tags in templates to cache fragments:

     {# templates/content.html.twig #}
     {% esi 'content-block' %}
     

Integration Tips

• Symfony Events: Hook into kernel.response to modify responses before caching:

  $eventDispatcher->addListener(
      KernelEvents::RESPONSE,
      [$this, 'onKernelResponse']
  );
  

• API Routes: Exclude API endpoints from caching by tagging them:

  # config/packages/ibexa_http_cache.yaml
  ibexa_http_cache:
      exclude:
          paths:
              - '^/api/'
  

• Testing: Use HttpCacheTestTrait for unit tests:

  use Ibexa\HttpCacheBundle\Tests\Integration\HttpCacheTestTrait;
  
  class MyTest extends WebTestCase
  {
      use HttpCacheTestTrait;
  }
  

Gotchas and Tips

Pitfalls

1. Varnish Configuration:

   • Ensure Varnish is configured to respect Surrogate-Control headers. Misconfigurations may lead to stale cache.
   • Debugging: Use varnishlog to inspect cache hits/misses:

     varnishlog -g request -q 'ReqUrl eq "/content/123"'
     

2. Tag vs. URL Purges:

   • Tag Purges: More efficient for large-scale invalidations (e.g., all content in a language).
   • URL Purges: Granular but less scalable. Prefer tags for dynamic content.

3. Header Conflicts:

   • Avoid mixing Cache-Control and Surrogate-Control headers. Use Surrogate-Control for Varnish-specific directives:

     $response->headers->set('Surrogate-Control', 'content="stale-while-revalidate=60"');
     

4. ESI Edge Cases:

   • Ensure ESI blocks are idempotent (same input → same output). Non-idempotent blocks (e.g., with timestamps) break caching.
   • Test ESI with curl -H "X-ESI: 1" to simulate edge-side includes.

Debugging

• Log Purges: Enable debug logging for purge operations:

  # config/packages/monolog.yaml
  handlers:
      ibexa_http_cache:
          type: stream
          path: "%kernel.logs_dir%/%kernel.environment%.ibexa_http_cache.log"
          level: debug
  

• Cache Validation:
  • Use curl -I to check X-Ibexa-Cache headers:

    curl -I http://your-site.com/content/123
    

  • Expected headers:

    X-Ibexa-Cache: HIT
    Surrogate-Control: content="stale-while-revalidate=60"
    

Extension Points

1. Custom Purge Strategies:

   • Implement PurgerInterface for custom invalidation logic:

     class CustomPurger implements PurgerInterface
     {
         public function purge(array $tags): void
         {
             // Custom logic (e.g., Redis, CDN API)
         }
     }
     

   • Register as a service:

     services:
         App\Purger\CustomPurger:
             tags: ['ibexa.http_cache.purger']
     

2. Dynamic Vary Headers:

   • Override VaryHeaderListener to add runtime headers:

     public function onKernelRequest(GetResponseEvent $event)
     {
         $request = $event->getRequest();
         $event->getResponse()->headers->addCacheControlDirective(
             'private',
             $request->get('user') ? 'user=' . $request->get('user') : null
         );
     }
     

3. Cache Warmup:

   • Pre-load cache for critical paths using HttpClient:

     $client = $this->container->get('http_client');
     $client->request('GET', '/content/123', [
         'headers' => ['X-Ibexa-Warmup' => '1'],
     ]);
     

Configuration Quirks

• Default TTL: The bundle uses 60 seconds for stale-while-revalidate by default. Adjust in config/packages/ibexa_http_cache.yaml:

  ibexa_http_cache:
      default_ttl: 300 # 5 minutes
  

• Purge Tags: Ensure tags are URL-safe (e.g., content/123, not content#123). Use hyphens for multi-word tags:

  $tagPurger->purge(['content/home-page', 'user/editor']);