Kunstmaan Distributed Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Add the bundle to composer.json:

   composer require dreadlabs/kunstmaan-distributed-bundle
   

   Register it in config/bundles.php (Laravel) or AppKernel.php (Symfony):

   DreadLabs\KunstmaanDistributedBundle\DreadLabsKunstmaanDistributedBundle::class => ['all' => true],
   

2. Configure Redis Add Redis dependencies:

   composer require snc/redis-bundle predis/predis doctrine/doctrine-cache-bundle
   

   Define Redis connection in config/packages/snc_redis.yaml (Laravel) or config.yml (Symfony):

   snc_redis:
       clients:
           default:
               type: predis
               alias: default
               dsn: redis://localhost:6379
   

3. Set Parameters Update config/packages/parameters.yaml (Laravel) or parameters.yml (Symfony):

   parameters:
       http_cache_purge_client_ips: ['127.0.0.1', '192.168.1.100']  # Trusted IPs for cache purge
       http_cache_proxy_servers: ['localhost:80']                     # Proxy servers
       http_cache_proxy_baseurl: 'https://yourdomain.com'            # Base URL
       http_cache_purge_method: 'PURGE'                              # Custom HTTP method
       redis_host: 'localhost'                                       # Redis host
   

4. First Use Case Deploy Kunstmaan CMS on a clustered setup (e.g., multiple web servers). The bundle ensures:

   • Redis-backed caching for Kunstmaan Admin.
   • Page cache invalidation via HTTP PURGE requests.

Implementation Patterns

Workflows

1. Clustered Deployment

   • Use the bundle to replace filesystem caching with Redis across multiple web servers.
   • Configure snc_redis for high availability (e.g., Redis Sentinel or Cluster).

2. Cache Invalidation

   • Trigger cache purges via HTTP PURGE requests from trusted clients (defined in http_cache_purge_client_ips).
   • Example in a controller:

     use Symfony\Component\HttpFoundation\Request;
     
     public function purgeCache(Request $request)
     {
         if ($request->isMethod('PURGE') && in_array($request->getClientIp(), $this->getParameter('http_cache_purge_client_ips'))) {
             $this->get('kunstmaan_admin.cache')->invalidateAll();
         }
         return new Response('Cache purged', 200);
     }
     

3. Event-Driven Cache Updates

   • Leverage the dreadlabs_kunstmaan_distibuted.cache_page_events.subscriber to listen to Kunstmaan events (e.g., PageUpdateEvent) and invalidate cache automatically:

     // config/packages/kunstmaan_admin.yaml
     kunstmaan_admin:
         cache:
             page_events_subscriber: true
     

4. Customizing Proxy Behavior

   • Extend proxy logic by overriding the PurgeCacheListener:

     // src/EventListener/CustomPurgeCacheListener.php
     use DreadLabs\KunstmaanDistributedBundle\EventListener\PurgeCacheListener as BaseListener;
     
     class CustomPurgeCacheListener extends BaseListener
     {
         public function onKernelRequest(GetResponseEvent $event)
         {
             // Custom logic here
             parent::onKernelRequest($event);
         }
     }
     

   • Register the custom listener in services.yaml:

     services:
         App\EventListener\CustomPurgeCacheListener:
             tags:
                 - { name: kernel.event_listener, event: kernel.request, method: onKernelRequest }
     

Gotchas and Tips

Pitfalls

1. Redis Connection Issues

   • Ensure redis_host and snc_redis configurations match your infrastructure.
   • Debug with:

     php bin/console debug:container snc_redis.default
     

   • Common fix: Verify Redis server is running and accessible from all web servers.

2. Cache Invalidation Delays

   • If using multiple Redis instances, ensure all clusters are synchronized.
   • Test cache invalidation with:

     curl -X PURGE http://yourdomain.com/path -H "X-Forwarded-For: 127.0.0.1"
     

3. HTTP PURGE Method Blocking

   • Some proxies (e.g., Nginx) require explicit configuration to allow PURGE:

     if ($request_method = PURGE) {
         return 200;
     }
     

   • Fallback: Use a custom header (e.g., X-Cache-Purge) and modify the bundle’s PurgeCacheListener.

4. Compiler Pass Conflicts

   • The kunstmaan_admin.cache compiler pass may conflict with other cache bundles.
   • Disable it temporarily to debug:

     # config/packages/dreadlabs_kunstmaan_distributed.yaml
     dreadlabs_kunstmaan_distributed:
         enable_cache_compiler_pass: false
     

Tips

1. Monitor Redis Performance

   • Use redis-cli monitor to track cache operations in real-time.
   • Optimize with Redis persistence (e.g., appendfsync everysec) for clustered setups.

2. Environment-Specific Configs

   • Override parameters per environment (e.g., config/packages/parameters.dev.yaml):

     parameters:
         redis_host: 'redis-dev.example.com'
         http_cache_purge_client_ips: ['10.0.0.1/24']  # Dev network
     

3. Testing Cache Invalidation

   • Mock Redis in PHPUnit:

     $this->container->set('snc_redis.default', $this->createMock(\Predis\Client::class));
     

   • Verify events fire with:

     $this->container->get('event_dispatcher')->dispatch(new PageUpdateEvent($page));
     

4. Extending Cache Keys

   • Customize cache keys by overriding the CacheKeyGenerator:

     // config/packages/kunstmaan_admin.yaml
     kunstmaan_admin:
         cache:
             cache_key_generator: App\Service\CustomCacheKeyGenerator
     

5. Logging Cache Operations

   • Enable debug logging for cache events:

     # config/packages/monolog.yaml
     handlers:
         cache:
             type: stream
             path: "%kernel.logs_dir%/%kernel.environment%.cache.log"
             level: debug
             channels: ["kunstmaan_admin.cache"]