aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Menu/MenuLinkManagerInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Menu;
   4
   5 use 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  */
  23 interface 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 }