Extra Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require twig/extra-bundle
   

   (Note: In Laravel, this requires twig-laravel/twig as a bridge.)

2. Basic Usage:

   • For Laravel + Twig, ensure twig-laravel/twig is installed and configured in config/app.php:

     'providers' => [
         Twig\Laravel\TwigServiceProvider::class,
     ],
     

   • Enable the bundle by registering it in config/twig.php (if using twig-laravel/twig):

     'extensions' => [
         Twig\Extra\String\StringExtension::class,
         Twig\Extra\Text\TextExtension::class,
     ],
     

3. First Use Case: Use Twig’s extended filters/functions in a template:

   {# StringExtension #}
   {{ 'hello world'|upper }}
   
   {# TextExtension #}
   {{ 'lorem ipsum'|truncate(20, '...') }}
   
   {# ArrayExtension #}
   {% for key, value in {'a': 1, 'b': 2} %}
       {{ key }}: {{ value }}
   {% endfor %}
   

Implementation Patterns

Usage Patterns

1. Selective Extension Activation:

   • Avoid loading all extensions if only a subset is needed (e.g., StringExtension for text manipulation).
   • Example in Laravel’s Twig config:

     'extensions' => [
         Twig\Extra\String\StringExtension::class,
         Twig\Extra\Text\TextExtension::class,
     ],
     

2. Form Handling (Symfony-Laravel Hybrid):

   • If using Symfony’s Form component in Laravel, leverage FormExtension:

     {{ form_start(form) }}
         {{ form_widget(form.name) }}
         {{ form_errors(form) }}
     {{ form_end(form) }}
     

   • Note: Requires Symfony’s Form component installed (composer require symfony/form).

3. URL Generation:

   • Use UrlExtension for Symfony-style routing (if symfony/routing is available):

     {{ path('home') }}
     {{ url('https://example.com') }}
     

   • Laravel Alternative: Use Blade’s @route or route() helper instead.

4. Text Processing:

   • Localization and formatting with IntlExtension (if symfony/intl is installed):

     {{ 'hello'|trans({'%name%': 'John'}) }}
     {{ 1000|filesize }}
     

5. Custom NodeVisitors:

   • Extend Twig’s parsing logic (advanced use case):

     use Twig\TwigFunction;
     $twig->addFunction(new TwigFunction('custom_function', function() {
         return 'custom logic';
     }));
     

Workflows

1. Laravel-Twig Hybrid Workflow:

   • Use Blade for frontend templates and Twig for admin panels (e.g., Symfony-based CMS).
   • Example: Admin dashboard with Twig forms:

     {# app/Resources/views/admin/dashboard.html.twig #}
     {{ form_widget(form.user) }}
     

2. Dynamic Template Logic:

   • Leverage ArrayExtension for complex data structures:

     {% for item in items if item.active %}
         {{ item.name|upper }}
     {% endfor %}
     

3. Asset Management:

   • Use AssetExtension for Symfony’s AssetMapper (if integrated):

     {{ asset('css/style.css') }}
     

   • Laravel Alternative: Use mix('css/style.css') or asset('css/style.css').

Integration Tips

1. Avoid Symfony Dependencies:

   • Skip extensions like CsrfExtension or WebProfilerExtension in Laravel unless Symfony components are explicitly used.

2. Laravel-Specific Shims:

   • Override Symfony-dependent services (e.g., Router) with Laravel equivalents:

     $twig->addExtension(new \Twig\Extra\UrlExtension(
         new \Illuminate\Routing\Router(), // Laravel's Router
         new \Illuminate\Http\Request()
     ));
     

3. Testing:

   • Test Twig templates in isolation using Laravel’s TwigView:

     use Twig\Laravel\View\TwigView;
     $view = new TwigView($twig, 'template.html.twig', ['data' => $data]);
     $content = $view->render();
     

4. Performance:

   • Cache Twig templates aggressively in Laravel:

     'cache' => true,
     'auto_reload' => env('APP_DEBUG'),
     

Gotchas and Tips

Pitfalls

1. Symfony-Specific Extensions:

   • Extensions like CsrfExtension or FormExtension fail silently in Laravel without Symfony’s RequestStack or Form component.
   • Fix: Mock dependencies or avoid these extensions.

2. Routing Conflicts:

   • UrlExtension expects Symfony’s Router; Laravel’s Router has a different interface.
   • Fix: Use Laravel’s route() helper or create a custom Twig extension.

3. CSRF Token Mismatch:

   • csrf_token filter assumes Symfony’s CsrfTokenManager; Laravel uses csrf_token() helper.
   • Fix: Replace with Blade’s @csrf or a custom Twig filter:

     $twig->addFunction(new \Twig\TwigFunction('csrf_token', function() {
         return csrf_token();
     }));
     

4. Asset Pipeline Conflicts:

   • AssetExtension expects Symfony’s AssetMapper; Laravel uses mix-manifest.json.
   • Fix: Use Laravel’s mix() or asset() helpers directly in Twig.

5. IntlExtension Dependencies:

   • Requires symfony/intl for localization features (e.g., |trans).
   • Fix: Use Laravel’s trans() helper or install the dependency.

Debugging

1. Extension Not Loading:

   • Verify extensions are registered in config/twig.php or via service provider.
   • Check for composer autoload issues:

     composer dump-autoload
     

2. Undefined Filters/Functions:

   • Ensure the extension class is fully qualified (e.g., \Twig\Extra\String\StringExtension).
   • Debug with:

     dd($twig->getExtensions()); // List loaded extensions
     

3. Symfony Service Missing:

   • Use Laravel’s app() to bind missing Symfony services:

     $twig->addExtension(new \Twig\Extra\UrlExtension(
         app(\Illuminate\Routing\Router::class),
         app(\Illuminate\Http\Request::class)
     ));
     

Tips

1. Laravel-Friendly Extensions:

   • Prefer StringExtension, TextExtension, and ArrayExtension for Laravel use cases.

2. Custom Extensions:

   • Create Laravel-specific Twig extensions for missing features:

     use Twig\Extension\AbstractExtension;
     use Twig\TwigFunction;
     
     class LaravelTwigExtension extends AbstractExtension {
         public function getFunctions() {
             return [
                 new TwigFunction('laravel_helper', function() {
                     return 'Laravel-specific logic';
                 }),
             ];
         }
     }
     

3. Configuration Overrides:

   • Disable unwanted extensions in config/twig.php:

     'extensions' => [
         // Only enable what you need
         \Twig\Extra\String\StringExtension::class,
     ],
     

4. Blade-Twig Interop:

   • Use Twig for complex logic and Blade for simplicity:

     {# Twig template #}
     {% if user.is_admin %}
         {{ 'Admin Panel'|upper }}
     {% endif %}
     

     @if(auth()->user()->is_admin)
         {{ Str::upper('Admin Panel') }}
     @endif
     

5. Performance Tuning:

   • Disable auto-reload in production:

     'auto_reload' => false,
     'cache' => storage_path('framework/views'),