Twigextensions Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require craue/twigextensions-bundle
   

   Ensure the bundle is enabled in config/bundles.php:

   return [
       // ...
       Craue\TwigExtensionsBundle\CraueTwigExtensionsBundle::class => ['all' => true],
   ];
   

2. First Use Case: Use the craue_default filter in a Twig template to replace empty values with HTML-safe placeholders:

   {{ user.name | craue_default('<em>No name provided</em>') }}
   

   No need for | e or | raw—the extension handles HTML escaping automatically.

Implementation Patterns

Common Workflows

1. Decorating Empty Values: Replace Symfony’s default default filter with craue_default for cleaner HTML placeholders:

   {% set price = product.price | craue_default('<span class="placeholder">N/A</span>') %}
   

2. Array Manipulation: Use craue_without to filter arrays dynamically:

   {{ user.roles | craue_without(['ROLE_GUEST']) | join(', ') }}
   

   Or modify arrays with craue_replaceKey:

   {{ config | craue_replaceKey('theme', 'dark') }}
   

3. Form Cloning: Clone forms for multi-step wizards or dynamic sections:

   {{ form_start(form) }}
   {{ form_widget(form) }}
   {{ form_end(form) }}
   
   <hr>
   {{ form | craue_cloneForm | form_start }}
   {{ form_widget(form) }}
   {{ form_end(form) }}
   

4. String Formatting: Ensure consistent punctuation with craue_trailingDot:

   {{ article.title | craue_trailingDot }} — {{ article.date }}
   

Integration Tips

• Custom Filters: Extend the bundle by creating your own Twig extensions and merging them with the bundle’s compiler pass:

  // src/Twig/AppExtension.php
  class AppExtension extends \Twig\Extension\AbstractExtension
  {
      public function getFilters()
      {
          return [
              new \Twig\TwigFilter('app_custom_filter', [$this, 'customFilter']),
          ];
      }
  }
  

  Register the extension in config/packages/twig.yaml:

  twig:
      extensions:
          - App\Twig\AppExtension
  

• Symfony Forms: Combine with Symfony’s form theme system for reusable components:

  {% block form_row %}
      {{ form_label(form) }}
      {{ form_widget(form) | craue_default('<small>Optional</small>') }}
  {% endblock %}
  

Gotchas and Tips

Pitfalls

1. HTML Escaping: craue_default auto-escapes HTML, but nested filters (e.g., | upper) may break escaping. Use | raw cautiously:

   {{ unsafeHtml | craue_default('<p>Fallback</p>') | raw }}
   

2. Form Cloning Quirks:

   • Cloned forms do not preserve original form errors or submitted data. Reset the form manually if needed:

     {{ form_rest(form | craue_cloneForm) }}
     

   • Avoid cloning forms with complex constraints (e.g., Callback validators) that rely on object state.

3. Array Key Handling: craue_replaceKey and craue_removeKey treat keys as strings. For numeric keys, ensure type consistency:

   {{ array | craue_replaceKey(0, 'new_value') }}  {# Works #}
   {{ array | craue_replaceKey(1, 'new_value') }}  {# May fail if key is string '1' #}
   

Debugging

• Filter Chain Issues: Use Twig’s {{ dump() }} to inspect values before/after filters:

  {{ someValue | dump }} {{ someValue | craue_default('fallback') | dump }}
  

• Form Cloning Debug: Check if the cloned form’s getName() differs from the original (Symfony may append _clone).

Extension Points

1. Custom Placeholders: Override the default placeholder logic by extending the DecorateEmptyValueExtension:

   // src/Twig/CustomDefaultExtension.php
   class CustomDefaultExtension extends \Craue\TwigExtensionsBundle\Twig\Extension\DecorateEmptyValueExtension
   {
       protected function getDefaultPlaceholder(): string
       {
           return '<i class="fa fa-exclamation"></i>'; // Custom icon
       }
   }
   

   Register it as a decorator in config/services.yaml:

   services:
       App\Twig\CustomDefaultExtension:
           decorates: 'craue.twig_extension.decorate_empty_value'
           arguments: ['@.inner']
   

2. Array Translation: Extend craue_translateArray to support custom translation domains:

   {{ menu.items | craue_translateArray('admin') }}
   

   Modify the extension to accept a domain parameter.

3. Performance: For large arrays, craue_without or craue_replaceKey may trigger performance overhead. Cache results if used repeatedly:

   {% set filteredArray = cache(app.container.get('doctrine').getManager().getConnection().getWrappedConnection().getNativeConnection().getResource())('filtered_array', array | craue_without(excludedKeys), 3600) %}