Template Cache Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require eglobal/template-cache-bundle:~1.0
   

   Register the bundle in config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3):

   EGlobal\Bundle\TemplateCacheBundle\EGlobalTemplateCacheBundle::class => ['all' => true],
   

2. Configure Update config/packages/eglobal_template_cache.yaml (Symfony 4+) or app/config/config.yml (Symfony 3):

   eglobal_template_cache:
       locales: ['en', 'es', 'de']
       cache_dir: '%kernel.project_dir%/var/cache/templates'
       public_prefix: '/templates'
       root_dirs: ['@AcmeDemoBundle/Resources/views']
   

3. First Use Case Annotate a controller action to cache its template:

   use EGlobal\Bundle\TemplateCacheBundle\Annotation\CacheableTemplate;
   use Symfony\Component\Routing\Annotation\Route;
   
   class DemoController
   {
       /**
        * @Route("/cached-page", name="cached_page")
        * @CacheableTemplate()
        */
       public function cachedPageAction()
       {
           return $this->render('AcmeDemo:Demo:page.html.twig');
       }
   }
   

   Run the cache generation command:

   php bin/console cache:template
   

Implementation Patterns

Workflows

1. Cache Generation

   • Manual: Trigger via CLI (php bin/console cache:template).
   • Automated: Hook into post-deploy scripts (e.g., Capistrano, Deployer) or CI/CD pipelines.
   • On-Demand: Use the CacheTemplateCommand programmatically in custom scripts.

2. Template Annotations

   • Apply @CacheableTemplate to controller actions or classes (caches all actions in the class).
   • Exclude specific actions with @CacheableTemplate(exclude=true).

3. Locale-Specific Caching

   • Cache templates per locale (e.g., en, es) by leveraging the locales config.
   • Useful for multilingual sites where templates differ by language.

4. Assetic Integration

   • If using Assetic, include the bundle in config/packages/assetic.yaml:

     assetic:
         bundles: [EGlobalTemplateCacheBundle]
     

   • Cache static assets (CSS/JS) alongside templates for full-page caching.

5. Dynamic Cache Invalidation

   • Clear cache for specific routes or locales:

     php bin/console cache:template:clear --route=cached_page --locale=en
     

   • Or programmatically:

     $this->get('eglobal_template_cache.cache_manager')->clearRoute('cached_page', 'en');
     

Integration Tips

• Symfony Flex: For Symfony 4/5, place config in config/packages/eglobal_template_cache.yaml.
• Twig Extensions: Extend the bundle’s TemplateCacheExtension to add custom logic (e.g., dynamic cache keys).
• Environment-Specific Config: Override cache_dir and public_prefix per environment (e.g., dev, prod).
• Debug Mode: Disable caching in dev environment by setting exposed_routes_only: true and whitelisting routes.

Gotchas and Tips

Pitfalls

1. Cache Directory Permissions

   • Ensure cache_dir is writable by the web server (e.g., chmod -R 775 var/cache/templates).
   • Symfony 4+: Use %kernel.project_dir%/var/cache/templates to align with default cache paths.

2. Route Scope Mismatch

   • If exposed_routes_only: true, only routes marked @CacheableTemplate will cache.
   • Debug with php bin/console debug:router to verify route exposure.

3. Locale Configuration

   • Mismatched locales in parameters and eglobal_template_cache.locales will cause silent failures.
   • Validate locales with:

     php bin/console debug:config eglobal_template_cache
     

4. Template Paths

   • root_dirs must point to view directories (e.g., @Bundle/Resources/views), not controller paths.
   • Use @Bundle notation for Symfony’s autoloader resolution.

5. Assetic Conflicts

   • If using Assetic, ensure the bundle is listed after FrameworkBundle in bundles.php to avoid asset processing issues.

Debugging

• Cache Validation:

  php bin/console cache:template:validate --route=cached_page --locale=en
  

  Outputs whether a route is cacheable and its cache status.

• Log Level: Set EGLOBAL_TEMPLATE_CACHE_DEBUG: true in .env for verbose logging:

  EGLOBAL_TEMPLATE_CACHE_DEBUG=true
  

• Cache Contents: Inspect generated files in cache_dir (e.g., /web/templates/en/cached_page.html).

Tips

1. Cache Key Customization Override the cache key logic by extending the CacheKeyGenerator service:

   services:
       app.template_cache_key_generator:
           class: App\Service\CustomCacheKeyGenerator
           decorates: eglobal_template_cache.cache_key_generator
           arguments: ['@eglobal_template_cache.cache_key_generator.inner']
   

2. Partial Caching For dynamic content in cached templates, use Twig’s {% block %} or embed partials:

   {% block dynamic_content %}
       {{ include('partials/dynamic.html.twig') }}
   {% endblock %}
   

3. Performance

   • Pre-generate cache during deployments to reduce TTFB.
   • Exclude rarely changed routes from caching (e.g., admin dashboards).

4. Symfony 5+ Compatibility

   • The bundle lacks Symfony 5+ support. Test with symfony/framework-bundle:^5.0 and patch if needed.
   • Use symfony/var-dumper for debugging annotations in newer Symfony versions.

5. Fallback Logic Combine with Symfony’s built-in cache (e.g., HttpCache) for hybrid caching:

   framework:
       http_cache:
           enabled: true