Oxy Menu Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require anismechri/oxy-menu-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Anismechri\OxyMenuBundle\OxyMenuBundle::class => ['all' => true],
   ];
   

2. Basic Configuration Define a menu in config/packages/oxy_menu.yaml:

   oxy_menu:
       menus:
           main:
               items:
                   - label: 'Home'
                     route: 'homepage'
                   - label: 'About'
                     route: 'about'
   

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

   {{ render(oxy_menu('main')) }}
   

Implementation Patterns

Menu Definition

• YAML Configuration: Define menus in config/packages/oxy_menu.yaml for static menus.

  oxy_menu:
      menus:
          admin:
              items:
                  - label: 'Dashboard'
                    route: 'admin_dashboard'
                    children:
                        - label: 'Users'
                          route: 'admin_users'
  

• Dynamic Menus via Services: Extend functionality by creating a service to fetch menu items dynamically:

  // src/Service/DynamicMenuBuilder.php
  class DynamicMenuBuilder
  {
      public function build(): array
      {
          return [
              ['label' => 'Dynamic Item', 'route' => 'dynamic_route'],
          ];
      }
  }
  

  Register it as a compiler pass to merge with static menus.

Twig Integration

• Render Menus: Use the oxy_menu Twig function to render menus:

  {% set menu = oxy_menu('main') %}
  <nav>{{ menu.render() }}</nav>
  

• Customize Output: Override Twig templates in templates/oxy_menu/ to modify rendering logic.

Event-Driven Extensions

• Menu Events: Listen to oxy_menu.build to modify menu items dynamically:

  // src/EventListener/MenuBuilderListener.php
  class MenuBuilderListener
  {
      public function onBuild(MenuBuildEvent $event)
      {
          $event->addItem('new_item', [
              'label' => 'Dynamic Item',
              'route' => 'dynamic_route',
          ]);
      }
  }
  

  Register the listener in services.yaml:

  services:
      App\EventListener\MenuBuilderListener:
          tags:
              - { name: 'kernel.event_listener', event: 'oxy_menu.build', method: 'onBuild' }
  

Routing and Access Control

• Route-Based Menus: Use Symfony routes for menu items to leverage routing features (e.g., generateUrl).
• Access Control: Filter menu items based on user roles:

  {% for item in oxy_menu('main').items %}
      {% if is_granted('ROLE_ADMIN') or item.route == 'homepage' %}
          <a href="{{ path(item.route) }}">{{ item.label }}</a>
      {% endif %}
  {% endfor %}
  

Gotchas and Tips

Configuration Quirks

• YAML Syntax: Ensure YAML indentation is correct (2 spaces per level). Incorrect indentation may cause silent failures.
• Menu Key Conflicts: Menu keys (e.g., main) must be unique. Overwriting a key will silently replace the existing menu.

Debugging

• Missing Menus: Verify the bundle is registered in bundles.php and the config file exists at config/packages/oxy_menu.yaml.
• Twig Errors: Clear the cache (php bin/console cache:clear) if Twig templates fail to load after updates.
• Event Listener Priority: Use the priority option in tags to control the order of event listeners:

  tags:
      - { name: 'kernel.event_listener', event: 'oxy_menu.build', method: 'onBuild', priority: 10 }
  

Extension Points

• Custom Item Types: Extend the bundle by adding support for custom item types (e.g., URLs, callbacks):

  // src/Twig/Extension/OxyMenuExtension.php
  class OxyMenuExtension extends \Twig_Extension
  {
      public function getFunctions()
      {
          return [
              new \Twig_SimpleFunction('oxy_menu_item', [$this, 'createCustomItem']),
          ];
      }
  
      public function createCustomItem(string $type, array $options)
      {
          return new CustomMenuItem($type, $options);
      }
  }
  

  Use in Twig:

  {{ oxy_menu_item('url', {url: '/custom-url', label: 'Custom'}) }}
  

Performance

• Caching: Menus are cached by default. Disable caching in oxy_menu.yaml for dynamic menus:

  oxy_menu:
      cache: false
  

• Lazy Loading: For large menus, implement lazy loading via JavaScript or server-side pagination.

Migration Notes

• Symfony 5+ Compatibility: While the bundle supports Symfony 5, test thoroughly as the last release is from 2020. Update dependencies if needed:

  composer require symfony/error-handler:^5.4 symfony/event-dispatcher:^5.4