3 namespace Drupal\Core\Menu;
5 use Drupal\Component\Plugin\PluginManagerInterface;
8 * Defines an interface for managing menu links and storing their definitions.
10 * Menu link managers support both automatic plugin definition discovery and
11 * manually maintaining plugin definitions.
13 * MenuLinkManagerInterface::updateDefinition() can be used to update a single
14 * menu link's definition and pass this onto the menu storage without requiring
15 * a full MenuLinkManagerInterface::rebuild().
17 * Implementations that do not use automatic discovery should call
18 * MenuLinkManagerInterface::addDefinition() or
19 * MenuLinkManagerInterface::removeDefinition() when they add or remove links,
20 * and MenuLinkManagerInterface::updateDefinition() to update links they have
23 interface MenuLinkManagerInterface extends PluginManagerInterface {
26 * Triggers discovery, save, and cleanup of discovered links.
28 public function rebuild();
31 * Deletes all links having a certain menu name.
33 * If a link is not deletable but is resettable, the link will be reset to have
34 * its original menu name, under the assumption that the original menu is not
35 * the one we are deleting it from. Note that when resetting, if the original
36 * menu name is the same as the menu name passed to this method, the link will
37 * not be moved or deleted.
39 * @param string $menu_name
40 * The name of the menu whose links will be deleted or reset.
42 public function deleteLinksInMenu($menu_name);
45 * Removes a single link definition from the menu tree storage.
47 * This is used for plugins not found through discovery to remove definitions.
50 * The menu link plugin ID.
51 * @param bool $persist
52 * If TRUE, this method will attempt to persist the deletion from any
53 * external storage by invoking MenuLinkInterface::deleteLink() on the
54 * plugin that is being deleted.
56 * @throws \Drupal\Component\Plugin\Exception\PluginException
57 * Thrown if the $id is not a valid, existing, plugin ID or if the link
60 public function removeDefinition($id, $persist = TRUE);
63 * Loads multiple plugin instances based on route.
65 * @param string $route_name
67 * @param array $route_parameters
68 * (optional) The route parameters. Defaults to an empty array.
69 * @param string $menu_name
70 * (optional) Restricts the found links to just those in the named menu.
72 * @return \Drupal\Core\Menu\MenuLinkInterface[]
73 * An array of instances keyed by plugin ID.
75 public function loadLinksByRoute($route_name, array $route_parameters = [], $menu_name = NULL);
78 * Adds a new menu link definition to the menu tree storage.
80 * Use this function when you know there is no entry in the tree. This is
81 * used for plugins not found through discovery to add new definitions.
84 * The plugin ID for the new menu link definition that is being added.
85 * @param array $definition
86 * The values of the link definition.
88 * @return \Drupal\Core\Menu\MenuLinkInterface
89 * A plugin instance created using the newly added definition.
91 * @throws \Drupal\Component\Plugin\Exception\PluginException
92 * Thrown when the $id is not valid or is an already existing plugin ID.
94 public function addDefinition($id, array $definition);
97 * Updates the values for a menu link definition in the menu tree storage.
99 * This will update the definition for a discovered menu link without the
100 * need for a full rebuild. It is also used for plugins not found through
101 * discovery to update definitions.
104 * The menu link plugin ID.
105 * @param array $new_definition_values
106 * The new values for the link definition. This will usually be just a
107 * subset of the plugin definition.
108 * @param bool $persist
109 * TRUE to also have the link instance itself persist the changed values to
110 * any additional storage by invoking MenuLinkInterface::updateDefinition()
111 * on the plugin that is being updated.
113 * @return \Drupal\Core\Menu\MenuLinkInterface
114 * A plugin instance created using the updated definition.
116 * @throws \Drupal\Component\Plugin\Exception\PluginException
117 * Thrown if the $id is not a valid, existing, plugin ID.
119 public function updateDefinition($id, array $new_definition_values, $persist = TRUE);
122 * Resets the values for a menu link based on the values found by discovery.
125 * The menu link plugin ID.
127 * @return \Drupal\Core\Menu\MenuLinkInterface
128 * The menu link instance after being reset.
130 * @throws \Drupal\Component\Plugin\Exception\PluginException
131 * Thrown if the $id is not a valid, existing, plugin ID or if the link
134 public function resetLink($id);
137 * Counts the total number of menu links.
139 * @param string $menu_name
140 * (optional) The menu name to count by. Defaults to all menus.
143 * The number of menu links in the named menu, or in all menus if the
146 public function countMenuLinks($menu_name = NULL);
149 * Loads all parent link IDs of a given menu link.
151 * This method is very similar to getActiveTrailIds() but allows the link to
152 * be specified rather than being discovered based on the menu name and
153 * request. This method is mostly useful for testing.
156 * The menu link plugin ID.
159 * An ordered array of IDs representing the path to the root of the tree.
160 * The first element of the array will be equal to $id, unless $id is not
161 * valid, in which case the return value will be NULL.
163 public function getParentIds($id);
166 * Loads all child link IDs of a given menu link, regardless of visibility.
168 * This method is mostly useful for testing.
171 * The menu link plugin ID.
174 * An unordered array of IDs representing the IDs of all children, or NULL
175 * if the ID is invalid.
177 public function getChildIds($id);
180 * Determines if any links use a given menu name.
182 * @param string $menu_name
186 * TRUE if any links are present in the named menu, FALSE otherwise.
188 public function menuNameInUse($menu_name);
191 * Resets any local definition cache. Used for testing.
193 public function resetDefinitions();