Page Cache Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require bigyouth/page-cache-bundle
   

   Add to AppKernel.php:

   new BigYouth\PageCacheBundle\BigYouthPageCacheBundle(),
   

2. Configure Cache: Edit app/config/config.yml:

   big_youth_page_cache:
       enabled: true
       cache_dir: "%kernel.cache_dir%/page_cache"
       ttl: 3600  # Default: 1 hour
       debug: false
   

3. First Use Case: Cache a route by adding the Cache annotation to a controller method:

   use BigYouth\PageCacheBundle\Annotation\Cache;
   
   class MyController extends Controller
   {
       /**
        * @Cache()
        */
       public function indexAction()
       {
           return $this->render('my_template.html.twig');
       }
   }
   

Implementation Patterns

Common Workflows

1. Route-Based Caching: Use the @Cache annotation on controller methods or classes to cache entire routes:

   /**
    * @Cache(ttl=600)  // Custom TTL (in seconds)
    */
   public function productsAction()
   {
       // Expensive logic here
   }
   

2. Dynamic Cache Keys: Override cache keys for dynamic content:

   /**
    * @Cache(key="products_{page}")
    */
   public function productsAction($page = 1)
   {
       // Cache key includes 'page' parameter
   }
   

3. Excluding Routes: Disable caching for specific routes via config.yml:

   big_youth_page_cache:
       exclude_paths:
           - ^/admin
           - ^/api
   

4. Cache Invalidation: Manually clear cache for a route:

   $this->get('big_youth_page_cache.cache')->invalidate('route_name');
   

Integration Tips

• Symfony Cache: Leverage Symfony’s Cache component for storage (default).
• Varnish/Reverse Proxy: Use this bundle as a fallback or for dynamic content.
• Debugging: Enable debug: true in config to log cache hits/misses.

Gotchas and Tips

Pitfalls

1. Cache Staleness:

   • The bundle uses a simple TTL-based invalidation. For dynamic data (e.g., user-specific content), avoid caching or use short TTLs.
   • Fix: Combine with Cache annotation’s vary parameter (if supported) or manual invalidation.

2. Annotation Parsing:

   • The @Cache annotation must be parsed by Doctrine’s annotation reader. Ensure doctrine/annotations is installed:

     composer require doctrine/annotations
     

3. Configuration Overrides:

   • Bundle config in config.yml takes precedence over annotations. Test changes thoroughly.

4. PHP 7+ Compatibility:

   • The package supports PHP 5.3–7.0. For PHP 7.4+, test thoroughly or fork the package.

Debugging Tips

• Logs: Enable debug: true to log cache operations to var/log/dev.log.
• Cache Directory: Verify cache_dir is writable and not symlinked (some systems break cache writes).
• Clear Cache: Use php app/console cache:clear if cache behaves unexpectedly.

Extension Points

1. Custom Cache Backend: Extend the bundle by implementing BigYouth\PageCacheBundle\Cache\CacheInterface and bind it as a service.

2. Event Listeners: Listen to big_youth_page_cache.invalidate events for custom invalidation logic:

   // src/EventListener/CacheListener.php
   public function onCacheInvalidate(CacheInvalidateEvent $event)
   {
       // Custom logic (e.g., log, notify)
   }
   

3. Middleware Alternative: For Symfony 4.3+, consider replacing annotations with middleware for better flexibility:

   // src/Kernel.php
   protected function build(RequestContext $requestContext)
   {
       $requestContext->addMiddleware(new PageCacheMiddleware());
   }