Config Knp Menu Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require jbouzekri/config-knp-menu-bundle
   

   Enable the bundle in config/bundles.php (or AppKernel.php for older Laravel versions):

   return [
       // ...
       Jb\Bundle\ConfigKnpMenuBundle\JbConfigKnpMenuBundle::class => ['all' => true],
       Knp\Bundle\MenuBundle\KnpMenuBundle::class => ['all' => true],
   ];
   

2. Create a navigation.yml: Place this file in Resources/config/navigation.yml within your bundle (e.g., src/MyBundle/Resources/config/navigation.yml). Example:

   menu.main:
       children:
           - label: 'Home'
             route: home
           - label: 'About'
             route: about
   

3. First Use Case: Use the menu in a Twig template:

   {{ knp_menu('menu.main') }}
   

   Ensure KnpMenuBundle is registered in your Twig environment (handled automatically by the bundle).

Implementation Patterns

Workflows

1. Bundle-Specific Menus: Define menus per bundle in Resources/config/navigation.yml. Example for an AdminBundle:

   menu.admin:
       children:
           - label: 'Users'
             route: admin_user_index
           - label: 'Settings'
             route: admin_settings
   

2. Dynamic Menu Items: Use PHP callbacks in YAML for dynamic logic:

   menu.dashboard:
       children:
           - label: 'Notifications'
             route: dashboard_notifications
             display: {{ app.hasUnreadNotifications() ? true : false }}
   

3. Inheritance & Overrides: Extend parent menus in child bundles by redefining the same key. Example:

   menu.main:
       children:
           - label: 'Home'
             route: home
           - label: 'Extended Menu'
             route: extended_route
   

4. Integration with Controllers: Pass menu names dynamically:

   return $this->render('template.html.twig', [
       'menu' => 'menu.' . $this->getUser()->getRole()
   ]);
   

5. Localization: Use translation placeholders for labels:

   menu.main:
       children:
           - label: '{{ "home"|trans }}'
             route: home
   

Gotchas and Tips

Pitfalls

1. YAML Syntax Errors:

   • Validate YAML with a linter (e.g., YAML Lint) before debugging.
   • Common issues: missing colons, incorrect indentation (use 2 spaces), or unquoted keys.

2. Menu Registration Timing:

   • Menus defined in navigation.yml must be loaded before the Twig template renders. If the menu appears empty, check:
     • The bundle is enabled in bundles.php.
     • The navigation.yml file exists in the correct path (Resources/config/).
     • No typos in the menu key (e.g., menu.main vs. menu_main).

3. Route Resolution:

   • Ensure routes referenced in YAML (e.g., route: home) are defined in your config/routes.yaml or bundle routes.
   • Use absolute routes (e.g., route: 'app_home') for clarity.

4. Caching:

   • KnpMenuBundle caches menus by default. Clear the cache after changes:

     php bin/console cache:clear
     

   • Disable caching in config/packages/knp_menu.yaml for development:

     knp_menu:
         twig:
             template: knp_menu.html.twig
             caching: false
     

Tips

1. Debugging:

   • Dump the menu structure in Twig for inspection:

     {{ dump(knp_menu('menu.main').children) }}
     

   • Check loaded menus via Symfony’s debug toolbar under the "KnpMenu" tab.

2. Configuration Quirks:

   • Boolean Values: Use true/false (not yes/no) in YAML for attributes like display.
   • Nested Menus: Use children for submenus and subchildren for deeper nesting (if supported by KnpMenuBundle).

3. Extension Points:

   • Custom Menu Builders: Extend the bundle’s MenuBuilder service to add logic:

     # config/services.yaml
     services:
         App\Menu\CustomMenuBuilder:
             tags: [knp_menu.menu_builder]
     

   • Twig Extensions: Override the default Twig template (knp_menu.html.twig) in your bundle’s templates/ directory.

4. Performance:

   • For large menus, lazy-load items using provider:

     menu.large:
         provider: App\Menu\LargeMenuProvider
     

   • Implement Knp\Menu\MenuItemInterface in your provider to fetch items dynamically.

5. Testing:

   • Mock menus in PHPUnit tests:

     $menu = $this->get('knp_menu.factory')->createItem('root');
     $this->get('knp_menu.renderer.twig')->render($menu);