1<?php 2 3namespace Drupal\Core\Menu; 4 5use Drupal\Component\Plugin\PluginManagerInterface; 6 7/** 8 * Defines an interface for managing menu links and storing their definitions. 9 * 10 * Menu link managers support both automatic plugin definition discovery and 11 * manually maintaining plugin definitions. 12 * 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(). 16 * 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 21 * already defined. 22 */ 23interface MenuLinkManagerInterface extends PluginManagerInterface { 24 25 /** 26 * Triggers discovery, save, and cleanup of discovered links. 27 */ 28 public function rebuild(); 29 30 /** 31 * Deletes all links having a certain menu name. 32 * 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. 38 * 39 * @param string $menu_name 40 * The name of the menu whose links will be deleted or reset. 41 */ 42 public function deleteLinksInMenu($menu_name); 43 44 /** 45 * Removes a single link definition from the menu tree storage. 46 * 47 * This is used for plugins not found through discovery to remove definitions. 48 * 49 * @param string $id 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. 55 * 56 * @throws \Drupal\Component\Plugin\Exception\PluginException 57 * Thrown if the $id is not a valid, existing, plugin ID or if the link 58 * cannot be deleted. 59 */ 60 public function removeDefinition($id, $persist = TRUE); 61 62 /** 63 * Loads multiple plugin instances based on route. 64 * 65 * @param string $route_name 66 * The 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. 71 * 72 * @return \Drupal\Core\Menu\MenuLinkInterface[] 73 * An array of instances keyed by plugin ID. 74 */ 75 public function loadLinksByRoute($route_name, array $route_parameters = [], $menu_name = NULL); 76 77 /** 78 * Adds a new menu link definition to the menu tree storage. 79 * 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. 82 * 83 * @param string $id 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. 87 * 88 * @return \Drupal\Core\Menu\MenuLinkInterface 89 * A plugin instance created using the newly added definition. 90 * 91 * @throws \Drupal\Component\Plugin\Exception\PluginException 92 * Thrown when the $id is not valid or is an already existing plugin ID. 93 */ 94 public function addDefinition($id, array $definition); 95 96 /** 97 * Updates the values for a menu link definition in the menu tree storage. 98 * 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. 102 * 103 * @param string $id 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. 112 * 113 * @return \Drupal\Core\Menu\MenuLinkInterface 114 * A plugin instance created using the updated definition. 115 * 116 * @throws \Drupal\Component\Plugin\Exception\PluginException 117 * Thrown if the $id is not a valid, existing, plugin ID. 118 */ 119 public function updateDefinition($id, array $new_definition_values, $persist = TRUE); 120 121 /** 122 * Resets the values for a menu link based on the values found by discovery. 123 * 124 * @param string $id 125 * The menu link plugin ID. 126 * 127 * @return \Drupal\Core\Menu\MenuLinkInterface 128 * The menu link instance after being reset. 129 * 130 * @throws \Drupal\Component\Plugin\Exception\PluginException 131 * Thrown if the $id is not a valid, existing, plugin ID or if the link 132 * cannot be reset. 133 */ 134 public function resetLink($id); 135 136 /** 137 * Counts the total number of menu links. 138 * 139 * @param string $menu_name 140 * (optional) The menu name to count by. Defaults to all menus. 141 * 142 * @return int 143 * The number of menu links in the named menu, or in all menus if the 144 * menu name is NULL. 145 */ 146 public function countMenuLinks($menu_name = NULL); 147 148 /** 149 * Loads all parent link IDs of a given menu link. 150 * 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. 154 * 155 * @param string $id 156 * The menu link plugin ID. 157 * 158 * @return array 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. 162 */ 163 public function getParentIds($id); 164 165 /** 166 * Loads all child link IDs of a given menu link, regardless of visibility. 167 * 168 * This method is mostly useful for testing. 169 * 170 * @param string $id 171 * The menu link plugin ID. 172 * 173 * @return array 174 * An unordered array of IDs representing the IDs of all children, or NULL 175 * if the ID is invalid. 176 */ 177 public function getChildIds($id); 178 179 /** 180 * Determines if any links use a given menu name. 181 * 182 * @param string $menu_name 183 * The menu name. 184 * 185 * @return bool 186 * TRUE if any links are present in the named menu, FALSE otherwise. 187 */ 188 public function menuNameInUse($menu_name); 189 190 /** 191 * Resets any local definition cache. Used for testing. 192 */ 193 public function resetDefinitions(); 194 195} 196