Gabarit Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Add the bundle via Composer:

   composer require dvp/gabarit-bundle
   

   Enable the bundle in config/bundles.php (Symfony):

   Dvp\GabaritBundle\DvpGabaritBundle::class => ['all' => true],
   

2. Basic Usage The bundle provides Twig extensions for common formatting tasks. Test it by creating a simple Twig template:

   {{ 'Hello World'|gabarit_format }}
   

   Ensure your Twig environment is configured to autoload extensions (handled automatically by the bundle).

3. First Use Case Use gabarit_format to apply French typography rules (e.g., spacing, punctuation) to text:

   {{ 'Bonjour, comment ça va ?'|gabarit_format }}
   

   Output: Properly formatted French text with correct spacing around punctuation.

Implementation Patterns

Common Workflows

1. Text Formatting Apply typography rules to dynamic content:

   {% for message in messages %}
       {{ message.text|gabarit_format }}
   {% endfor %}
   

2. Conditional Formatting Use Twig’s if to apply formatting selectively:

   {% if is_french %}
       {{ text|gabarit_format }}
   {% else %}
       {{ text }}
   {% endif %}
   

3. Integration with Forms Format user-generated content (e.g., comments) before display:

   <div class="comment">
       {{ comment.body|gabarit_format }}
   </div>
   

4. Custom Extensions Extend the bundle’s functionality by creating a custom Twig extension that leverages its core logic:

   // src/Twig/AppExtension.php
   class AppExtension extends \Twig\Extension\AbstractExtension
   {
       public function getFunctions()
       {
           return [
               new \Twig\TwigFunction('custom_format', [$this, 'customFormat']),
           ];
       }
   
       public function customFormat($text)
       {
           // Reuse GabaritBundle's logic or wrap it
           return \Dvp\GabaritBundle\Twig\GabaritExtension::format($text);
       }
   }
   

Integration Tips

• Symfony Forms: Use the gabarit_format filter in form themes to auto-format labels or help text.
• API Responses: Apply formatting to JSON responses (via a response transformer) for consistency.
• Localization: Combine with Symfony’s translation system for multi-language support:

  {{ 'greeting'|trans|gabarit_format }}
  

Gotchas and Tips

Pitfalls

1. Twig Auto-Reloading If Twig extensions aren’t recognized, clear the cache:

   php bin/console cache:clear
   

2. Character Encoding Ensure input text is UTF-8 encoded to avoid formatting issues (e.g., mb_convert_encoding in PHP).

3. Performance Avoid applying gabarit_format to large blocks of text in loops without caching. Cache the result if reused:

   {% cache 'formatted_text' %}
       {{ long_text|gabarit_format }}
   {% endcache %}
   

4. Edge Cases The bundle may not handle all French typography rules (e.g., complex ligatures). Test with edge cases like:

   {{ '«Bonjour !» — dit-il.'|gabarit_format }}
   

Debugging

• Extension Availability: Verify the extension is registered by dumping Twig’s available filters:

  {{ dump(_twig_functions) }}
  

  Look for gabarit_format.

• Input/Output Mismatch: Compare raw input vs. formatted output to identify unexpected behavior:

  <pre>{{ dump('Input: ' ~ text ~ ' | Output: ' ~ text|gabarit_format) }}</pre>
  

Configuration Quirks

• No Public Config: The bundle has no configurable options (as of now). All logic is hardcoded.
• Extension Overrides: To modify behavior, fork the bundle or create a wrapper extension (see Implementation Patterns).

Extension Points

1. Custom Rules Extend the core formatting logic by subclassing Dvp\GabaritBundle\Twig\GabaritExtension and overriding methods like format().

2. New Filters Add more Twig filters by extending the bundle’s extension class:

   // Add to Dvp\GabaritBundle\Twig\GabaritExtension
   public function getFilters()
   {
       return [
           new \Twig\TwigFilter('custom_rule', [$this, 'customRule']),
           // ...
       ];
   }
   

3. Event Listeners Hook into Symfony events (e.g., kernel.response) to auto-format responses globally.