Sulu Http Cache Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require alengo/sulu-http-cache-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       Alengo\SuluHttpCacheBundle\SuluHttpCacheBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config (if needed):

   php bin/console sulu:http-cache:install
   

   Override defaults in config/packages/sulu_http_cache.yaml:

   sulu_http_cache:
       tracking_params: ['utm_source', 'utm_medium', 'utm_campaign']  # Customize as needed
       cookie_prefix: 'cta_'  # Prefix for marketing cookies
       # 1.0.0: referer validation is on by default — add every host you
       # legitimately receive attribution traffic from (see Gotchas).
       trusted_referers:
           - 'www.example.com'
           - 'campaign.example.com'
       excluded_paths:
           - '^/api/'
           - '^/_admin/'
   

3. Upgrading to 1.0.0 This is the first stable release; the public services and event classes are unchanged, but validation is stricter. Before deploying:

   • Re-run php bin/console cache:clear so compiled patterns are rebuilt.
   • Audit excluded_paths / tracking_params for unescaped regex characters (see Gotchas).
   • Verify your reverse proxy forwards the original Referer header — the hardened check depends on it.
   • Confirm any custom cookie payloads pass the new payload validation.

4. First Use Case Cache-Breaking Query Parameters Strip tracking params from cached responses:

   use Alengo\SuluHttpCacheBundle\Cache\CacheAwareRequest;
   
   $request = new CacheAwareRequest($originalRequest);
   $cleanUrl = $request->getUri(); // Automatically strips tracking params
   

   Marketing Cookie Handling Store attribution cookies at the reverse-proxy layer:

   $this->get('sulu_http_cache.cookie_handler')->storeCookie(
       'cta_campaign_id',
       'summer_sale',
       ['lifetime' => 3600]
   );
   

Implementation Patterns

1. Request Sanitization

Workflow:

• Use CacheAwareRequest to clean URLs before caching.
• Integrate with Symfony’s RequestStack for global access:

  $request = $this->get('request_stack')->getCurrentRequest();
  $cleanRequest = new CacheAwareRequest($request);
  

Symfony Event Integration Listen to kernel.request to auto-sanitize requests:

use Alengo\SuluHttpCacheBundle\EventListener\CacheAwareRequestListener;

services:
    Alengo\SuluHttpCacheBundle\EventListener\CacheAwareRequestListener:
        tags:
            - { name: kernel.event_listener, event: kernel.request, method: onKernelRequest }

Referer-Aware Attribution (1.0.0) The bundle now validates the Referer against the configured hosts before it will persist an attribution cookie. In multi-domain or CDN-fronted setups, make sure the origin host is present in trusted_referers:

sulu_http_cache:
    trusted_referers:
        - 'www.example.com'
        - '*.example.com'   # wildcards are supported, but compiled strictly

If you proxy through a CDN, the referer seen by PHP is whatever the edge forwards — do not strip it in your VCL/nginx config.

2. Cookie Management

Reverse-Proxy Layer Handling

• Store marketing cookies (e.g., cta_campaign_id) in the SuluHttpCacheBundle config.
• Use the CookieHandler service to manage cookies:

  $this->get('sulu_http_cache.cookie_handler')->setCookie(
      'cta_source',
      'facebook',
      ['path' => '/', 'secure' => true]
  );
  

Cookie Payload Validation (1.0.0) Cookie values are now validated against an expected payload shape before being written or read back. Malformed, oversized, or control-character-containing values are discarded instead of being stored. Validate up front when values are user-derived:

if (!$this->get('sulu_http_cache.cookie_handler')->isValidPayload($value)) {
    // skip or normalise before storing
}

Keep payloads scalar and short (campaign ids, source names, timestamps). Do not stuff serialized objects or base64 blobs into attribution cookies — they will be rejected.

Dynamic Cookie Storage

• Extend the CookieHandler to support custom storage backends (e.g., Redis):

  sulu_http_cache:
      cookie_storage: 'redis://localhost:6379/0'
  

  Custom backends must round-trip the validated payload unchanged; do not mutate or re-encode values in the backend adapter.

3. Cache Key Generation

Custom Cache Keys Override the default cache key logic in a subscriber:

use Alengo\SuluHttpCacheBundle\Event\CacheKeyEvent;

public function onGenerateCacheKey(CacheKeyEvent $event) {
    $event->setKey(md5($event->getRequest()->getPathInfo() . $event->getTrackingParams()));
}

Symfony Cache Integration Use the bundle’s cache key with Symfony’s HttpCache:

use Alengo\SuluHttpCacheBundle\Cache\CacheKeyGenerator;

$generator = new CacheKeyGenerator($this->getParameter('sulu_http_cache.tracking_params'));
$cacheKey = $generator->generate($request);

Pattern Compilation (1.0.0) tracking_params and excluded_paths are now compiled into escaped, anchored regular expressions rather than being used loosely. This means:

• Literal strings behave as expected without escaping: ^/api/ is safe.
• Wildcards written as raw regex (.+, .*, (, [) must be intentional and valid — invalid patterns now fail fast at container compile time instead of silently never matching.
• After changing patterns, always cache:clear; the compiled set is cached.

4. Reverse-Proxy Integration

Varnish/Nginx Configuration Configure your reverse proxy to respect the X-Sulu-Cache-Key header:

location / {
    set $cache_key $request_uri;
    if ($http_x_sulu_cache_key) {
        set $cache_key $http_x_sulu_cache_key;
    }
    proxy_cache_key "$cache_key";
}

Also ensure Referer is forwarded untouched:

proxy_set_header Referer $http_referer;

Header-Based Cache Control Add cache headers dynamically:

use Alengo\SuluHttpCacheBundle\Response\CacheResponse;

$response = new CacheResponse($content, 200, [
    'Cache-Control' => 'public, max-age=3600',
]);

Gotchas and Tips

Pitfalls

1. Tracking Param Whitelisting

   • Issue: Forgetting to whitelist new tracking params in sulu_http_cache.tracking_params can cause cache misses.
   • Fix: Use a wildcard (*) cautiously—validate params server-side first.

2. Cookie Scope Conflicts

   • Issue: Overlapping cookie names (e.g., cta_* vs. existing cookies) may cause conflicts.
   • Fix: Use a unique cookie_prefix and audit existing cookies.

3. Reverse-Proxy Mismatch

   • Issue: If the reverse proxy ignores X-Sulu-Cache-Key, cached responses will use raw URLs.
   • Fix: Test proxy config with curl -H "X-Sulu-Cache-Key: test" and verify headers.

4. Dynamic Content Leaks

   • Issue: Personalized content (e.g., user-specific data) may leak into cached responses.
   • Fix: Exclude dynamic routes from caching or use Vary: Cookie headers.

5. Referer Rejections After Upgrading (1.0.0)

   • Issue: Attribution cookies silently stop being stored if the Referer host isn’t in trusted_referers, or if a CDN/proxy strips the header.
   • Fix: Add all legitimate origins to trusted_referers, confirm proxy_set_header Referer $http_referer;, and test with curl -H "Referer: https://www.example.com/" .... Watch the log for rejected-referer entries.

6. Cookie Values Now Rejected (1.0.0)

   • Issue: Previously-accepted payloads (long strings, JSON blobs, non-UTF-8 bytes, values containing ;/newlines) are now dropped by payload validation.
   • Fix: Normalise to a short scalar before calling storeCookie()/setCookie(). Add a test that asserts a round-trip of your real campaign values; failures are silent by design (to avoid poisoning responses).

7. Compiled Pattern Regressions (1.0.0)

   • Issue: Patterns that relied on loose matching may no longer match, or may now throw at compile time. A missing ^ anchor, an unbalanced bracket, or an unescaped . can all change behaviour.
   • Fix: Treat excluded_paths and tracking_params as regexes and test them explicitly:

     php bin/console cache:clear && php bin/console debug:config sulu_http_cache
     

     Run your exclusion list against real paths in a unit test.

Debugging

• Log Cache Keys Enable debug mode to log generated cache keys:

  sulu_http_cache:
      debug: true
  

  Check logs for SULU_HTTP_CACHE_KEY entries.

• Diagnose Dropped Cookies / Referers With debug: true, the 1.0.0 validation paths log why a cookie or referer was rejected. If attribution data is missing but no exception was thrown, look here first — rejections are intentionally non-fatal.

• Inspect Compiled Patterns After cache:clear, dump the compiled rules from the container to confirm what actually got built:

  php bin/console debug:container --parameter=sulu_http_cache.tracking_params
  

• Validate Cookie Storage Use bin/console debug:container sulu_http_cache.cookie_handler to inspect stored cookies.

Extension Points

1. Custom Cache Key Logic Extend CacheKeyGenerator to support:

   • User-agent-based keys.
   • Geographic targeting (e.g., ?locale=fr).

2. Cookie Storage Backends Implement Alengo\SuluHttpCacheBundle\Cookie\CookieStorageInterface for:

   • Database storage.
   • Distributed cache (Redis, Memcached).

3. Event-Driven Extensions Subscribe to sulu_http_cache.cache_key_generated to modify keys pre-caching:

   use Alengo\SuluHttpCacheBundle\Event\CacheKeyEvent;
   
   public function onCacheKeyGenerated(CacheKeyEvent $event) {
       if ($event->getRequest()->getPathInfo() === '/promo') {
           $event->setKey('promo_' . $event->getKey());
       }
   }
   

4. Custom Referer Rules If your trust model is more complex than host matching (e.g., signed campaign links), decorate the referer validator service and delegate to the built-in check for the default case rather than replacing it — the 1.0.0 hardening covers normalisation edge cases you would otherwise have to reimplement.

Performance Tips

• Batch Cookie Operations Use CookieHandler::flush() to clear stale cookies in bulk during migrations.
• Edge Caching Configure CDN (Cloudflare, Fastly) to cache based on X-Sulu-Cache-Key headers.
• Avoid Over-Caching Exclude API endpoints or admin routes from cache:

  sulu_http_cache:
      excluded_paths:
          - '^/api/'
          - '^/_admin/'
  

• Keep Pattern Count Low Compiled patterns are matched on every request. Prefer a handful of anchored prefixes over dozens of broad rules, and prune tracking_params to what you actually report on.