Twig Extensions Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ajgl/twig-extensions
   

   (Note: Despite being deprecated, this package may still be used in legacy projects or as a reference for the newer AjglBreakpointTwigExtension.)

2. Register the Extension: In your Laravel service provider (e.g., AppServiceProvider), add:

   $this->app['twig']->addExtension(new \Ajgl\TwigExtensions\AjglTwigExtensions());
   

3. First Use Case: Test a basic Twig filter (if available) in a Blade template:

   {{ 'hello'|uppercase }}  {# Example if 'uppercase' filter exists #}
   

Where to Look First

• Source Code: AjglTwigExtensions.php (check for available filters/functions).
• README: Confirm deprecated features (e.g., breakpoint utilities) and their replacements in AjglBreakpointTwigExtension.

Implementation Patterns

Common Workflows

1. Legacy Template Integration:

   • Use the package to maintain compatibility with existing Twig templates relying on its extensions.
   • Example: Replace deprecated {{ breakpoint() }} with the newer package’s equivalent.

2. Custom Extensions:

   • Extend the package’s base class (AjglTwigExtensions) to add your own filters/functions:

     class CustomTwigExtensions extends \Ajgl\TwigExtensions\AjglTwigExtensions {
         public function getFunctions() {
             return array_merge(parent::getFunctions(), [
                 new \Twig_SimpleFunction('custom_function', [$this, 'customFunction']),
             ]);
         }
     
         public function customFunction($input) {
             return strtoupper($input);
         }
     }
     

3. Conditional Logic:

   • Leverage Twig extensions for dynamic content (e.g., responsive classes):

     {% if breakpoint('sm') %}
         <div class="sm-only">...</div>
     {% endif %}
     

Integration Tips

• Blade Compatibility: Use @twig directives to embed Twig logic:

  @twig
      {{ 'content'|some_filter }}
  @endtwig
  

• Testing: Mock the extension in PHPUnit:

  $twig = new \Twig_Environment($loader);
  $twig->addExtension(new \Ajgl\TwigExtensions\AjglTwigExtensions());
  $template = $twig->createTemplate('{{ some_function() }}');
  $template->render();
  

Gotchas and Tips

Pitfalls

1. Deprecation Warning:

   • The package is deprecated; prioritize migrating to AjglBreakpointTwigExtension for new projects.
   • Check for breaking changes in the newer package (e.g., renamed functions).

2. Undefined Extensions:

   • The package may lack documentation for all available filters/functions. Inspect the source code directly:

     // Example: Check for 'truncate' filter in AjglTwigExtensions.php
     public function getFilters() { ... }
     

3. Namespace Conflicts:

   • Avoid naming collisions with Laravel’s built-in Twig extensions (e.g., App\Extensions\Twig\...).

Debugging

• Enable Twig Debugging: In config/twig.php, set:

  'debug' => env('APP_DEBUG', false),
  

  To display errors like:

  Twig_Error_Runtime: Filter 'unknown_filter' does not exist.
  

• Log Extension Calls: Override methods to log usage (e.g., for breakpoint checks):

  public function breakpoint($size) {
      \Log::debug("Breakpoint called for: $size");
      return parent::breakpoint($size);
  }
  

Extension Points

1. Override Existing Extensions:

   • Subclass and redefine methods (e.g., getFilters(), getFunctions()).

2. Add Global Variables:

   • Inject data via Twig’s addGlobal:

     $this->app['twig']->addGlobal('app_name', config('app.name'));
     

3. Custom Breakpoint Logic:

   • If using the deprecated breakpoint() function, replace it with a Laravel helper:

     // app/Helpers.php
     if (!function_exists('breakpoint')) {
         function breakpoint($size) {
             return request()->wantsJson() || request()->isMobile();
         }
     }