Menu Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require awaresoft/menu-bundle
   

   Note: Due to symlinking requirements, follow the README’s local setup instructions if modifying the bundle.

2. Enable the Bundle: Add to config/bundles.php:

   Awaresoft\MenuBundle\AwaresoftMenuBundle::class => ['all' => true],
   

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

   {{ knp_menu_render('main_menu', {
       'current_uri': app.request.uri,
       'deep': true,
       'template': '@AwaresoftMenu/menu.html.twig'
   }) }}
   

   Default template: @AwaresoftMenu/menu.html.twig (override via config).

4. Configuration: Override defaults in config/packages/awaresoft_menu.yaml:

   awaresoft_menu:
       templates:
           menu: 'path/to/custom_template.html.twig'
       sonata_integration: true  # Enable if using SonataAdmin
   

Implementation Patterns

Core Workflows

1. Dynamic Menu Building:

   • Use builders to construct menus programmatically:

     $menu = $this->menuFactory->createItem('root');
     $menu->addChild('Dashboard', ['route' => 'dashboard']);
     $this->menuFactory->add('main_menu', $menu);
     

   • Tip: Cache builders for performance:

     # config/packages/awaresoft_menu.yaml
     awaresoft_menu:
         cache: true
     

2. SonataAdmin Integration:

   • Auto-generate admin menus via annotations:

     use Awaresoft\MenuBundle\Annotation\Menu;
     use Sonata\AdminBundle\Annotation\Route;
     
     /**
      * @Menu("admin_menu")
      * @Route("admin", name="admin_dashboard")
      */
     class DashboardController extends Controller { ... }
     

   • Trigger rebuild after adding new admin classes:

     php bin/console awaresoft:menu:build
     

3. Twig Extensions:

   • Access menus directly in Twig:

     {% set menu = app.service('awaresoft.menu.menu_factory').get('main_menu') %}
     {{ menu|knp_menu_render({deep: true}) }}
     

4. Multi-Language Menus:

   • Use locale-aware builders:

     $menu = $this->menuFactory->createItem('root', ['locale' => 'en']);
     $menu->addChild('Home', ['route' => 'home_en']);
     

Integration Tips

• Event Listeners: Subscribe to awaresoft.menu.build to modify menus dynamically:

  use Awaresoft\MenuBundle\Event\MenuBuildEvent;
  
  public function onMenuBuild(MenuBuildEvent $event) {
      $event->getMenu()->addChild('Custom Item', ['route' => 'custom']);
  }
  

  Register in services.yaml:

  services:
      App\EventListener\MenuListener:
          tags:
              - { name: kernel.event_listener, event: awaresoft.menu.build, method: onMenuBuild }
  

• Doctrine Fixtures: Pre-populate menus in fixtures:

  public function load(ObjectManager $manager) {
      $menuFactory = $this->container->get('awaresoft.menu.menu_factory');
      $menu = $menuFactory->createItem('fixture_menu');
      $menu->addChild('Test', ['route' => 'test']);
      $menuFactory->add('fixture_menu', $menu);
  }
  

Gotchas and Tips

Common Pitfalls

1. Symlinking Issues:

   • Problem: Forgetting to remove Composer-installed versions before symlinking.
   • Fix: Run composer remove awaresoft/menu-bundle and clear cache (php bin/console cache:clear).

2. Caching Quirks:

   • Problem: Menus not updating after changes.
   • Fix: Clear the menu cache explicitly:

     php bin/console awaresoft:menu:clear-cache
     

   • Tip: Disable caching in awaresoft_menu.yaml during development:

     awaresoft_menu:
         cache: false
     

3. SonataAdmin Conflicts:

   • Problem: Menus not appearing in SonataAdmin.
   • Fix: Ensure sonata_integration: true and rebuild menus:

     php bin/console awaresoft:menu:build --env=prod
     

4. Route Resolution:

   • Problem: Menu items linking to undefined routes.
   • Fix: Use absolute routes or verify route names exist:

     {{ path('dashboard') }}  {# Instead of hardcoded URLs #}
     

Debugging

• Dump Menu Structure: Use the debug command to inspect menus:

  php bin/console awaresoft:menu:debug main_menu
  

• Twig Debugging: Enable Twig strict mode to catch template errors:

  twig:
      strict_variables: true
  

Extension Points

1. Custom Templates: Override the default template by copying @AwaresoftMenu/menu.html.twig to your theme and updating the config:

   awaresoft_menu:
       templates:
           menu: 'YourThemeBundle:menu:custom.html.twig'
   

2. Menu Providers: Create a custom provider to fetch menus from external sources (e.g., API):

   use Awaresoft\MenuBundle\Provider\MenuProviderInterface;
   
   class ApiMenuProvider implements MenuProviderInterface {
       public function getMenu(string $name) { ... }
   }
   

   Register in services.yaml:

   services:
       App\Provider\ApiMenuProvider:
           tags:
               - { name: awaresoft.menu.provider, alias: 'api_menu' }
   

3. Menu Builders: Extend the base builder for custom logic:

   use Awaresoft\MenuBundle\Builder\MenuBuilder;
   
   class CustomMenuBuilder extends MenuBuilder {
       protected function buildMenu() {
           // Custom logic
           $this->addChild('Custom Root', ['route' => 'custom_root']);
       }
   }
   

   Register as a service:

   services:
       App\Builder\CustomMenuBuilder:
           tags:
               - { name: awaresoft.menu.builder, alias: 'custom_menu' }
   

Configuration Quirks

• Locale Handling: Menus are locale-agnostic by default. To enforce locale-specific menus:

  awaresoft_menu:
      locale_aware: true
  

• Priority System: Menu items can have priority (higher = earlier):

  $menu->addChild('High Priority', ['route' => 'high'], ['priority' => 10]);