Cache Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cache/cache-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Cache\CacheBundle\CacheBundle::class => ['all' => true],
   ];
   

2. Configure PSR-6 Cache Pool: Define your cache pool (e.g., cache.yaml):

   framework:
       cache:
           pools:
               my_cache_pool.app:
                   adapter: cache.adapter.filesystem
                   provider: 'ocramius.file_cache.provider'
                   directory: '%kernel.cache_dir%/my_cache'
   

3. First Use Case: Cache Doctrine metadata (most common entry point):

   # config/packages/doctrine.yaml
   doctrine:
       orm:
           metadata_cache_driver: cache.pool.my_cache_pool.app.metadata
           query_cache_driver:   cache.pool.my_cache_pool.app.query
           result_cache_driver:  cache.pool.my_cache_pool.app.result
   

Implementation Patterns

Core Workflows

1. Doctrine Integration:

   • Cache metadata, queries, and results by referencing the pool in doctrine.yaml.
   • Example for query caching:

     query_cache_driver: cache.pool.my_cache_pool.app.query
     

2. Session Caching:

   • Enable session caching via framework.yaml:

     framework:
         session:
             handler_id: cache.session.handler
     

   • Requires a PSR-6 pool configured as cache.session.handler.

3. Routing Cache:

   • Cache routes for performance:

     framework:
         router:
             cache_pool: cache.pool.my_cache_pool.app.routes
     

4. Custom Services:

   • Inject the cache pool into services via autowiring:

     use Psr\Cache\CacheItemPoolInterface;
     
     class MyService {
         public function __construct(private CacheItemPoolInterface $cache) {}
     }
     

Integration Tips

• Debug Toolbar: Automatically integrates with Symfony Profiler to show cache hits/misses.
• Environment-Specific Pools: Use %kernel.environment% in pool names (e.g., cache.pool.dev.app vs. cache.pool.prod.app).
• Tag-Based Invalidation: Leverage PSR-6 tags for cache invalidation (e.g., cache_item->setTag('user_123')).

Gotchas and Tips

Pitfalls

1. Pool Configuration:

   • The bundle does not auto-register pools. You must define them manually in framework.cache.pools.
   • Missing pool definitions cause ServiceNotFoundException.

2. Doctrine Cache Drivers:

   • Ensure pool names match exactly (e.g., cache.pool.my_cache_pool.app.metadata).
   • Mismatched names result in silent failures (Doctrine uses APCu by default).

3. Session Caching:

   • Requires a PSR-6-compliant session handler (e.g., cache.session.handler).
   • Default Symfony session handler (session.handler.native_file) won’t work.

4. Debugging:

   • Use bin/console debug:cache to list registered pools.
   • Check Profiler’s "Cache" tab for hits/misses.

Tips

1. Cache Warmup:

   • Pre-load caches during deployment:

     bin/console cache:warmup
     

2. Tag-Based Invalidation:

   • Invalidate caches programmatically:

     $this->cache->invalidateTags(['user_123']);
     

3. Environment Awareness:

   • Use %kernel.debug% to disable caching in dev:

     pools:
         my_cache_pool.app:
             adapter: cache.adapter.null # Disabled in dev
     

4. Extending the Bundle:

   • Override pool definitions via compiler passes or custom bundles.
   • Example: Add a cache.pool.my_custom_pool in a custom bundle’s Resources/config/services.yaml.

5. Performance:

   • Monitor cache size with bin/console debug:cache and adjust directory paths.
   • For high traffic, use cache.adapter.redis or cache.adapter.apcu.