Getting Started

Minimal Steps

Installation:
```
composer require alpixel/adminmenubundle
```
Ensure your composer.json supports Symfony 2.8 or 3.0.
Register the Bundle: Add to app/AppKernel.php (Symfony 2.x) or config/bundles.php (Symfony 3.x):
```
new Alpixel\Bundle\AdminMenuBundle\AlpixelAdminMenuBundle(),
```

Configure the Menu: Create app/config/menu.yml with a basic structure:

mainMenu:
    Dashboard:
        type: 'route'
        route: 'dashboard'
        icon: 'fa fa-dashboard'
        visibility: [ROLE_ADMIN]

Render the Menu: Use Twig in your template (e.g., base.html.twig):
```
{{ knp_menu_render('main', { depth: 2 }) }}
```
Clear Cache:
```
php bin/console cache:clear
```

First Use Case

Create a simple admin dashboard menu with 2-3 nested routes (e.g., Users, Products, Settings) and restrict visibility by role (e.g., ROLE_ADMIN).

Implementation Patterns

Core Workflows

Dynamic Menu Generation:

Define menus in menu.yml with type: 'route' (for Symfony routes) or type: 'url' (for external links).
Use visibility to control access via Symfony’s security roles (e.g., visibility: [ROLE_SUPER_ADMIN]).

Example:

mainMenu:
    Users:
        type: 'route'
        route: 'admin_user_index'
        icon: 'fa fa-users'
        visibility: [ROLE_ADMIN]
        children:
            Create:
                type: 'route'
                route: 'admin_user_create'
                icon: 'fa fa-plus'

Parameterized Routes: Pass static parameters to routes via parameters:

mainMenu:
    Products:
        type: 'route'
        route: 'admin_product_edit'
        parameters:
            id: 123

Icon Integration: Use Font Awesome (or other icon libraries) by prefixing classes with fa fa-:
```
icon: 'fa fa-cog'  # Renders as `<i class="fa fa-cog"></i>`
```
Template Integration:
- Place {{ knp_menu_render('main', { depth: 2 }) }} in your base template (e.g., templates/base.html.twig).
- Customize depth to control nesting levels (e.g., depth: 1 for flat menus).
Event-Driven Extensions: Listen to alpixel_admin_menu.build events to dynamically modify menus at runtime (see Gotchas).

Integration Tips

Symfony Security:
- Ensure roles in visibility (e.g., ROLE_ADMIN) are defined in security.yml or your firewall configuration.
- Example:
```
# security.yml
role_hierarchy:
    ROLE_ADMIN: [ROLE_USER]
```
Translation Support:
- Wrap menu labels in Twig translation tags for i18n:
```
{{ 'menu.dashboard'|trans }}
```
- Configure translations in menu.yml via trans keys (if the bundle supports it; may require customization).

Asset Management:

Include Font Awesome in your base template:

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">

Testing:

Mock the menu builder in PHPUnit to test visibility logic:

$menu = $this->get('knp_menu.menu_factory')->createMenu('main', $this->get('request_stack')->getCurrentRequest());

Gotchas and Tips

Pitfalls

Deprecated Symfony Version:
- The bundle was last updated in 2016 and targets Symfony 2.8/3.0. Use with caution in newer versions (e.g., Symfony 5+).
- Workaround: Fork the repo and update dependencies (e.g., knp-menu-bundle) if needed.
Cache Invalidation:
- Changes to menu.yml require cache:clear to take effect. Forgetting this is a common issue.
- Tip: Use cache:pool:clear knp_menu.cache_pool for faster iteration during development.
Event Listener Conflicts:
- The bundle fires alpixel_admin_menu.build events, but these may conflict with other menu builders (e.g., knp_menu).
- Debugging: Check app/logs/dev.log for event listener errors.
Visibility Logic:
- Visibility checks are strict: If the user lacks all specified roles, the menu item is hidden (no partial matching).
- Example: visibility: [ROLE_ADMIN, ROLE_SUPER_ADMIN] requires either role.
Icon Rendering:
- Icons rely on client-side CSS. If icons don’t render, verify:
  - The icon library (e.g., Font Awesome) is loaded.
  - The class prefix (fa fa-) is correct.

Debugging Tips

Dump Menu Structure: Use Twig’s dump to inspect the generated menu:
```
{{ dump(knp_menu('main', { depth: 10 }).getChildren()) }}
```

Check Events: Enable Symfony’s event dispatcher debug mode:

# config/packages/dev/debug.yaml
framework:
    profiler: { only_exceptions: false }

Override Menu Builder: Extend the bundle’s menu builder to add custom logic:

// src/Service/CustomMenuBuilder.php
use Alpixel\Bundle\AdminMenuBundle\Menu\MenuBuilder;

class CustomMenuBuilder extends MenuBuilder {
    public function buildMenu() {
        parent::buildMenu();
        // Add dynamic items here
        $this->menu->addChild('Dynamic Item', ['route' => 'dynamic_route']);
    }
}

Extension Points

Dynamic Menu Items: Use the alpixel_admin_menu.build event to inject items programmatically:

// src/EventListener/AddDynamicMenuItem.php
use Alpixel\Bundle\AdminMenuBundle\Event\MenuEvent;

class AddDynamicMenuItem {
    public function onBuildMenu(MenuEvent $event) {
        $menu = $event->getMenu();
        $menu->addChild('Dynamic', ['route' => 'dynamic_route']);
    }
}

services:
    App\EventListener\AddDynamicMenuItem:
        tags:
            - { name: kernel.event_listener, event: alpixel_admin_menu.build, method: onBuildMenu }

Custom Menu Types: Extend the bundle to support non-route items (e.g., type: 'callback' for JavaScript links):
```
// src/DependencyInjection/Configuration.php
$builder->addNode('custom_types', 'array')
    ->info('Define custom menu item types');
```
Update the menu builder to handle new types.
Theme Integration: Override the bundle’s Twig templates (located in Resources/views) to customize rendering (e.g., add badges, dropdowns).

Adminmenubundle Laravel Package