Millwright Menu Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require zerkalica/millwright-menu-bundle dev-master
   

   Register the bundle in AppKernel.php:

   new Millwright\MenuBundle\MillwrightMenuBundle(),
   new Knp\Bundle\MenuBundle\KnpMenuBundle(),
   new Millwright\ConfigurationBundle\MillwrightConfigurationBundle()
   

2. Basic Configuration: Add to config.yml:

   knp_menu:
       twig: true
       default_renderer: twig
   

3. First Menu: Create app/config/menu.yml:

   millwright_menu:
       items:
           homepage:
               label: 'Home'
               route: homepage
       tree:
           main:
               type: navigation
               children:
                   homepage: ~
   

4. Render in Twig:

   {{ millwright_menu_render('main') }}
   

Implementation Patterns

1. Config-Driven Menus

• Centralized Management: Define menus in menu.yml (e.g., main, admin, user).
• Hierarchical Structure:

  tree:
      admin_panel:
          type: navigation
          children:
              dashboard: ~
              users:
                  children:
                      list: ~
                      create: ~
  

2. Dynamic Route Parameters

Pass dynamic parameters to adjust visibility/links:

{% for user in users %}
    {{ millwright_menu_render('user_actions', { id: user.id }) }}
{% endfor %}

3. Annotations for Controller-Specific Menus

Override menu items per action:

/**
 * @Route("/admin/users", name="admin_users")
 * @Menu(label="Users", translateDomain="AdminBundle")
 */
public function listAction() { ... }

4. Security Integration

Leverage @Secure (roles) and @SecureParam (ACL) from JMSSecurityExtraBundle:

/**
 * @Secure(roles="ROLE_ADMIN")
 * @SecureParam(name="user", permissions="EDIT")
 */
public function editAction(User $user) { ... }

5. Custom Renderers

Extend default Twig templates:

renderers:
    dropdown:
        renderer: twig
        rendererOptions:
            template: MyBundle:Menu:dropdown.html.twig

Gotchas and Tips

Pitfalls

1. Deprecated Dependencies:

   • Uses dev-master (last release: 2018). Test thoroughly; may conflict with newer Symfony/KnpMenu versions.
   • Requires JMSSecurityExtraBundle for ACL/role annotations.

2. Merge Conflicts:

   • Menu options from config, annotations, and tagged services merge hierarchically. Debug with:

     bin/console debug:container millwright_menu.menu_options
     

3. Translation Quirks:

   • translateDomain defaults to MillwrightMenuBundle. Override per item:

     items:
         fos_user_profile:
             translateDomain: FOSUserBundle
     

4. Route Resolution:

   • If route is missing, the item key is used as the route name. Explicitly define routes to avoid ambiguity.

Debugging Tips

• Dump Menu Structure:

  {{ dump(millwright_menu('main').getChildren()) }}
  

• Check Security Context: Use bin/console debug:security to verify roles/ACL permissions.

Extension Points

1. Custom Menu Providers: Tag services to contribute menus:

   <service id="my_menu_provider" class="My\MenuProvider">
       <tag name="millwright_menu.menu_options" order="200"/>
   </service>
   

2. Override Default Renderer: Extend MillwrightMenuBundle:Default:knp_menu.html.twig or register a custom renderer in menu.yml.

3. Dynamic Item Visibility: Use showNonAuthorized or showAsText for non-authorized users:

   items:
       admin_dashboard:
           showNonAuthorized: false
           showAsText: true
   

Performance

• Cache Menus: Enable KnpMenu’s cache (via knp_menu.cache config) to avoid rebuilding on every request.
• Avoid Over-Fetching: Limit routeParams to only necessary dynamic values.