krystal-sf/ux-menus

Tagged menus for Krystal Symfony UX Projects

1.0.x-dev 2026-08-05 23:04 UTC

Requires

• php: ^8.1
• knplabs/knp-menu-bundle: ^3.0
• krystal-sf/ux-common: ^1.0

Requires (Dev)

• badpixxel/php-sdk: ^3.0
• krystal-sf/ux-bootbox: ^1.0
• phpunit/phpunit: ^10.0|^11.0
• symfony/debug-bundle: ^6.4|^7.4|^8.0
• symfony/monolog-bundle: ^3.0|^4.0
• symfony/stopwatch: ^6.4|^7.4|^8.0
• symfony/web-profiler-bundle: ^6.4|^7.4|^8.0

Suggests

• krystal-sf/ux-bootbox: Confirmation dialogs for menu actions (BootBox)

MIT

• BadPixxel

• symfony
• twig
• components
• menus
• knp-menu
• symfony-ux
• krystal-sf

Published on Packagist.org on 2026-08-05 23:05 UTC

README

Tagged Knp Menus for Krystal Symfony UX Projects: menus providers collected by tags, fluent menu factory, presets processors and live menu items.

Installation

composer require krystal-sf/ux-menus

Enable the bundle in config/bundles.php:

return [
    // ...
    Ksf\Core\Menus\KsfMenusBundle::class => ['all' => true],
];

Tagged Menus Providers

Menus are built by providers, plain services registered on a tag with the #[AsMenu] attribute. All providers sharing a tag are collected and merged (by priority) when the menu is rendered:

use Knp\Menu\ItemInterface;
use Ksf\Core\Menus\Attribute\AsMenu;
use Ksf\Core\Menus\Model\AbstractUxMenuProvider;

#[AsMenu(MyMenusTags::SIDEBAR, priority: 100)]
class UserMenu extends AbstractUxMenuProvider
{
    public function get(string $name, array $options = array()): ItemInterface
    {
        return $this->factory
            ->autoload("menus.user", "MyDomain")
            ->createItem("user", array('route' => MyRoutes::USER))
        ;
    }
}

Providers may target a parent item via getParent(), or declare themselves as root with const IS_ROOT = true.

Render the menu anywhere with the Ksf:Menu Twig component:

<twig:Ksf:Menu :subject="ux.menus.app.SIDEBAR" :options="{...}"/>

Menu tags are declared in dictionaries exposed to Twig via #[AsMenusDictionary("name")] → ux.menus.name.*.

Menu Factory

MenuFactory wraps the Knp factory with a fluent options basket, consumed and purged by createItem():

$item = $this->factory
    ->setIcon("fas fa-user")
    ->setBadge("12")
    ->addPreset(BtnStylesPresets::PRIMARY)
    ->liveAction("doAction", array("id" => 27))
    ->autoload("menus.user.details", "MyDomain")
    ->createItem("details")
;

Fluent helpers: setOption, mergeOptions, setIcon, setImage, setBadge, setTooltip, setTranslationDomain, addPreset, addPresets, setPresets, liveEvent, liveAction, liveController, autoload.

Warning: the factory is a shared service — options accumulated without a final createItem() would leak into the next menu construction. Call reset() at the beginning of a build when in doubt.

BootBox confirmations helpers (bootboxConfirm...) are available when krystal-sf/ux-bootbox is installed (suggested dependency).

Presets & Processors

Menu items may carry presets (CSV or array), expanded by tagged providers and applied by processors:

• #[AsMenuPresetProvider] services expose preset values
• #[AsMenuProcessor] services post-process built items (see CompactModeProcessor, JumboModeProcessor)

Live Menu Items

Rendered items are Live Components (Ksf:MenuItem) supporting:

• data-event → dispatch a Live Event (LiveEventArgs)
• data-action → trigger a Live Action (LiveActionArgs)
• action / actionArgs → forward to a Symfony controller
• Badges with live counters (Ksf:MenuItemWithBadge)

Testing

make up          # boot the docker stack
make phpunit     # run the test suite
make quality     # lint + style + phpstan

License

MIT — see LICENSE.