Sonata Extra Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require draw/sonata-extra-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Draw\SonataExtraBundle\DrawSonataExtraBundle::class => ['all' => true],
   ];
   

2. First Use Case:

   • Constructor Argument Simplification: Update an existing Sonata admin class (e.g., UserAdmin) to omit the hardcoded entity class in YAML:

     # config/packages/sonata_admin.yaml
     App\Sonata\Admin\UserAdmin:
         arguments: [~, ~, ~]  # No need to repeat User::class
     

     Define the default in the constructor:

     public function __construct($code, $class = User::class, $baseControllerName = null) {
         parent::__construct($code, $class, $baseControllerName);
     }
     

3. Verify Compiler Pass: Clear cache to trigger the compiler pass:

   php bin/console cache:clear
   

Implementation Patterns

Constructor Argument Workflow

1. Refactor Existing Admins:

   • Replace repetitive YAML arguments with constructor defaults.
   • Example for PostAdmin:

     App\Sonata\Admin\PostAdmin:
         arguments: [~, ~, ~]  # No Post::class hardcoded
     

     public function __construct($code, $class = Post::class, $baseControllerName = null) {
         parent::__construct($code, $class, $baseControllerName);
     }
     

2. Order Matters:

   • Ensure the compiler pass runs after any other admin configuration (e.g., in sonata_admin extension).
   • Override the compiler pass in a custom bundle if needed:

     // src/DependencyInjection/Compiler/ExtraAdminPass.php
     use Draw\SonataExtraBundle\DependencyInjection\Compiler\AdminArgumentPass;
     
     public function process(ContainerBuilder $container) {
         $container->addCompilerPass(new AdminArgumentPass());
     }
     

Menu Depth Optimization

1. Enable Feature: Add to config/packages/draw_sonata_extra.yaml:

   draw_sonata_extra:
       fix_menu_depth: true
   

2. Customize Logic: Extend the menu builder to add conditions:

   // src/Twig/Extension/SonataMenuExtension.php
   public function getMenuDepthFix($menu, $depth = 1) {
       if ($depth === 1 && count($menu->getChildren()) === 1) {
           return $this->getMenuDepthFix($menu->getChildren()[0], $depth + 1);
       }
       return $menu;
   }
   

3. Template Integration: Override Sonata’s base template to use the new menu structure:

   {# templates/sonata_admin/layout.html.twig #}
   {% block sonata_menu %}
       {{ sonata_menu.render('level1', { 'depthFix': true }) }}
   {% endblock %}
   

Template Types

1. Extend Default Assets: Add custom JS/CSS to the extra_javascripts or extra_stylesheets blocks:

   {# templates/sonata_admin/layout.html.twig #}
   {% block sonata_admin_assets_extra_javascripts %}
       {{ parent() }}
       <script src="{{ asset('bundles/sonataextra/js/custom.js') }}"></script>
   {% endblock %}
   

2. Create Custom Template Types: Register new template types in services.yaml:

   sonata.admin.template.type:
       sonata_extra_custom:
           path: '@DrawSonataExtraBundle/Resources/views/'
           context: sonata.admin.template.type.custom
   

Gotchas and Tips

Pitfalls

1. Compiler Pass Timing:

   • If the compiler fails silently, check for circular dependencies or missing services.
   • Debug with:

     php bin/console debug:container draw_sonata_extra.admin_argument_pass
     

2. Menu Depth Overrides:

   • The fix_menu_depth feature only applies to top-level menus (depth = 1).
   • For nested menus, override the sonata.menu.twig template:

     {# templates/sonata_admin/sonata_menu.html.twig #}
     {% if menu.children|length == 1 and depth == 1 %}
         {{ render_menu(menu.children[0], depth + 1) }}
     {% else %}
         {{ render_menu(menu, depth) }}
     {% endif %}
     

3. Template Type Conflicts:

   • Avoid naming collisions with Sonata’s default template types (e.g., sonata_admin).
   • Use unique prefixes (e.g., sonata_extra_custom).

Debugging

1. Constructor Argument Issues:

   • Verify the exact argument name match in the constructor (case-sensitive).
   • Check the compiler pass logs:

     php bin/console debug:config draw_sonata_extra
     

2. Menu Rendering:

   • Disable fix_menu_depth temporarily to isolate issues:

     draw_sonata_extra:
         fix_menu_depth: false
     

   • Inspect the rendered menu with Twig’s dump():

     {{ dump(sonata_menu.menu) }}
     

Extension Points

1. Custom Compiler Pass: Extend the AdminArgumentPass to support additional logic:

   // src/DependencyInjection/Compiler/CustomAdminPass.php
   use Draw\SonataExtraBundle\DependencyInjection\Compiler\AdminArgumentPass;
   
   class CustomAdminPass extends AdminArgumentPass {
       protected function getDefaultArgument($reflection, $argument) {
           // Custom logic here
           return parent::getDefaultArgument($reflection, $argument);
       }
   }
   

2. Dynamic Menu Depth: Add a dynamic condition to the menu fix:

   draw_sonata_extra:
       fix_menu_depth:
           enabled: true
           exclude_routes: ['sonata_admin_dashboard']
   

3. Asset Management: Override the asset block to conditionally load resources:

   {% block sonata_admin_assets_extra_javascripts %}
       {% if app.user.isGranted('ROLE_SUPER_ADMIN') %}
           {{ parent() }}
       {% endif %}
   {% endblock %}