From be79aa6d601dfadc6c6fe7fe1faadf0f13193165 Mon Sep 17 00:00:00 2001 From: "promptless[bot]" Date: Fri, 21 Aug 2026 07:58:43 +0000 Subject: [PATCH 1/2] Document registering a custom Menu in Config/services.php for Mautic 8 Mautic 8 (mautic/mautic PR #17116) removed the ServicePass compiler pass and the 'services > menus' array in bundle Config/config.php. Add a 'Registering a custom Menu' section to plugins/config.rst documenting the knp_menu.menu MenuItem and knp_menu.renderer MenuRenderer services a Plugin now declares in Config/services.php, with a before/after migration example and a forward cross-reference from 'Available menus'. --- docs/plugins/config.rst | 79 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) diff --git a/docs/plugins/config.rst b/docs/plugins/config.rst index eedb58e2d..6aaaa4cd0 100644 --- a/docs/plugins/config.rst +++ b/docs/plugins/config.rst @@ -320,6 +320,8 @@ There are currently four menus built into Mautic. * - ``extra`` - Menu not used by Core but available to Plugins. +A Plugin can also register its own top-level Menu instead of adding items to these. See :ref:`plugins/config:Registering a custom Menu`. + Menu definitions ================ @@ -459,6 +461,83 @@ Of course, you can also combine multiple checks. All must evaluate to TRUE to di // ... +.. vale off + +Registering a custom Menu +************************* + +.. vale on + +The :ref:`plugins/config:Menu config items` section adds items to Mautic's four built-in menus through the ``menu`` config array. This section covers the opposite direction: registering a Plugin's own top-level Menu, with its own template and renderer. + +.. note:: + + Mautic 8 removed the ``ServicePass`` compiler pass and the ``services > menus`` array in ``Config/config.php``. A Plugin now declares its Menu item and renderer explicitly in ``Config/services.php``. + +Registering a custom Menu takes two services in your Plugin's ``Config/services.php``: + +- A ``Knp\Menu\MenuItem`` tagged ``knp_menu.menu``. +- A ``Mautic\CoreBundle\Menu\MenuRenderer`` tagged ``knp_menu.renderer``. + +Give each tag an ``['alias' => '']`` argument so Mautic pairs the item with its renderer. + +Earlier versions registered the Menu through the ``services > menus`` array in ``Config/config.php``: + +.. code-block:: php + + [ + 'menus' => [ + 'mautic.menu.mybundle' => [ + 'alias' => 'mybundle', + 'options' => ['template' => '@MyBundle/Menu/mybundle.html.twig'], + ], + ], + ], + +The following snippet is the Mautic 8 equivalent. This is a partial example. The ``use`` statements go at the top of ``Config/services.php``, and the ``$services->set(...)`` definitions go inside its configurator closure. The bundle Extension and this ``$services`` configurator setup are described in :ref:`plugins/autowiring:Autowiring`: + +.. code-block:: php + + set('mautic.menu.mybundle', MenuItem::class) + ->factory([service(MenuBuilder::class), 'mybundleMenu']) + ->tag('knp_menu.menu', ['alias' => 'mybundle']); + + $services->set('mautic.menu_renderer.mybundle', MenuRenderer::class) + ->args([service('knp_menu.matcher'), service('twig'), ['template' => '@MyBundle/Menu/mybundle.html.twig']]) + ->tag('knp_menu.renderer', ['alias' => 'mybundle']); + +Reference the Menu builder by class through ``service(Mautic\CoreBundle\Menu\MenuBuilder::class)``. Mautic 8 removed the ``mautic.menu.builder`` string alias, so it no longer resolves. + +These two services register and render the Menu, while the ``Menu`` method the factory calls on the Menu builder, here ``mybundleMenu``, supplies the Menu's contents. + +If your bundle has several menus, register them in a loop. ``$menuTemplates`` is the alias-to-options array you supply: + +.. code-block:: php + + foreach ($menuTemplates as $alias => $options) { + $services->set('mautic.menu.'.$alias, MenuItem::class) + ->factory([service(MenuBuilder::class), $alias.'Menu']) + ->tag('knp_menu.menu', ['alias' => $alias]); + + $services->set('mautic.menu_renderer.'.$alias, MenuRenderer::class) + ->args([service('knp_menu.matcher'), service('twig'), $options]) + ->tag('knp_menu.renderer', ['alias' => $alias]); + } + Service config items ******************** From d005649dab269bd28a15e9990f6e14d5f03ffc16 Mon Sep 17 00:00:00 2001 From: "promptless[bot]" Date: Mon, 7 Sep 2026 12:20:10 +0000 Subject: [PATCH 2/2] Address Vale findings on custom Menu section Wrap intentionally-correct code/doc identifiers (reference-path segments and the lowercase plugins/ filesystem path) in vale off/on comments per maintainer review, and rephrase one passive sentence to active voice. No capitalization changed. --- docs/plugins/config.rst | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/plugins/config.rst b/docs/plugins/config.rst index 8c272c99c..77c20767d 100644 --- a/docs/plugins/config.rst +++ b/docs/plugins/config.rst @@ -320,8 +320,12 @@ There are currently four menus built into Mautic. * - ``extra`` - Menu not used by Core but available to Plugins. +.. vale off + A Plugin can also register its own top-level Menu instead of adding items to these. See :ref:`plugins/config:Registering a custom Menu`. +.. vale on + Menu definitions ================ @@ -476,8 +480,12 @@ Registering a custom Menu .. vale on +.. vale off + The :ref:`plugins/config:Menu config items` section adds items to Mautic's four built-in menus through the ``menu`` config array. This section covers the opposite direction: registering a Plugin's own top-level Menu, with its own template and renderer. +.. vale on + .. note:: Mautic 8 removed the ``ServicePass`` compiler pass and the ``services > menus`` array in ``Config/config.php``. A Plugin now declares its Menu item and renderer explicitly in ``Config/services.php``. @@ -491,6 +499,8 @@ Give each tag an ``['alias' => '']`` argument so Mautic pairs the item wi Earlier versions registered the Menu through the ``services > menus`` array in ``Config/config.php``: +.. vale off + .. code-block:: php menus`` array in ` ], ], -The following snippet is the Mautic 8 equivalent. This is a partial example. The ``use`` statements go at the top of ``Config/services.php``, and the ``$services->set(...)`` definitions go inside its configurator closure. The bundle Extension and this ``$services`` configurator setup are described in :ref:`plugins/autowiring:Autowiring`: +.. vale on + +.. vale off + +The following snippet is the Mautic 8 equivalent. This is a partial example. The ``use`` statements go at the top of ``Config/services.php``, and the ``$services->set(...)`` definitions go inside its configurator closure. :ref:`plugins/autowiring:Autowiring` describes the bundle Extension and this ``$services`` configurator setup: + +.. vale on .. code-block:: php