Twig Pack Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer in your Laravel project:

   composer require symfony/twig-pack
   

   (Note: This package is primarily a Symfony "Pack" for Twig, meaning it’s designed to integrate Twig into Symfony projects. In Laravel, you’d typically use twig/laravel or spatie/laravel-twig instead. However, if you’re working in a hybrid Laravel/Symfony environment or need Twig-specific Symfony Pack features, proceed with caution.)

2. First Use Case

   • For Laravel Devs: This package alone won’t render Twig templates. Pair it with a Laravel-compatible Twig bridge (e.g., spatie/laravel-twig).
   • For Symfony Pack Features: If you’re using Symfony’s Flex recipes, this pack enables Twig’s core functionality (e.g., twig:install, twig:debug). Run:

     php bin/console twig:install
     

     (In Laravel, this would require manual config or a custom recipe.)

3. Where to Look First

   • Symfony Docs: Twig Pack Reference (for Symfony-specific features).
   • Laravel Twig Bridges: Focus on spatie/laravel-twig for Laravel integration.
   • Template Files: Place Twig templates in resources/views/ (if using a Laravel bridge) or templates/ (Symfony convention).

Implementation Patterns

Workflows

1. Template Rendering

   • Symfony: Use Twig’s render function in controllers:

     return $this->render('template.html.twig', ['data' => $value]);
     

   • Laravel: With spatie/laravel-twig, render via:

     return Twig::render('template.twig', ['data' => $value]);
     

2. Dynamic Includes/Extends

   • Use Twig’s native syntax:

     {% extends 'base.twig' %}
     {% block content %}
         {{ include('partial/_header.twig') }}
     {% endblock %}
     

3. Asset Management

   • Symfony: Leverage twig:assets for versioned URLs:

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

   • Laravel: Use Laravel Mix/Vite alongside Twig (ensure asset paths are compatible).

4. Form Handling

   • Symfony: Use TwigBundle's form themes:

     {{ form_start(form) }}
         {{ form_widget(form) }}
     {{ form_end(form) }}
     

   • Laravel: Integrate with Laravel Collective or custom form builders.

Integration Tips

• Hybrid Projects: If mixing Laravel/Symfony, configure Twig’s loader to scan both resources/views/ and templates/:

  // config/twig.php (custom)
  'paths' => [
      realpath(__DIR__.'/../../resources/views'),
      realpath(__DIR__.'/../../templates'),
  ],
  

• Caching: Enable Twig’s cache for production (Symfony):

  # config/packages/twig.yaml
  twig:
      cache: '%kernel.cache_dir%/twig'
  

• Laravel Blade + Twig: Avoid mixing unless absolutely necessary (use one templating engine per project).

Gotchas and Tips

Pitfalls

1. Laravel Incompatibility

   • This package is not a standalone Twig solution for Laravel. It assumes Symfony’s autowiring and kernel. Use spatie/laravel-twig instead for Laravel projects.
   • Symptom: Twig\Error\LoaderError if templates aren’t found in Symfony’s templates/ directory.
   • Fix: Configure custom paths or use a Laravel-compatible bridge.

2. Asset Pipeline Conflicts

   • Symfony’s asset() function may clash with Laravel’s Mix/Vite. Ensure consistent asset paths:

     <!-- Symfony -->
     {{ asset('css/app.css') }}
     
     <!-- Laravel (if using Mix) -->
     <link href="{{ mix('css/app.css') }}" rel="stylesheet">
     

3. Caching Quirks

   • Symfony: Twig cache is tied to Symfony’s cache directory (var/cache/). Clear it with:

     php bin/console cache:clear
     

   • Laravel: Use php artisan view:clear for Twig views (if using spatie/laravel-twig).

4. Dependency Overlap

   • Installing this pack may pull in Symfony components (e.g., symfony/http-foundation). In Laravel, this can cause conflicts with Laravel’s base classes.
   • Fix: Use composer why symfony/http-foundation to audit dependencies.

Debugging

• Template Errors: Enable Twig’s debug mode (Symfony):

  twig:
      debug: '%kernel.debug%'
  

  • Laravel: Set TWIG_DEBUG=true in .env.

• Loader Issues: Verify template paths are correct:

  php bin/console debug:container twig.loader
  

Extension Points

1. Custom Twig Extensions

   • Create a service to extend Twig’s functionality:

     // src/Twig/AppExtension.php
     class AppExtension extends \Twig\Extension\AbstractExtension
     {
         public function getFunctions()
         {
             return [
                 new \Twig\TwigFunction('app_function', [$this, 'appFunction']),
             ];
         }
     }
     

   • Register it in Symfony’s services or Laravel’s service provider.

2. Filters/Tests

   • Add custom Twig filters:

     $twig->addFilter(new \Twig\TwigFilter('custom_filter', function ($str) {
         return strtoupper($str);
     }));
     

3. Symfony Recipes

   • If using Symfony Flex, create a custom recipe to integrate Twig into Laravel’s workflow (advanced). Example:

     # resources/recipes/your-vendor/your-package.yaml
     symfony/recipe:
         type: project
         name: Your Laravel Project
         # ...