KnpMenuBundle

https://symfony.com/bundles/KnpMenuBundle/current/
Admin
KnpMenuBundle is a Symfony bundle that provides an easy and flexible way to create, manage, and...
Tokens:6,327
Snippets:77
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install KnpMenuBundle with Composer

Source: https://symfony.com/bundles/KnpMenuBundle/current/index.html

Use this command to download the latest stable version of the KnpMenuBundle. Ensure Composer is installed globally.

```bash
composer require knplabs/knp-menu-bundle
```

--------------------------------

### Get and Render a Menu with Options

Source: https://symfony.com/bundles/KnpMenuBundle/current/menu_builder_service.html

Retrieve a menu using `knp_menu_get` and pass options to its builder method. Then, render the retrieved menu object.

```twig
{% set menu = knp_menu_get('sidebar', [], {include_homepage: false}) %}
{{ knp_menu_render(menu) }}
```

--------------------------------

### Get Menu with Builder Options - PHP

Source: https://symfony.com/bundles/KnpMenuBundle/current/index.html

Retrieve a menu item in PHP, passing options to the menu builder. This enables customization of menu construction.

```php
<?php $menuItem = $view['knp_menu']->get('my_main_menu', [], [
    'some_option' => 'my_value'
]) ?>
<?php echo $view['knp_menu']->render($menuItem) ?>
```

--------------------------------

### Get Menu Item for Later Rendering - PHP

Source: https://symfony.com/bundles/KnpMenuBundle/current/index.html

Retrieve a menu item using PHP, which can then be rendered. This provides flexibility in how and when menus are displayed.

```php
<?php $menuItem = $view['knp_menu']->get('my_main_menu') ?>
<?php echo $view['knp_menu']->render($menuItem) ?>
```

--------------------------------

### Get Specific Menu Branch - PHP

Source: https://symfony.com/bundles/KnpMenuBundle/current/index.html

Retrieve a specific menu branch using PHP, allowing you to render only a part of the menu structure.

```php
<?php $menuItem = $view['knp_menu']->get('my_main_menu', ['Contact']) ?>
<?php echo $view['knp_menu']->render(['my_main_menu', 'Contact']) ?>
```

--------------------------------

### Get Menu with Builder Options - Twig

Source: https://symfony.com/bundles/KnpMenuBundle/current/index.html

Retrieve a menu item while passing options to its builder. This allows for dynamic menu generation based on specific parameters.

```twig
{% set menuItem = knp_menu_get('my_main_menu', [], {'some_option': 'my_value'}) %}
{{ knp_menu_render(menuItem) }}
```

--------------------------------

### Get Specific Menu Branch - Twig

Source: https://symfony.com/bundles/KnpMenuBundle/current/index.html

Retrieve and render a specific branch of a menu by providing the menu name and the desired branch identifier.

```twig
{% set menuItem = knp_menu_get('my_main_menu', ['Contact']) %}
{{ knp_menu_render(['my_main_menu', 'Contact']) }}
```

--------------------------------

### Get Menu Item for Later Rendering - Twig

Source: https://symfony.com/bundles/KnpMenuBundle/current/index.html

Retrieve a menu item by its name in Twig, allowing you to render it later. This is useful for complex template logic.

```twig
{% set menuItem = knp_menu_get('my_main_menu') %}
{{ knp_menu_render(menuItem) }}
```

--------------------------------

### Create Menu Items

Source: https://symfony.com/bundles/KnpMenuBundle/current/i18n.html

This snippet shows how to create a menu and add children with specified routes.

```php
$menu = $factory->createItem('root');

$menu->addChild('Home', ['route' => 'homepage']);
$menu->addChild('Login', ['route' => 'login']);
```

--------------------------------

### Register Menu Builder Service (Manual)

Source: https://symfony.com/bundles/KnpMenuBundle/current/menu_builder_service.html

If autoconfiguration is disabled, manually register your menu builder service in `config/services.yaml`. Tag it with `knp_menu.menu_builder` and specify the method to use and an alias for the menu.

```yaml
# config/services.yaml
services:
    app.menu_builder:
        class: App\Menu\MenuBuilder
        arguments: ["@knp_menu.factory"]
        tags:
            - { name: knp_menu.menu_builder, method: createMainMenu, alias: main } # The alias is what is used to retrieve the menu

    # ...
```

--------------------------------

### Register Menu Builder and Main Menu Services

Source: https://symfony.com/bundles/KnpMenuBundle/current/menu_service.html

Configure services.yaml to register the menu builder and the main menu. The main menu service uses the menu builder's `createMainMenu` method as a factory.

```yaml
# config/services.yaml
services:
    app.menu_builder:
        class: App\Menu\MenuBuilder
        arguments: ["@knp_menu.factory"]

    app.main_menu:
        class: Knp\Menu\MenuItem # the service definition requires setting the class
        factory: ["@app.menu_builder", createMainMenu]
        arguments: ["@request_stack"]
        tags:
            - { name: knp_menu.menu, alias: main } # The alias is what is used to retrieve the menu

    # ...
```

--------------------------------

### Implement Custom Menu Provider Class

Source: https://symfony.com/bundles/KnpMenuBundle/current/custom_provider.html

Create a class that implements the MenuProviderInterface. This class will be responsible for fetching and constructing menu items.

```php
namespace App\Provider;

use Knp\Menu\FactoryInterface;
use Knp\Menu\Provider\MenuProviderInterface;

class CustomMenuProvider implements MenuProviderInterface
{
    /**
     * @var FactoryInterface
     */
    protected $factory = null;


    /**
     * @param FactoryInterface $factory the menu factory used to create the menu item
     */
    public function __construct(FactoryInterface $factory)
    {
        $this->factory = $factory;
    }

    /**
     * Retrieves a menu by its name
     *
     * @param string $name
     * @param array $options
     * @return \Knp\Menu\ItemInterface
     * @throws \InvalidArgumentException if the menu does not exists
     */
    public function get($name, array $options = [])
    {
        if ('demo' == $name) { //several menu could call this provider

            $menu = /* construct / get a \Knp\Menu\NodeInterface */;

            if ($menu === null) {
                throw new \InvalidArgumentException(sprintf('The menu "%s" is not defined.', $name));
            }

            /*
             * Populate your menu here
             */

            $menuItem = $this->factory->createFromNode($menu);

            return $menuItem;
        }
    }

    /**
     * Checks whether a menu exists in this provider
     *
     * @param string $name
     * @param array $options
     * @return bool
     */
    public function has($name, array $options = [])
    {
        $menu = /* find the menu called $name */;

        return $menu !== null;
    }
}
```

--------------------------------

### Render Menu with Options - PHP

Source: https://symfony.com/bundles/KnpMenuBundle/current/index.html

Render a menu using PHP, passing an array of options to customize its appearance and behavior.

```php
<?php echo $view['knp_menu']->render('my_main_menu', [
    'depth'         => 2,
    'currentAsLink' => false,
]) ?>
```

--------------------------------

### Define a Menu Builder Service

Source: https://symfony.com/bundles/KnpMenuBundle/current/menu_builder_service.html

Create a PHP class to build your menus. Use the `#[AsMenuBuilder]` attribute to automatically register it as a menu builder service. The `name` option in the attribute is used to retrieve the menu.

```php
namespace App\Menu;

use Knp\Menu\Attribute\AsMenuBuilder;
use Knp\Menu\FactoryInterface;
use Knp\Menu\ItemInterface;

class MenuBuilder
{
    private $factory;

    /**
     * Add any other dependency you need...
     */
    public function __construct(FactoryInterface $factory)
    {
        $this->factory = $factory;
    }

    #[AsMenuBuilder(name: 'main')] // The name is what is used to retrieve the menu
    public function createMainMenu(array $options): ItemInterface
    {
        $menu = $this->factory->createItem('root');

        $menu->addChild('Home', ['route' => 'homepage']);
        // ... add more children

        return $menu;
    }
}
```

--------------------------------

### Register a custom renderer service

Source: https://symfony.com/bundles/KnpMenuBundle/current/custom_renderer.html

Register your custom renderer as a service in `services.yaml`. Ensure the class implements `Knp\Menu\Renderer\RendererInterface` and is tagged with `knp_menu.renderer` using your desired alias.

```yaml
services:
    app.menu_renderer:
        # The class implements Knp\Menu\Renderer\RendererInterface
        class: App\Menu\CustomRenderer
        arguments: ["%kernel.charset%"] # set your own dependencies here
        tags:
            # The alias is what is used to retrieve the menu
            - { name: knp_menu.renderer, alias: custom }

    # ...
```

--------------------------------

### Create Menu Builder with Event Dispatch

Source: https://symfony.com/bundles/KnpMenuBundle/current/events.html

This builder creates a base menu and dispatches a 'ConfigureMenuEvent' to allow extensions. It requires the Knp menu factory and Symfony's event dispatcher.

```php
namespace App\Menu;

use App\Event\ConfigureMenuEvent;
use Knp\Menu\FactoryInterface;
use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;

class MainBuilder
{
    private $factory;
    private $eventDispatcher;

    public function __construct(FactoryInterface $factory, EventDispatcherInterface $eventDispatcher)
    {
        $this->factory = $factory;
        $this->eventDispatcher = $eventDispatcher;
    }

    public function build(array $options)
    {
        $menu = $this->factory->createItem('root');

        $menu->addChild('Dashboard', ['route' => '_acp_dashboard']);

        $this->eventDispatcher->dispatch(
            new ConfigureMenuEvent($this->factory, $menu),
            ConfigureMenuEvent::CONFIGURE
        );

        return $menu;
    }
}
```

--------------------------------

### Create Menu Builder Class

Source: https://symfony.com/bundles/KnpMenuBundle/current/menu_service.html

Define a menu builder class that utilizes the KnpMenu factory to create menu items. This class will be registered as a service.

```php
namespace App\Menu;

use Knp\Menu\FactoryInterface;
use Symfony\Component\HttpFoundation\RequestStack;

class MenuBuilder
{
    private $factory;

    public function __construct(FactoryInterface $factory)
    {
        $this->factory = $factory;
    }

    public function createMainMenu(RequestStack $requestStack)
    {
        $menu = $this->factory->createItem('root');

        $menu->addChild('Home', ['route' => 'homepage']);
        // ... add more children

        return $menu;
    }
}
```

--------------------------------

### Create Event Object for Menu Configuration

Source: https://symfony.com/bundles/KnpMenuBundle/current/events.html

This event object carries the menu and factory to listeners. It defines a 'CONFIGURE' constant for the event name.

```php
namespace App\Event;

use Knp\Menu\FactoryInterface;
use Knp\Menu\ItemInterface;
use Symfony\Component\EventDispatcher\Event;

class ConfigureMenuEvent extends Event
{
    const CONFIGURE = 'app.menu_configure';

    private $factory;
    private $menu;

    public function __construct(FactoryInterface $factory, ItemInterface $menu)
    {
        $this->factory = $factory;
        $this->menu = $menu;
    }

    /**
     * @return \Knp\Menu\FactoryInterface
     */
    public function getFactory()
    {
        return $this->factory;
    }

    /**
     * @return \Knp\Menu\ItemInterface
     */
    public function getMenu()
    {
        return $this->menu;
    }
}
```

--------------------------------

### Create Listener to Add Menu Items

Source: https://symfony.com/bundles/KnpMenuBundle/current/events.html

This listener adds 'Matches' and 'Participants' menu items when the 'app.menu_configure' event is dispatched. It uses the event's getMenu() method to access the menu object.

```php
namespace Acme\AdminBundle\EventListener;

use App\Event\ConfigureMenuEvent;

class ConfigureMenuListener
{
    public function __invoke(ConfigureMenuEvent $event)
    {
        $menu = $event->getMenu();

        $menu->addChild('Matches', ['route' => 'versus_rankedmatch_acp_matches_index']);
        $menu->addChild('Participants', ['route' => 'versus_rankedmatch_acp_participants_index']);
    }
}
```

--------------------------------

### Translate Menu Items with YAML

Source: https://symfony.com/bundles/KnpMenuBundle/current/i18n.html

Translate menu items 'Home' and 'Login' to French using a YAML translation file.

```yaml
# translations/messages.fr.yaml
Home: Accueil
Login: Connexion
```

--------------------------------

### Define Menu Builder Class

Source: https://symfony.com/bundles/KnpMenuBundle/current/menu_convention.html

Create a `Builder` class within the `Menu` directory of your bundle. Each method in this class represents a menu and receives a `FactoryInterface` and options array. The class requires an `EntityManagerInterface` for data retrieval.

```php
namespace AppBundle\Menu;

use App\Entity\Blog;
use Knp\Menu\FactoryInterface;
use Knp\Menu\ItemInterface;
use Doctrine\ORM\EntityManagerInterface;

final class Builder
{
    public function __construct(
        private EntityManagerInterface $em,
    ) {
    }

    public function mainMenu(FactoryInterface $factory, array $options): ItemInterface
    {
        $menu = $factory->createItem('root');

        $menu->addChild('Home', ['route' => 'homepage']);

        // findMostRecent and Blog are just imaginary examples
        $blog = $this->em->getRepository(Blog::class)->findMostRecent();

        $menu->addChild('Latest Blog Post', [
            'route' => 'blog_show',
            'routeParameters' => ['id' => $blog->getId()]
        ]);

        // create another menu item
        $menu->addChild('About Me', ['route' => 'about']);
        // you can also add sub levels to your menus as follows
        $menu['About Me']->addChild('Edit profile', ['route' => 'edit_profile']);

        // ... add more children

        return $menu;
    }
}
```

--------------------------------

### Register a custom renderer extending ListRenderer

Source: https://symfony.com/bundles/KnpMenuBundle/current/custom_renderer.html

If your custom renderer extends `ListRenderer`, you must provide a `Matcher` instance and potentially other dependencies like renderer options. Configure these in the service arguments.

```yaml
services:
    app.menu_renderer:
        # The class implements Knp\Menu\Renderer\RendererInterface
        class: App\Menu\CustomRenderer
        arguments:
            - '@knp_menu.matcher'
            - '%knp_menu.renderer.list.options%'
            - '%kernel.charset%'
            # add your own dependencies here
        tags:
            # The alias is what is used to retrieve the menu
            - { name: knp_menu.renderer, alias: custom }

    # ...
```

--------------------------------

### Configure KnpMenuBundle with YAML

Source: https://symfony.com/bundles/KnpMenuBundle/current/index.html

Configure KnpMenuBundle settings such as the Twig template, templating support, and default renderer using a YAML configuration file.

```yaml
# config/packages/knp_menu.yaml
knp_menu:
    # use "twig: false" to disable the Twig extension and the TwigRenderer
    twig:
        template: KnpMenuBundle::menu.html.twig
    # if true, enables the helper for PHP templates
    # support for templating is deprecated, it will be removed in next major version
    templating: false
    # the renderer to use, list is also available by default
    default_renderer: twig
```

--------------------------------

### Configure KnpMenuBundle with PHP

Source: https://symfony.com/bundles/KnpMenuBundle/current/index.html

Configure KnpMenuBundle settings programmatically using a PHP configuration file. This allows setting the Twig template, templating support, and default renderer.

```php
// config/packages/knp_menu.php
$container->loadFromExtension('knp_menu', [
    // use 'twig' => false to disable the Twig extension and the TwigRenderer
    'twig' => [
        'template' => 'KnpMenuBundle::menu.html.twig'
    ],
    // if true, enable the helper for PHP templates (deprecated)
    'templating' => false,
    // the renderer to use, list is also available by default
    'default_renderer' => 'twig',
]);
```

--------------------------------

### Configure KnpMenuBundle with XML

Source: https://symfony.com/bundles/KnpMenuBundle/current/index.html

Configure KnpMenuBundle settings using an XML configuration file. This includes options for the Twig template, templating support, and the default renderer.

```xml
<!-- config/packages/knp_menu.xml -->
<?xml version="1.0" charset="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:knp-menu="http://knplabs.com/schema/dic/menu">

    <!--
        templating:       if true, enable the helper for PHP templates (deprecated)
        default-renderer: the renderer to use, list is also available by default
    -->
    <knp-menu:config
        templating="false"
        default-renderer="twig"
    >
        <!-- add enabled="false" to disable the Twig extension and the TwigRenderer -->
        <knp-menu:twig template="KnpMenuBundle::menu.html.twig"/>
    </knp-menu:config>
</container>
```

--------------------------------

### Register Sidebar Menu Service

Source: https://symfony.com/bundles/KnpMenuBundle/current/menu_service.html

Define a new service for the sidebar menu in `services.yaml`, using the `createSidebarMenu` method as its factory and assigning it a unique alias.

```yaml
services:
    app.sidebar_menu:
        class: Knp\Menu\MenuItem
        factory: ["@app.menu_builder", createSidebarMenu]
        arguments: ["@request_stack"]
        tags:
            - { name: knp_menu.menu, alias: sidebar } # Named "sidebar" this time

    # ...
```

--------------------------------

### Add Second Menu Method to Builder

Source: https://symfony.com/bundles/KnpMenuBundle/current/menu_service.html

Extend the `MenuBuilder` class by adding a new method to create a different menu, such as a sidebar menu.

```php
// ...

class MenuBuilder
{
    // ...

    public function createSidebarMenu(RequestStack $requestStack)
    {
        $menu = $this->factory->createItem('sidebar');

        $menu->addChild('Home', ['route' => 'homepage']);
        // ... add more children

        return $menu;
    }
}
```

--------------------------------

### Enable KnpMenuBundle in AppKernel

Source: https://symfony.com/bundles/KnpMenuBundle/current/index.html

Manually enable the KnpMenuBundle by adding it to the registerBundles method in your AppKernel. This is only necessary if you are not using Flex.

```php
// e.g. app/AppKernel.php

// ...
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = [
            // ...

            new Knp\Bundle\MenuBundle\KnpMenuBundle(),
        ];

        // ...
    }

    // ...
}
```

--------------------------------

### Translate Menu Items with PHP Array

Source: https://symfony.com/bundles/KnpMenuBundle/current/i18n.html

Translate menu items 'Home' and 'Login' to French using a PHP array.

```php
// translations/messages.fr.php
return [
    'Home' => 'Accueil',
    'Login' => 'Connexion',
];
```

--------------------------------

### Translate Menu Items with XLF

Source: https://symfony.com/bundles/KnpMenuBundle/current/i18n.html

Translate menu items 'Home' and 'Login' to French using an XLF translation file.

```xlf
<!-- translations/messages.fr.xliff -->
<?xml version="1.0"?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
    <file source-language="en" datatype="plaintext" original="file.ext">
        <body>
            <trans-unit id="menu.home">
                <source>Home</source>
                <target>Accueil</target>
            </trans-unit>

            <trans-unit id="menu.login">
                <source>Login</source>
                <target>Connexion</target>
            </trans-unit>
        </body>
    </file>
</xliff>
```

--------------------------------

### Register Listener Service

Source: https://symfony.com/bundles/KnpMenuBundle/current/events.html

This YAML configuration registers the 'ConfigureMenuListener' as a kernel event listener for the 'app.menu_configure' event.

```yaml
# config/services.yaml
services:
    app.admin_configure_menu_listener:
        class: Acme\AdminBundle\EventListener\ConfigureMenuListener
        tags: [kernel.event_listener]
```

--------------------------------

### Add a Second Menu Builder Method

Source: https://symfony.com/bundles/KnpMenuBundle/current/menu_builder_service.html

Add another method to your existing menu builder class to create a different menu. Use the `#[AsMenuBuilder]` attribute with a unique `name` for the new menu.

```php
// src/Menu/MenuBuilder.php

// ...

class MenuBuilder
{
    // ...

    #[AsMenuBuilder(name: 'sidebar')]
    public function createSidebarMenu(array $options): ItemInterface
    {
        $menu = $this->factory->createItem('sidebar');

        if (isset($options['include_homepage']) && $options['include_homepage']) {
            $menu->addChild('Home', ['route' => 'homepage']);
        }

        // ... add more children

        return $menu;
    }
}
```

--------------------------------

### Render a Menu - PHP

Source: https://symfony.com/bundles/KnpMenuBundle/current/index.html

Use this PHP helper to render a menu by its name. This is typically used within Twig templates or controllers.

```php
<?php echo $view['knp_menu']->render('my_main_menu') ?>
```

--------------------------------

### Render Main Menu in Template

Source: https://symfony.com/bundles/KnpMenuBundle/current/menu_service.html

Use the `knp_menu_render` Twig function to display the main menu in your templates, referencing it by its alias.

```twig
{{ knp_menu_render('main') }}
```

--------------------------------

### Configure Custom Menu Provider Service

Source: https://symfony.com/bundles/KnpMenuBundle/current/custom_provider.html

Register your custom menu provider as a service in Symfony's configuration and tag it appropriately.

```yaml
# config/services.yaml or app/config/services.yml
services:
    app.menu_provider:
        class: App\Provider\CustomMenuProvider
        arguments:
          - '@knp_menu.factory'
        tags:
          - { name: knp_menu.provider }

# ...

```

--------------------------------

### Render Menu in Template

Source: https://symfony.com/bundles/KnpMenuBundle/current/menu_convention.html

Use the `knp_menu_render` Twig function to display a menu defined by the naming convention. The menu is referenced using the 'bundle:class:method' format.

```twig
{{ knp_menu_render('App:Builder:mainMenu') }}
```

--------------------------------

### Render a menu with a custom renderer

Source: https://symfony.com/bundles/KnpMenuBundle/current/custom_renderer.html

Use the `knp_menu_render` Twig function to render a menu, specifying the menu name, options, and the alias of your custom renderer.

```twig
{{ knp_menu_render('main', {}, 'custom') }}
```

--------------------------------

### Render a Menu - Twig

Source: https://symfony.com/bundles/KnpMenuBundle/current/index.html

Use this Twig function to render a menu by its name. Ensure the menu is defined and available in your application.

```twig
{{ knp_menu_render('my_main_menu') }}
```

--------------------------------

### Configure Custom Translation Domain

Source: https://symfony.com/bundles/KnpMenuBundle/current/i18n.html

Set a custom translation domain for a menu item by specifying it in the item's extras.

```php
// ...
$menu->addChild('Home', ['route' => 'homepage'])
    ->setExtra('translation_domain', 'AcmeAdminBundle');
```

--------------------------------

### Render Sidebar Menu in Template

Source: https://symfony.com/bundles/KnpMenuBundle/current/menu_service.html

Render the sidebar menu in your templates using its assigned alias with the `knp_menu_render` function.

```twig
{{ knp_menu_render('sidebar') }}
```

--------------------------------

### Render Menu with Options - Twig

Source: https://symfony.com/bundles/KnpMenuBundle/current/index.html

Render a menu with specific options like 'depth' and 'currentAsLink'. Adjust these options to control menu display.

```twig
{{ knp_menu_render('my_main_menu', {'depth': 2, 'currentAsLink': false}) }}
```

--------------------------------

### Render Menu in Twig Template

Source: https://symfony.com/bundles/KnpMenuBundle/current/custom_provider.html

Use the knp_menu_render Twig function to display the menu generated by your custom provider.

```twig
{{ knp_menu_render('demo') }}
```

--------------------------------

### Disable Builder Alias Provider

Source: https://symfony.com/bundles/KnpMenuBundle/current/disabling_providers.html

Disable the builder-alias-based provider by setting 'builder_alias' to false in the knp_menu configuration. All providers are enabled by default.

```yaml
# config/packages/knp_menu.yaml
knp_menu:
    providers:
        builder_alias: false    # disable the builder-alias-based provider
```

--------------------------------

### Disable Menu Item Translation

Source: https://symfony.com/bundles/KnpMenuBundle/current/i18n.html

Disable translation for a menu item by setting its 'translation_domain' extra to false.

```php
// ...
$menu->addChild('About', ['route' => 'about'])
    ->setExtra('translation_domain', false);
```
Tokens:
Raw