Download the PHP package chamber-orchestra/menu-bundle without Composer

ChamberOrchestra MenuBundle

A Symfony 8 bundle for building navigation menus, sidebars, and breadcrumbs — fluent tree builder, route-based active-item matching, role-based access control, runtime extensions for dynamic badges, PSR-6 tag-aware caching, and Twig rendering.

Features

• Fluent builder API — add(), children(), end() for deeply-nested trees
• Route-based matching — RouteVoter marks the current item and its ancestors active; route values are treated as regex patterns
• Custom voters — implement VoterInterface to add custom matching logic alongside the built-in RouteVoter
• Role-based access — Accessor gates items by Symfony security roles; results are memoized per request
• PSR-6 caching — AbstractCachedNavigation caches the item tree for 24 h with tag-based invalidation
• Runtime extensions — RuntimeExtensionInterface runs post-cache on every request for fresh dynamic data without rebuilding the tree
• Badge support — BadgeExtension resolves int and \Closure badges at runtime; implement RuntimeExtensionInterface for service-injected dynamic badges
• Counters — CounterExtension resolves multiple named counters (int or \Closure) at runtime
• Icons — IconExtension moves the icon option into extras['icon'] at build time
• Dividers — DividerExtension marks items as dividers via extras['divider'] at build time
• Visibility — VisibilityExtension resolves visible (bool or \Closure) at runtime into extras['visible']
• Label translation — TranslationExtension translates item labels via Symfony's TranslatorInterface (auto-disabled when no translator is available)
• Breadcrumbs — menu_breadcrumbs() Twig function returns the path from root to the current item
• Raw tree access — menu_get() Twig function returns the root Item without rendering
• Twig integration — render_menu() function with fully customisable templates and optional default template
• Bundle configuration — centralised config for default template, translation domain, and cache namespace
• Extension system — build-time ExtensionInterface for cached option enrichment, runtime RuntimeExtensionInterface for post-cache processing
• DI autoconfiguration — implement an interface, done; no manual service tags required

Requirements

Installation

Register the bundle

Configuration

All values are optional with sensible defaults.

Quick Start

1. Create a navigation class

The class is auto-tagged as a navigation service — no YAML/XML service definition needed.

2. Create a Twig template

3. Render in Twig

Item Options

Options are passed as the second argument to MenuBuilder::add():

Section items

Pass section: true to mark an item as a non-linkable section heading:

Caching

Navigation classes form a hierarchy — extend the one that fits your use case:

All navigations are deduped within the same request via NavigationFactory. When a PSR-6 CacheInterface (tag-aware) is wired in, AbstractCachedNavigation stores the tree across requests. Without one, an in-memory ArrayAdapter is used automatically.

Dynamic data (badges, counters) does not require sacrificing the cache — use runtime extensions instead.

The default cache key is the fully-qualified class name; default TTL is 24 hours; default tag is chamber_orchestra_menu.

ClosureNavigation caching

ClosureNavigation is uncached by default (TTL 0), but you can opt in to caching by providing a unique cacheKey and a ttl:

Each cached ClosureNavigation must have a unique cacheKey — without one, all instances share the same key and overwrite each other.

The cache namespace prefix defaults to $NAVIGATION$ and can be changed via bundle configuration.

Route Matching

RouteVoter reads _route from the current request and compares it against each item's routes array. Route values are treated as regex patterns, so you can highlight an entire section:

Custom Voters

Implement VoterInterface to add custom matching logic. Custom voters are auto-tagged and used alongside RouteVoter:

Role-Based Access

The accessor variable is injected into every rendered template. Call hasAccess(item) to gate visibility:

hasAccess() returns true when:

• the item has no roles restriction, or
• the current user has all of the required roles (AND logic).

hasAccessToChildren(collection) returns true when any child in the collection is accessible.

Icons

The built-in IconExtension moves the icon option into extras['icon'] at build time, so the value is cached with the tree:

In Twig:

Dividers

The DividerExtension marks items as visual dividers at build time:

In Twig:

Visibility

The VisibilityExtension resolves the visible option at runtime. Pass a bool or a \Closure:

In Twig:

Badges

Via the badge option

The built-in BadgeExtension is a runtime extension that resolves the badge item option on every request. Pass an int or a \Closure:

Via a custom runtime extension

For service-injected dynamic data, implement RuntimeExtensionInterface. The tree stays cached; the extension runs post-cache on every request:

In Twig, read the badge via item.badge:

Counters

The CounterExtension resolves multiple named counters at runtime. Pass a array<string, int|\Closure>:

In Twig:

Label Translation

The TranslationExtension translates item labels using Symfony's TranslatorInterface. It runs at runtime (post-cache) so translated labels are always fresh.

• Default domain: configured via chamber_orchestra_menu.translation.domain (defaults to messages)
• Per-item override: set the translation_domain option on an item
• Empty labels are skipped
• Auto-disabled when no TranslatorInterface service is available in the container

Factory Extensions

Build-time extensions (cached)

Implement ExtensionInterface to enrich item options before the Item is created. Results are cached with the tree. Extensions are auto-tagged and sorted by priority (higher runs first; CoreExtension runs last at -10):

Built-in build-time extensions

Runtime extensions (post-cache)

Implement RuntimeExtensionInterface to apply fresh data after every cache fetch. processItem() is called on every Item in the tree:

Built-in runtime extensions

DI Autoconfiguration

Implement an interface and you're done — no manual service tags required:

Breadcrumbs

The menu_breadcrumbs() Twig function returns the path from root to the current item (root excluded):

Returns an empty array when no item is currently active.

Twig Reference

Template variables (available inside render_menu templates):

Testing

License

MIT. See LICENSE.