Menu Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require nucleos/menu-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Nucleos\MenuBundle\NucleosMenuBundle::class => ['all' => true],
   ];
   

2. First Use Case: Define a menu in YAML (e.g., config/menus/main.yaml):

   main:
       label: 'Main Menu'
       items:
           - label: 'Home'
             uri: '/'
             icon: 'fas fa-home'
           - label: 'About'
             uri: '/about'
   

   Register the menu in config/packages/nucleos_menu.yaml:

   nucleos_menu:
       menus:
           main: '@main'
   

3. Render in Twig:

   {{ render_menu('main') }}
   

Implementation Patterns

Menu Definition Workflows

1. YAML Configuration:

   • Use config/menus/*.yaml for static menus (e.g., main.yaml, admin.yaml).
   • Reference files with @filename syntax in nucleos_menu.yaml.

2. Dynamic Menus via Services:

   • Extend MenuBuilder to fetch menus from a database or API:

     // src/Service/CustomMenuBuilder.php
     use Nucleos\MenuBundle\Menu\MenuBuilderInterface;
     
     class CustomMenuBuilder implements MenuBuilderInterface {
         public function build(string $name): array {
             return $this->fetchFromDatabase($name);
         }
     }
     

   • Register as a service in services.yaml:

     services:
         Nucleos\MenuBundle\Menu\MenuBuilderInterface: '@custom_menu_builder'
     

3. Nested Menus:

   # config/menus/admin.yaml
   admin:
       label: 'Admin Panel'
       items:
           - label: 'Users'
             uri: '/admin/users'
             children:
                 - label: 'List'
                   uri: '/admin/users/list'
                 - label: 'Create'
                   uri: '/admin/users/create'
   

4. Conditional Items: Use Twig logic in templates or PHP callbacks in YAML:

   items:
       - label: 'Dashboard'
         uri: '/dashboard'
         visible: '@=user.hasRole("ROLE_ADMIN")'
   

Integration Tips

• Twig Extensions: Override render_menu in Twig to customize output:

  {% macro render_menu(menu, options={}) %}
      <nav class="custom-menu">
          {% for item in menu.items %}
              <a href="{{ item.uri }}">{{ item.label }}</a>
          {% endfor %}
      </nav>
  {% endmacro %}
  

• Event Listeners: Modify menus dynamically via MenuEvents:

  // src/EventListener/MenuListener.php
  use Nucleos\MenuBundle\Event\MenuEvent;
  
  class MenuListener {
      public function onBuildMenu(MenuEvent $event) {
          $event->getMenu()->addItem('custom_item', [
              'label' => 'Dynamic Item',
              'uri' => '/dynamic',
          ]);
      }
  }
  

  Register in services.yaml:

  services:
      App\EventListener\MenuListener:
          tags:
              - { name: 'kernel.event_listener', event: 'nucleos_menu.build', method: 'onBuildMenu' }
  

Gotchas and Tips

Pitfalls

1. Caching Issues:

   • Menus are cached by default. Clear cache after changes:

     php bin/console cache:clear
     

   • Disable caching in nucleos_menu.yaml for development:

     nucleos_menu:
         cache: false
     

2. YAML Syntax Errors:

   • Validate YAML files with symfony/validator or use an online validator.
   • Common errors: missing colons (:), incorrect indentation, or undefined references (@filename).

3. Overwriting Defaults:

   • Avoid naming custom menus main or admin to prevent conflicts with future updates.

4. Twig Template Overrides:

   • Ensure your Twig templates extend the base nucleos_menu.html.twig if customizing:

     {% extends 'nucleos_menu.html.twig' %}
     {% block menu_item %}
         <li class="custom-class">{{ item.label }}</li>
     {% endblock %}
     

Debugging

• Dump Menu Structure: Use Twig’s dump to inspect the menu array:

  {{ dump(render_menu('main')) }}
  

• Symfony Debug Toolbar: Check the Menu tab for built menus and their metadata.

Extension Points

1. Custom Menu Builders: Implement MenuBuilderInterface for non-YAML sources (e.g., Doctrine entities):

   class DoctrineMenuBuilder implements MenuBuilderInterface {
       public function build(string $name): array {
           return $this->entityManager->getRepository(MenuEntity::class)
               ->findBy(['name' => $name]);
       }
   }
   

2. Menu Item Transformers: Use MenuItemTransformerInterface to modify items post-build:

   class UrlTransformer implements MenuItemTransformerInterface {
       public function transform(array $item): array {
           $item['uri'] = route($item['route'], [], $item['route_params']);
           return $item;
       }
   }
   

   Register in services.yaml:

   services:
       App\Transformer\UrlTransformer:
           tags:
               - { name: 'nucleos_menu.item_transformer' }
   

3. Localization: Use Symfony’s translation system for labels:

   items:
       - label: '@trans("menu.home")'
         uri: '/'
   

   Define translations in translations/messages.en.yaml:

   menu:
       home: 'Home'