Twig Extension Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require dms/twig-extension-bundle
   

   Add the bundle to config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3-):

   DMS\Bundle\TwigExtensionBundle\DMSTwigExtensionBundle::class => ['all' => true],
   

2. Enable Extensions: Configure enabled extensions in config/packages/dms_twig_extension.yaml (Symfony 4+) or app/config/config.yml (Symfony 3-):

   dms_twig_extension:
       fabpot_extensions:
           text: true
           debug: false
           intl: true
           i18n: false  # Avoid conflicts with Symfony Translator
       dms_extensions:
           textual_date: true
   

3. First Use Case: Use the textual_date filter in a Twig template to convert timestamps to human-readable strings:

   {{ timestamp|textual_date }}
   

   Output: "2 days ago" (if timestamp is a Unix timestamp from 2 days ago).

Implementation Patterns

Core Workflows

1. Fabpot Extensions:

   • Text: Use truncate and wordwrap filters for text manipulation:

     {{ long_text|truncate(50, '...') }}  {# Truncate to 50 chars #}
     {{ text|wordwrap(80) }}             {# Wrap text at 80 chars #}
     

   • Intl: Localize dates with date filter (requires Intl extension):

     {{ timestamp|date('medium') }}  {# Localized date format #}
     

   • Debug: Use debug filter for token parsing (dev-only):

     {{ _context|debug }}  {# Dump Twig context #}
     

2. DMS Extensions:

   • Textual Date: Customize output via configuration:

     dms_twig_extension:
         dms_extensions:
             textual_date:
                 past_string: "ago"
                 future_string: "from now"
                 precision: 4  {# Days, hours, minutes, seconds #}
     

     Usage:

     {{ timestamp|textual_date }}
     

3. Integration Tips:

   • Symfony Forms: Combine with form_row for truncated labels:

     {{ form_label(form.field)|truncate(20) }} {{ form_widget(form.field) }}
     

   • API Responses: Use textual_date in JSON responses via Twig’s json_encode:

     {{ {'created_at': timestamp}|json_encode|raw }}
     

Gotchas and Tips

Pitfalls

1. i18n Conflict:

   • The i18n extension (Symfony Translator) is disabled by default to avoid conflicts with Symfony’s built-in translator. Enable only if you’re not using Symfony’s translation system.

2. Intl Dependency:

   • The intl extension requires the PHP intl extension. Verify with:

     php -m | grep intl
     

   • If missing, install via:

     pecl install intl
     

3. Textual Date Precision:

   • The textual_date filter defaults to 4 precision levels (days/hours/minutes/seconds). Overriding precision in config may break formatting if set too low (e.g., precision: 1 hides hours/minutes).

4. Debug Filter:

   • The debug filter is resource-intensive. Use only in development:

     # config/packages/dms_twig_extension.yaml
     dms_twig_extension:
         fabpot_extensions:
             debug: "%kernel.debug%"  {# Auto-disable in prod #}
     

Debugging

• Filter Not Working?:

  • Verify the extension is enabled in config.
  • Check for typos in filter names (e.g., textual_date vs. textualdate).
  • Clear cache:

    php bin/console cache:clear
    

• Intl Errors:

  • Ensure ext-intl is enabled in php.ini and restart your web server.

Extension Points

1. Custom Filters: Extend the bundle by creating a custom Twig extension and merging it:

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

   Register it in config/packages/twig.yaml:

   twig:
       extensions:
           - App\Twig\AppExtension
   

2. Override Textual Date: Subclass DMS\Bundle\TwigExtensionBundle\Twig\TextualDateExtension and override formatDate():

   class CustomTextualDateExtension extends \DMS\Bundle\TwigExtensionBundle\Twig\TextualDateExtension
   {
       protected function formatDate(\DateTimeInterface $dateTime)
       {
           // Custom logic
       }
   }
   

   Register it in services.yaml:

   services:
       App\Twig\CustomTextualDateExtension:
           tags: ['twig.extension']