API Cheat Sheet

The public methods of the core classes. See Helper & Render Options for the Menu helper.

Menu

Factories, building, querying, and lifecycle. (MenuInterface)

Menu::create(array $attributes = []): static
Menu::fromArray(array $config): static          // build from a nested config array
Menu::fromFlat(iterable $rows, Closure $mapper): static  // build a tree from flat rows

Method	Purpose
add(ItemInterface $item)	Add an existing item.
addItems(array $items)	Add multiple existing items in order.
addItem(string $label, $link = null, array $options = [])	Create and add an item.
addRaw(string $html, array $options = [])	Add a raw-HTML item.
addDivider(array $options = [])	Add a divider.
addHeader(string $label, array $options = [])	Add a non-link section header.
newItem(?string $label = null, $link = null, array $options = [])	Build an item without adding it.
getItems() / setItems(array)	Root items as an array.
collect()	All items (root + descendants) as an ItemCollection.
get(string $id) / has(string $id) / remove(string $id)	Find/check/remove by id (recursive); remove() throws if missing.
getByKey(string $key) / hasKey(string $key) / removeByKey(string $key)	Find/check/remove by explicit key only; removal targets the first match and throws if none exists.
insertBefore(ItemInterface $item, string $idOrKey) / insertAfter(...)	Insert relative to a sibling (by id/key).
moveToPosition(string $idOrKey, int $pos) / moveToFirstPosition(...) / moveToLastPosition(...)	Reposition a child.
reorder(list<string> $order)	Reorder children by id/key; unlisted keep order, appended.
merge(MenuInterface $menu, bool $mergeAttributes = false)	Append a deep copy of another menu's items (source untouched).
slice(int|string $offset, int|string|null $length = null)	New menu with a copy of a range of items.
split(int|string $length)	['primary' => ..., 'secondary' => ...] menus split at a boundary.
getActiveItem()	Deepest active item.
clearActive()	Deactivate all items.
getAttributes() / setAttribute() / setAttributes()	Root HTML attributes.
getData() / setData()	Menu-level metadata.
setItemClass(string $class) / getItemClass()	Set or read the class used for new items and their submenus.
collect()	Return all items as an ItemCollection.
filter(Closure)	Keep only matching items.
find(Closure)	Return matching items as an ItemCollection without mutating the tree.
sortBy(Closure|string $by, SortDirection $direction = SortDirection::Asc)	Sort items.
resolve(ResolverInterface)	Apply a resolver.
resetState()	Reset active/visible/expanded to defaults.
freeze() / isFrozen()	Make immutable / check.
toArray()	Serialize (round-trips with fromArray()).

Item

A single entry. (ItemInterface)

Group	Methods
Identity	setId() / getId(), setKey() / getKey(), hasExplicitKey()
Label	setLabel(string, bool $escape = true) / getLabel(), shouldEscapeLabel()
Link	setLink() / getLink()
Content	setRaw() / getRaw() / isRaw(), setBefore() / getBefore(), setAfter() / getAfter()
Type	setDivider() / isDivider(), setHeader() / isHeader()
Icon/badge	setIcon() / getIcon(), setBadge($badge, $type) / getBadge() / getBadgeType()
Defaults	setActive() / isActive(), setVisible() / isVisible(), setExpanded() / isExpanded()
Submenu	add(), setSubMenu() / getSubMenu() / hasSubMenu(), setDisplayChildren(bool) / displaysChildren()
Label attrs	setLabelAttributes(array, bool $merge = false) / getLabelAttributes()
Tree	setParent() / getParent() / hasParent() / getParentId()
Matching	setMatchRoutes() / addMatchRoute() / getMatchRoutes(), setIgnoreQueryString() / getIgnoreQueryString(), setFuzzy(true) / getFuzzy()
Attributes/data	setAttribute() / setAttributes() / getAttributes(), setData() / getData()
Lifecycle	freeze() / isFrozen(), resetState(), toArray()
Runtime (resolver-safe)	setRuntimeActive(), setRuntimeVisible(), setRuntimeExpanded()

Link

The URL of an item. (LinkInterface)

Link::create(string|array|null $url = null, array $attributes = [], bool $external = false): static

Method	Purpose
setUrl($url, bool $external = false)	Set the URL (string/array) and external flag.
getRawUrl()	The raw URL (string, array, or null).
getUrl()	The resolved URL string (via the Router).
isExternal()	Whether the link is external.
setAttribute() / setAttributes() / getAttributes()	Link HTML attributes.

ItemCollection

A flat collection returned by Menu::collect(). Iterable and countable.

Method	Purpose
add() / addMany()	Add item(s).
all()	Items as an array.
findById(string $id)	Find by id.
findByKey(string $key)	Find by explicit key only.
findByParent(string|ItemInterface $parent)	Direct children of a parent.
count()	Number of items.

Runtime state uses setRuntimeVisible(), setRuntimeActive(), and setRuntimeExpanded(). resetState() restores the authoring defaults. getPath() returns root-to-self items, getLevel() is zero for a top-level item, and getRoot() returns the top-level ancestor.

ResolverCollectionInterface extends ResolverInterface and adds add(), addMany(), and all(). Resolvers require resolve(ItemInterface $item, ResolverContext $context): void.