3 namespace Drupal\Core\Menu;
6 * Defines an interface for storing a menu tree containing menu link IDs.
8 * The tree contains a hierarchy of menu links which have an ID as well as a
9 * route name or external URL.
11 interface MenuTreeStorageInterface {
14 * The maximum depth of tree the storage implementation supports.
19 public function maxDepth();
22 * Clears all definitions cached in memory.
24 public function resetDefinitions();
27 * Rebuilds the stored menu link definitions.
29 * Links that saved by passing definitions into this method must be included
30 * on all future calls, or they will be purged. This allows for automatic
31 * cleanup e.g. when modules are uninstalled.
33 * @param array $definitions
34 * The new menu link definitions.
36 public function rebuild(array $definitions);
39 * Loads a menu link plugin definition from the storage.
42 * The menu link plugin ID.
45 * The plugin definition, or FALSE if no definition was found for the ID.
47 public function load($id);
50 * Loads multiple plugin definitions from the storage.
53 * An array of plugin IDs.
56 * An array of plugin definition arrays keyed by plugin ID, which are the
57 * actual definitions after the loadMultiple() including all those plugins
60 public function loadMultiple(array $ids);
63 * Loads multiple plugin definitions from the storage based on properties.
65 * @param array $properties
66 * The properties to filter by.
69 * An array of menu link definition arrays.
71 * @throws \InvalidArgumentException
72 * Thrown if an invalid property name is specified in $properties.
74 public function loadByProperties(array $properties);
77 * Loads multiple plugin definitions from the storage based on route.
79 * @param string $route_name
81 * @param array $route_parameters
82 * (optional) The route parameters. Defaults to an empty array.
83 * @param string $menu_name
84 * (optional) Restricts the found links to just those in the named menu.
87 * An array of menu link definitions keyed by ID and ordered by depth.
89 public function loadByRoute($route_name, array $route_parameters = [], $menu_name = NULL);
92 * Saves a plugin definition to the storage.
94 * @param array $definition
95 * A definition for a \Drupal\Core\Menu\MenuLinkInterface plugin.
98 * The menu names affected by the save operation. This will be one menu
99 * name if the link is saved to the sane menu, or two if it is saved to a
103 * Thrown if the storage back-end does not exist and could not be created.
104 * @throws \Drupal\Component\Plugin\Exception\PluginException
105 * Thrown if the definition is invalid - for example, if the specified
106 * parent would cause the links children to be moved to greater than the
109 public function save(array $definition);
112 * Deletes a menu link definition from the storage.
115 * The menu link plugin ID.
117 public function delete($id);
120 * Loads a menu link tree from the storage.
122 * This function may be used build the data for a menu tree only, for example
123 * to further massage the data manually before further processing happens.
124 * MenuLinkTree::checkAccess() needs to be invoked afterwards.
126 * The tree order is maintained using an optimized algorithm, for example by
127 * storing each parent in an individual field, see
128 * https://www.drupal.org/node/141866 for more details. However, any details
129 * of the storage should not be relied upon since it may be swapped with a
130 * different implementation.
132 * @param string $menu_name
133 * The name of the menu.
134 * @param \Drupal\Core\Menu\MenuTreeParameters $parameters
135 * The parameters to determine which menu links to be loaded into a tree.
138 * An array with 2 elements:
139 * - tree: A fully built menu tree containing an array.
140 * @see static::treeDataRecursive()
141 * - route_names: An array of all route names used in the tree.
143 public function loadTreeData($menu_name, MenuTreeParameters $parameters);
146 * Loads all the enabled menu links that are below the given ID.
148 * The returned links are not ordered, and visible children will be included
149 * even if they have parent that is not enabled or ancestor so would not
150 * normally appear in a rendered tree.
153 * The parent menu link ID.
154 * @param int $max_relative_depth
155 * The maximum relative depth of the children relative to the passed parent.
158 * An array of enabled link definitions, keyed by ID.
160 public function loadAllChildren($id, $max_relative_depth = NULL);
163 * Loads all the IDs for menu links that are below the given ID.
166 * The parent menu link ID.
169 * An unordered array of plugin IDs corresponding to all children.
171 public function getAllChildIds($id);
174 * Loads a subtree rooted by the given ID.
176 * The returned links are structured like those from loadTreeData().
179 * The menu link plugin ID.
180 * @param int $max_relative_depth
181 * (optional) The maximum depth of child menu links relative to the passed
182 * in. Defaults to NULL, in which case the full subtree will be returned.
185 * An array with 2 elements:
186 * - subtree: A fully built menu tree element or FALSE.
187 * - route_names: An array of all route names used in the subtree.
189 public function loadSubtreeData($id, $max_relative_depth = NULL);
192 * Returns all the IDs that represent the path to the root of the tree.
198 * An associative array of IDs with keys equal to values that represents the
199 * path from the given ID to the root of the tree. If $id is an ID that
200 * exists, the returned array will at least include it. An empty array is
201 * returned if the ID does not exist in the storage. An example $id (8) with
202 * two parents (1, 6) looks like the following:
217 public function getRootPathIds($id);
220 * Finds expanded links in a menu given a set of possible parents.
222 * @param string $menu_name
224 * @param array $parents
225 * One or more parent IDs to match.
228 * The menu link IDs that are flagged as expanded in this menu.
230 public function getExpanded($menu_name, array $parents);
233 * Finds the height of a subtree rooted by the given ID.
236 * The ID of an item in the storage.
239 * Returns the height of the subtree. This will be at least 1 if the ID
240 * exists, or 0 if the ID does not exist in the storage.
242 public function getSubtreeHeight($id);
245 * Determines whether a specific menu name is used in the tree.
247 * @param string $menu_name
251 * Returns TRUE if the given menu name is used, otherwise FALSE.
253 public function menuNameInUse($menu_name);
256 * Returns the used menu names in the tree storage.
261 public function getMenuNames();
264 * Counts the total number of menu links in one menu or all menus.
266 * @param string $menu_name
267 * (optional) The menu name to count by. Defaults to all menus.
270 * The number of menu links in the named menu, or in all menus if the menu
273 public function countMenuLinks($menu_name = NULL);