Menu Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require disjfa/menu-bundle
   

   Add to config/bundles.php (Symfony):

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

2. Publish Configuration

   php artisan vendor:publish --provider="Disjfa\MenuBundle\DisjfaMenuBundle" --tag="config"
   

   This creates config/menu.php with default settings for site_menu and admin_menu.

3. First Use Case: Basic Site Menu Define a menu in config/menu.php:

   'site_menu' => [
       'items' => [
           ['label' => 'Home', 'route' => 'home'],
           ['label' => 'About', 'route' => 'about'],
       ],
   ],
   

   Render in a Twig template:

   {{ render(knp_menu('site_menu')) }}
   

Implementation Patterns

Menu Definition Workflows

1. YAML Configuration (Recommended) Use config/menu.yaml for maintainability:

   site_menu:
       items:
           - label: "Products"
             route: "products.index"
             children:
                 - label: "Category 1"
                   route: "products.category1"
   

2. Dynamic Menu Building Extend the builder via a service:

   // src/Service/CustomMenuBuilder.php
   class CustomMenuBuilder extends AbstractMenuBuilder
   {
       public function buildSiteMenu(): MenuNode
       {
           $menu = $this->factory->createItem('root');
           $menu->addChild('Dynamic Item', ['route' => 'dynamic_route']);
           return $menu;
       }
   }
   

   Register in services.yaml:

   services:
       App\Service\CustomMenuBuilder:
           tags: [disjfa.menu.builder]
   

3. Integration with Authentication Conditionally render items based on user roles:

   // In a Twig extension or controller
   $menu = $this->menuBuilder->buildSiteMenu();
   if (!$this->auth->isGranted('ROLE_ADMIN')) {
       $menu->removeChild('Admin Panel');
   }
   

Common Use Cases

• Admin Panel Menus Use admin_menu for backend navigation with nested CRUD routes:

  'admin_menu' => [
      'items' => [
          ['label' => 'Users', 'route' => 'admin.users.index', 'icon' => 'fas fa-users'],
          ['label' => 'Settings', 'route' => 'admin.settings.index', 'children' => [...]],
      ],
  ],
  

• Multi-Language Menus Override menu items per locale in config/menu_{locale}.php:

  'site_menu' => [
      'items' => [
          ['label' => 'Accueil', 'route' => 'home'], // French
      ],
  ],
  

• Active Menu Highlighting Use Twig’s is_active filter:

  <li class="{{ path('current_route') == 'home' ? 'active' : '' }}">
      {{ knp_menu_item('site_menu', 'Home') }}
  </li>
  

Gotchas and Tips

Pitfalls

1. Caching Issues

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

     php artisan cache:clear
     

   • Disable caching in config/menu.php for development:

     'cache' => false,
     

2. Route Name Conflicts

   • Ensure route names in menu items match exactly (case-sensitive). Use absolute URLs (/home) as fallbacks:

     ['label' => 'Home', 'uri' => '/home'],
     

3. KnpMenuBundle Dependency

   • Requires KnpMenuBundle. Install if missing:

     composer require knplabs/knp-menu-bundle
     

4. Twig Rendering Quirks

   • Use render() for full menus, knp_menu_item() for single items:

     {# Correct #}
     {{ render(knp_menu('site_menu')) }}
     
     {# Incorrect (throws error) #}
     {{ knp_menu('site_menu') }}
     

Debugging Tips

• Dump Menu Structure Add to a controller to inspect the menu tree:

  dd($this->menuBuilder->buildSiteMenu()->getChildren());
  

• Check Builder Priority If custom builders aren’t triggered, verify they’re tagged in services.yaml:

  tags: [disjfa.menu.builder]  # Must match exactly
  

Extension Points

1. Custom Menu Factories Override the default KnpMenuFactory by binding a new service:

   // config/services.php
   Disjfa\MenuBundle\Menu\MenuFactoryInterface::class => App\Menu\CustomFactory::class,
   

2. Event Listeners Listen for menu build events to modify items dynamically:

   // src/EventListener/MenuListener.php
   class MenuListener
   {
       public function onMenuBuild(MenuBuildEvent $event)
       {
           $event->getMenu()->addChild('Dynamic Item', ['route' => 'dynamic']);
       }
   }
   

   Register in events.yaml:

   Disjfa\MenuBundle\Event\MenuBuildEvent: ['listener' => App\EventListener\MenuListener]
   

3. Database-Backed Menus Fetch menu items from a database and merge with config:

   // In a custom builder
   $dbItems = $this->menuRepository->findAll();
   $menu = $this->factory->createItem('root');
   foreach ($dbItems as $item) {
       $menu->addChild($item['label'], ['route' => $item['route']]);
   }