MenuLinkManagerInterface.php 6.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195
  1. <?php
  2. namespace Drupal\Core\Menu;
  3. use Drupal\Component\Plugin\PluginManagerInterface;
  4. /**
  5. * Defines an interface for managing menu links and storing their definitions.
  6. *
  7. * Menu link managers support both automatic plugin definition discovery and
  8. * manually maintaining plugin definitions.
  9. *
  10. * MenuLinkManagerInterface::updateDefinition() can be used to update a single
  11. * menu link's definition and pass this onto the menu storage without requiring
  12. * a full MenuLinkManagerInterface::rebuild().
  13. *
  14. * Implementations that do not use automatic discovery should call
  15. * MenuLinkManagerInterface::addDefinition() or
  16. * MenuLinkManagerInterface::removeDefinition() when they add or remove links,
  17. * and MenuLinkManagerInterface::updateDefinition() to update links they have
  18. * already defined.
  19. */
  20. interface MenuLinkManagerInterface extends PluginManagerInterface {
  21. /**
  22. * Triggers discovery, save, and cleanup of discovered links.
  23. */
  24. public function rebuild();
  25. /**
  26. * Deletes all links having a certain menu name.
  27. *
  28. * If a link is not deletable but is resettable, the link will be reset to have
  29. * its original menu name, under the assumption that the original menu is not
  30. * the one we are deleting it from. Note that when resetting, if the original
  31. * menu name is the same as the menu name passed to this method, the link will
  32. * not be moved or deleted.
  33. *
  34. * @param string $menu_name
  35. * The name of the menu whose links will be deleted or reset.
  36. */
  37. public function deleteLinksInMenu($menu_name);
  38. /**
  39. * Removes a single link definition from the menu tree storage.
  40. *
  41. * This is used for plugins not found through discovery to remove definitions.
  42. *
  43. * @param string $id
  44. * The menu link plugin ID.
  45. * @param bool $persist
  46. * If TRUE, this method will attempt to persist the deletion from any
  47. * external storage by invoking MenuLinkInterface::deleteLink() on the
  48. * plugin that is being deleted.
  49. *
  50. * @throws \Drupal\Component\Plugin\Exception\PluginException
  51. * Thrown if the $id is not a valid, existing, plugin ID or if the link
  52. * cannot be deleted.
  53. */
  54. public function removeDefinition($id, $persist = TRUE);
  55. /**
  56. * Loads multiple plugin instances based on route.
  57. *
  58. * @param string $route_name
  59. * The route name.
  60. * @param array $route_parameters
  61. * (optional) The route parameters. Defaults to an empty array.
  62. * @param string $menu_name
  63. * (optional) Restricts the found links to just those in the named menu.
  64. *
  65. * @return \Drupal\Core\Menu\MenuLinkInterface[]
  66. * An array of instances keyed by plugin ID.
  67. */
  68. public function loadLinksByRoute($route_name, array $route_parameters = [], $menu_name = NULL);
  69. /**
  70. * Adds a new menu link definition to the menu tree storage.
  71. *
  72. * Use this function when you know there is no entry in the tree. This is
  73. * used for plugins not found through discovery to add new definitions.
  74. *
  75. * @param string $id
  76. * The plugin ID for the new menu link definition that is being added.
  77. * @param array $definition
  78. * The values of the link definition.
  79. *
  80. * @return \Drupal\Core\Menu\MenuLinkInterface
  81. * A plugin instance created using the newly added definition.
  82. *
  83. * @throws \Drupal\Component\Plugin\Exception\PluginException
  84. * Thrown when the $id is not valid or is an already existing plugin ID.
  85. */
  86. public function addDefinition($id, array $definition);
  87. /**
  88. * Updates the values for a menu link definition in the menu tree storage.
  89. *
  90. * This will update the definition for a discovered menu link without the
  91. * need for a full rebuild. It is also used for plugins not found through
  92. * discovery to update definitions.
  93. *
  94. * @param string $id
  95. * The menu link plugin ID.
  96. * @param array $new_definition_values
  97. * The new values for the link definition. This will usually be just a
  98. * subset of the plugin definition.
  99. * @param bool $persist
  100. * TRUE to also have the link instance itself persist the changed values to
  101. * any additional storage by invoking MenuLinkInterface::updateDefinition()
  102. * on the plugin that is being updated.
  103. *
  104. * @return \Drupal\Core\Menu\MenuLinkInterface
  105. * A plugin instance created using the updated definition.
  106. *
  107. * @throws \Drupal\Component\Plugin\Exception\PluginException
  108. * Thrown if the $id is not a valid, existing, plugin ID.
  109. */
  110. public function updateDefinition($id, array $new_definition_values, $persist = TRUE);
  111. /**
  112. * Resets the values for a menu link based on the values found by discovery.
  113. *
  114. * @param string $id
  115. * The menu link plugin ID.
  116. *
  117. * @return \Drupal\Core\Menu\MenuLinkInterface
  118. * The menu link instance after being reset.
  119. *
  120. * @throws \Drupal\Component\Plugin\Exception\PluginException
  121. * Thrown if the $id is not a valid, existing, plugin ID or if the link
  122. * cannot be reset.
  123. */
  124. public function resetLink($id);
  125. /**
  126. * Counts the total number of menu links.
  127. *
  128. * @param string $menu_name
  129. * (optional) The menu name to count by. Defaults to all menus.
  130. *
  131. * @return int
  132. * The number of menu links in the named menu, or in all menus if the
  133. * menu name is NULL.
  134. */
  135. public function countMenuLinks($menu_name = NULL);
  136. /**
  137. * Loads all parent link IDs of a given menu link.
  138. *
  139. * This method is very similar to getActiveTrailIds() but allows the link to
  140. * be specified rather than being discovered based on the menu name and
  141. * request. This method is mostly useful for testing.
  142. *
  143. * @param string $id
  144. * The menu link plugin ID.
  145. *
  146. * @return array
  147. * An ordered array of IDs representing the path to the root of the tree.
  148. * The first element of the array will be equal to $id, unless $id is not
  149. * valid, in which case the return value will be NULL.
  150. */
  151. public function getParentIds($id);
  152. /**
  153. * Loads all child link IDs of a given menu link, regardless of visibility.
  154. *
  155. * This method is mostly useful for testing.
  156. *
  157. * @param string $id
  158. * The menu link plugin ID.
  159. *
  160. * @return array
  161. * An unordered array of IDs representing the IDs of all children, or NULL
  162. * if the ID is invalid.
  163. */
  164. public function getChildIds($id);
  165. /**
  166. * Determines if any links use a given menu name.
  167. *
  168. * @param string $menu_name
  169. * The menu name.
  170. *
  171. * @return bool
  172. * TRUE if any links are present in the named menu, FALSE otherwise.
  173. */
  174. public function menuNameInUse($menu_name);
  175. /**
  176. * Resets any local definition cache. Used for testing.
  177. */
  178. public function resetDefinitions();
  179. }