Twig Extensions Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer (ensure compatibility with Symfony 8+ and PHP 8.2+):

   composer require sonata-project/twig-extensions:^2.6.0
   

   Register the service provider in config/app.php under providers:

   SonataProject\Twig\Extensions\TwigExtensionsServiceProvider::class,
   

2. First Use Case Use the sonata_block Twig extension to render a block in a template:

   {{ sonata_block('block_name') }}
   

   Verify the block exists in your Sonata admin configuration (e.g., config/packages/sonata_admin.yaml). Note: Ensure your Symfony version is 8.0+ (this release drops support for Symfony 7.x).

3. Where to Look First

   • Documentation: SonataProject Docs (if available).
   • Source Code: Focus on src/Twig/Extension/ for core extensions.
   • Configuration: Check config/packages/sonata_twig_extensions.yaml for default settings.
   • Symfony 8 Compatibility: Review composer.json constraints for PHP 8.2+ and Symfony 8+.

Implementation Patterns

Common Workflows

1. Dynamic Block Rendering Use sonata_block with dynamic names (e.g., {{ sonata_block('user_' ~ user.id) }}) for user-specific blocks. Example: Render a dashboard block conditionally:

   {% if is_granted('ROLE_ADMIN') %}
       {{ sonata_block('admin_dashboard') }}
   {% endif %}
   

2. Form Integration Leverage sonata_form for enhanced Symfony forms:

   {{ form_start(form) }}
       {{ sonata_form_row(form.field) }} {# Renders field with Sonata styling #}
   {{ form_end(form) }}
   

3. Asset Management Use sonata_asset for optimized asset handling:

   {{ sonata_asset('bundles/sonataadmin/css/style.css') }}
   

4. Localization Extend translations with sonata_trans:

   {{ 'sonata.admin.block.title'|trans }}
   

Integration Tips

• Symfony 8 Flex: Autoloading is handled automatically; ensure symfony/flex is up to date.
• Cache Warmup: Run php bin/console cache:clear after adding new blocks or extensions.
• Custom Extensions: Extend the Twig environment in App\Twig\AppExtension:

  use SonataProject\Twig\Extensions\TwigExtensions;
  
  public function getExtensions(TwigEnvironment $env) {
      return array_merge(parent::getExtensions($env), [
          new TwigExtensions(),
      ]);
  }
  

  Note: Test with PHP 8.2+ and Symfony 8+ to avoid compatibility issues.

Gotchas and Tips

Pitfalls

1. Block Registration

   • Issue: sonata_block fails with "Block not found" errors.
   • Fix: Ensure the block is registered in Sonata Admin (services.yaml or sonata_admin.yaml):

     sonata.block:
         blocks:
             sonata.admin.block.admin_list:
                 class: Sonata\AdminBundle\Block\BlockAdminListBlock
                 contexts: [admin]
     

2. Twig Environment Conflicts

   • Issue: Extensions not loading due to duplicate Twig environments.
   • Fix: Disable Symfony’s default Twig bundle if conflicts arise:

     # config/bundles.php
     Twig\ExtraBundle\TwigExtraBundle::class => ['all' => false],
     

3. Asset Paths

   • Issue: sonata_asset returns 404 for bundles.
   • Fix: Verify the bundle is enabled in config/bundles.php and assets are built:

     php bin/console assets:install
     

4. PHP/Symfony Version Mismatch

   • Issue: Package fails to load with PHP 8.1 or Symfony 7.x.
   • Fix: Update composer.json to enforce PHP 8.2+ and Symfony 8+:

     {
         "require": {
             "php": "^8.2",
             "symfony/*": "^8.0"
         }
     }
     

Debugging

• Enable Twig Debugging: Add to config/packages/twig.yaml:

  twig:
      debug: '%kernel.debug%'
      strict_variables: '%kernel.debug%'
  

• Log Block Errors: Use Symfony’s profiler to inspect block rendering:

  {% if app.debug %}
      {{ dump(sonata_block('block_name', {'debug': true})) }}
  {% endif %}
  

Extension Points

1. Custom Filters Create a custom Twig filter in App\Twig\AppExtension:

   public function getFilters() {
       return [
           new \Twig\TwigFilter('custom_filter', [$this, 'customFilterMethod']),
       ];
   }
   

2. Override Existing Extensions Replace Sonata’s default extensions by redefining the service:

   # config/services.yaml
   SonataProject\Twig\Extensions\TwigExtensions:
       arguments:
           $someDependency: '@custom.service'
   

3. Event Listeners Hook into Sonata’s block events (e.g., sonata.block.pre_render):

   use Sonata\BlockBundle\Event\BlockEvent;
   
   public static function onPreRender(BlockEvent $event) {
       $event->getBlock()->setSetting('custom_key', 'value');
   }
   

   Note: Test event listeners with Symfony 8+ to ensure compatibility.

4. Symfony 8-Specific Adjustments

   • Attribute-Based Configuration: Update any custom bundles to use Symfony 8’s attribute syntax if migrating from older versions.
   • Dependency Injection: Verify DI containers are compatible with Symfony 8’s autowiring improvements.