Helper & Render Options

The Menu helper builds, resolves, and renders named menus. Load it in AppView:

$this->loadHelper('CakeMenu.Menu');

Methods

Method	Purpose
create(string $name, array $options = [])	Create a new named menu.
register(string $name, Closure $cb, array $options = [])	Idempotently build a named menu via a callback.
getOrCreate(string $name, array $options = [])	Return an existing menu or create it.
has(string $name)	Whether a named menu exists.
get(string $name)	Return a named menu (throws if missing).
remove(string $name) / reset()	Drop one / all named menus.
render($menu = null, array $options = [])	Resolve and render a menu (by name, instance, or the last-created).
getCurrentItem($menu = null, array $options = [])	The deepest active item after resolution.
extractPath(ItemInterface $item)	Root-to-item path (for breadcrumbs).
getBreadcrumbs($menu = null, array $options = [])	Active path as an array of crumbs.
populateBreadcrumbs($menu = null, array $options = [])	Push crumbs into Cake's Breadcrumbs helper.
renderBreadcrumbs($menu = null, array $options = [])	Render through BreadcrumbRenderer or a subclass.

render() options

These come from the helper's defaults and may be overridden per call. Unrecognized keys are passed straight through to the renderer as renderer options.

Option	Default	Description
renderer	StringTemplateRenderer::class	Renderer class name or instance.
resolve	true	Set false to render without resolving active state.
resolver	(built-in URL resolvers)	A ResolverInterface that replaces the defaults.
additionalResolvers	[]	Extra ResolverInterfaces appended after the defaults (keeps active-state matching).
singleActive	false	Keep only the deepest active item active (best-match arbitration).
fuzzy	true	Fuzzy (prefix) matching for the default UrlArrayResolver.
ignoreQueryString	true	Ignore the query string in the default Psr7UrlResolver.
resolveDepth	null	Max depth the default URL resolvers scan (null = unlimited).
currentAsLink	true	Passed through: render the active item as a link.

Option precedence

Options merge in this order (later wins): helper config → per-menu render defaults → this call's $options. So defaults set at create() time apply to every later render() unless overridden in the call.

resolver vs additionalResolvers

resolver replaces the built-in URL resolvers (you lose automatic active-state matching). To keep them and add your own, use additionalResolvers. See Resolvers.

create() / register() options

Option	Description
attributes	HTML attributes for the root <ul>.
overwrite	Allow create() to replace an existing menu of the same name.
rebuild	Make register() rebuild even if the menu already exists.
cache	Cache the built structure (see below). true, a string key, or ['key' => ..., 'config' => ...].

attributes, overwrite, cache, and rebuild are consumed during building. They are not stored as render defaults or forwarded to renderers.

Any other keys (e.g. renderer, singleActive) set here become defaults for later render() calls on that menu.

The registration closure always receives ($menu, $helper). It may omit unused parameters.

renderBreadcrumbs() always uses BreadcrumbRenderer; its renderer option accepts a subclass name or instance. To use Cake's markup, call populateBreadcrumbs() and then $this->Breadcrumbs->render($attributes, $separator) yourself.

Caching a built menu

register() with a cache option builds the menu through the callback once and caches its structure (not its active state); later requests skip the build and load the tree from cache, while active state is always resolved fresh per request. Pass rebuild => true to refresh.

$this->Menu->register('main', function ($menu): void {
    // ...expensive build, e.g. a DB/ACL query...
}, ['cache' => 'menu_main']); // or ['cache' => true] (keyed by menu name), or ['key' => ..., 'config' => ...]

WARNING

The cached form is the serialized array, so custom item classes are restored as the base item class. Cache data-driven menus, not menus that rely on custom ItemInterface implementations.

Config-defined menus

The helper auto-registers menus declared in Configure::read('CakeMenu.menus') (each value a Menu::fromArray() spec keyed by name), so they render without any wiring:

// config/app.php (or a dedicated config/menu.php loaded via Configure::load)
'CakeMenu' => [
    'menus' => [
        'main' => [
            'attributes' => ['class' => 'nav'],
            'items' => [
                ['label' => 'Home', 'link' => '/'],
                ['label' => 'Articles', 'link' => ['controller' => 'Articles', 'action' => 'index']],
            ],
        ],
    ],
],

echo $this->Menu->render('main'); // no create()/register() needed

An explicit create()/register() of the same name overrides the configured menu entirely.

Breadcrumb options

Option	Default	Description
linkCurrent	false	Link the current (last) crumb too.
resetBreadcrumbs	true	Reset Cake's Breadcrumbs helper before populating.
renderer	BreadcrumbRenderer::class	Renderer used by renderBreadcrumbs(). Pass a BreadcrumbRenderer subclass or instance to customize the output.

Per-item breadcrumb attributes can be set via the item's data['breadcrumbOptions'].