Templates Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cyril-verloop/templates-bundle
   

   For Symfony Flex projects, no additional config is required. For non-Flex projects, manually add the Twig paths in config/packages/twig.yaml:

   twig:
       paths:
           '%kernel.project_dir%/vendor/cyril-verloop/templates-bundle/templates': CVTemplatesBundle
   

2. First Use Case: Extend a base template in your Twig file:

   {% extends "@CVTemplatesBundle/base.html.twig" %}
   {% block body %}
       <!-- Your content here -->
   {% endblock %}
   

3. Where to Look First:

   • Check the templates/ directory in the package for available templates (e.g., base.html.twig, layout.html.twig).
   • Review the documentation for template-specific variables or blocks.

Implementation Patterns

Common Workflows

1. Template Inheritance: Use the provided templates as parent templates for your views:

   {% extends "@CVTemplatesBundle/layout.html.twig" %}
   {% block title %}My Page{% endblock %}
   

2. Customizing Blocks: Override blocks defined in the base templates (e.g., head, footer, styles):

   {% block styles %}
       {{ parent() }}  <!-- Include parent styles -->
       <link rel="stylesheet" href="{{ asset('custom.css') }}">
   {% endblock %}
   

3. Dynamic Content Injection: Pass variables to child templates via Twig’s {% block %} or {{ include() }}:

   {% block content %}
       {{ include('@CVTemplatesBundle/_partials/alert.html.twig', {
           type: 'success',
           message: 'Operation completed!'
       }) }}
   {% endblock %}
   

4. Partial Reuse: Include reusable components (e.g., @CVTemplatesBundle/_partials/navbar.html.twig) in multiple templates:

   {{ include('@CVTemplatesBundle/_partials/navbar.html.twig') }}
   

5. Integration with Laravel (Symfony Bridge):

   • Use Laravel’s Symfony Bridge (e.g., spatie/symfony) to integrate Symfony templates in Laravel.
   • Configure Twig in Laravel’s config/twig.php:

     'paths' => [
         base_path('vendor/cyril-verloop/templates-bundle/templates'),
     ],
     

   • Extend templates in Laravel Blade via Twig integration or use Twig directly in custom views.

6. Asset Management: Reference assets (CSS/JS) from the bundle’s public/ directory:

   <link rel="stylesheet" href="{{ asset('bundles/cvtemplates/css/base.css') }}">
   

Gotchas and Tips

Pitfalls

1. Namespace Conflicts:

   • Ensure template paths (e.g., @CVTemplatesBundle/...) are unique in your project to avoid conflicts with other bundles or custom templates.

2. Caching Issues:

   • Clear Twig cache after updating templates:

     php bin/console cache:clear
     

   • In Laravel, run:

     php artisan view:clear
     

3. Missing Dependencies:

   • The bundle assumes Twig is installed. If using Laravel, ensure twig/twig is installed via Composer:

     composer require twig/twig
     

4. Symfony Flex vs. Non-Flex:

   • Non-Flex projects require manual twig.yaml configuration. Forgetting this will result in TemplateNotFoundException.

5. Laravel-Specific Quirks:

   • Laravel’s asset pipeline (mix/vite) may not resolve paths in the bundle’s public/ directory by default. Use asset() with full paths:

     {{ asset('bundles/cvtemplates/js/script.js') }}
     

Debugging Tips

1. Template Not Found:

   • Verify the path in twig.yaml matches the bundle’s templates/ directory.
   • Check for typos in template names (e.g., @CVTemplatesBundle/base.html.twig vs. @CVTemplatesBundle/base.html.twig).

2. Block Override Failures:

   • Ensure child templates define blocks with the same names as the parent. Use {{ dump(_context.getBlockName()) }} to debug block names.

3. Variable Scope:

   • Variables passed to included templates must be explicitly defined. Use {{ dump(_context.getBlockParent()) }} to inspect parent context.

Extension Points

1. Customizing Templates:

   • Override the entire template by copying it to your project’s templates/ directory (e.g., templates/base.html.twig). Changes here take precedence.

2. Adding New Templates:

   • Extend the bundle by creating a custom bundle that depends on CVTemplatesBundle and adds new templates to Resources/views/.

3. Hooking into Events:

   • Listen for Twig events (e.g., TwigEvent::PRE_RENDER) to modify templates dynamically:

     // In a Symfony service or Laravel event listener
     $twig->addExtension(new class extends \Twig\Extension\AbstractExtension {
         public function onPreRender(\Twig\Event\EnvironmentEvent $event) {
             $template = $event->getTemplateName();
             if (str_starts_with($template, '@CVTemplatesBundle')) {
                 // Modify template logic here
             }
         }
     });
     

4. Laravel-Specific Extensions:

   • Create a Laravel service provider to register Twig extensions or filters for bundle-specific functionality:

     // In Laravel
     Twig::getEnvironment()->addFunction(new \Twig\TwigFunction('cv_template_partial', [$this, 'renderPartial']));