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

   1 <?php
   2
   3 namespace Drupal\Core\Menu;
   4
   5 /**
   6  * Defines an interface for storing a menu tree containing menu link IDs.
   7  *
   8  * The tree contains a hierarchy of menu links which have an ID as well as a
   9  * route name or external URL.
  10  */
  11 interface MenuTreeStorageInterface {
  12
  13   /**
  14    * The maximum depth of tree the storage implementation supports.
  15    *
  16    * @return int
  17    *   The maximum depth.
  18    */
  19   public function maxDepth();
  20
  21   /**
  22    * Clears all definitions cached in memory.
  23    */
  24   public function resetDefinitions();
  25
  26   /**
  27    * Rebuilds the stored menu link definitions.
  28    *
  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.
  32    *
  33    * @param array $definitions
  34    *   The new menu link definitions.
  35    */
  36   public function rebuild(array $definitions);
  37
  38   /**
  39    * Loads a menu link plugin definition from the storage.
  40    *
  41    * @param string $id
  42    *   The menu link plugin ID.
  43    *
  44    * @return array|false
  45    *   The plugin definition, or FALSE if no definition was found for the ID.
  46    */
  47   public function load($id);
  48
  49   /**
  50    * Loads multiple plugin definitions from the storage.
  51    *
  52    * @param array $ids
  53    *   An array of plugin IDs.
  54    *
  55    * @return array
  56    *   An array of plugin definition arrays keyed by plugin ID, which are the
  57    *   actual definitions after the loadMultiple() including all those plugins
  58    *   from $ids.
  59    */
  60   public function loadMultiple(array $ids);
  61
  62   /**
  63    * Loads multiple plugin definitions from the storage based on properties.
  64    *
  65    * @param array $properties
  66    *   The properties to filter by.
  67    *
  68    * @return array
  69    *   An array of menu link definition arrays.
  70    *
  71    * @throws \InvalidArgumentException
  72    *   Thrown if an invalid property name is specified in $properties.
  73    */
  74   public function loadByProperties(array $properties);
  75
  76   /**
  77    * Loads multiple plugin definitions from the storage based on route.
  78    *
  79    * @param string $route_name
  80    *   The 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.
  85    *
  86    * @return array
  87    *   An array of menu link definitions keyed by ID and ordered by depth.
  88    */
  89   public function loadByRoute($route_name, array $route_parameters = [], $menu_name = NULL);
  90
  91   /**
  92    * Saves a plugin definition to the storage.
  93    *
  94    * @param array $definition
  95    *   A definition for a \Drupal\Core\Menu\MenuLinkInterface plugin.
  96    *
  97    * @return array
  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
 100    *   new menu.
 101    *
 102    * @throws \Exception
 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
 107    *   maximum depth.
 108    */
 109   public function save(array $definition);
 110
 111   /**
 112    * Deletes a menu link definition from the storage.
 113    *
 114    * @param string $id
 115    *   The menu link plugin ID.
 116    */
 117   public function delete($id);
 118
 119   /**
 120    * Loads a menu link tree from the storage.
 121    *
 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.
 125    *
 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.
 131    *
 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.
 136    *
 137    * @return array
 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.
 142    */
 143   public function loadTreeData($menu_name, MenuTreeParameters $parameters);
 144
 145   /**
 146    * Loads all the enabled menu links that are below the given ID.
 147    *
 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.
 151    *
 152    * @param string $id
 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.
 156    *
 157    * @return array
 158    *   An array of enabled link definitions, keyed by ID.
 159    */
 160   public function loadAllChildren($id, $max_relative_depth = NULL);
 161
 162   /**
 163    * Loads all the IDs for menu links that are below the given ID.
 164    *
 165    * @param string $id
 166    *   The parent menu link ID.
 167    *
 168    * @return array
 169    *   An unordered array of plugin IDs corresponding to all children.
 170    */
 171   public function getAllChildIds($id);
 172
 173   /**
 174    * Loads a subtree rooted by the given ID.
 175    *
 176    * The returned links are structured like those from loadTreeData().
 177    *
 178    * @param string $id
 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.
 183    *
 184    * @return array
 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.
 188    */
 189   public function loadSubtreeData($id, $max_relative_depth = NULL);
 190
 191   /**
 192    * Returns all the IDs that represent the path to the root of the tree.
 193    *
 194    * @param string $id
 195    *   A menu link ID.
 196    *
 197    * @return array
 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:
 203    * @code
 204    *   array(
 205    *     'p1' => 1,
 206    *     'p2' => 6,
 207    *     'p3' => 8,
 208    *     'p4' => 0,
 209    *     'p5' => 0,
 210    *     'p6' => 0,
 211    *     'p7' => 0,
 212    *     'p8' => 0,
 213    *     'p9' => 0
 214    *   )
 215    * @endcode
 216    */
 217   public function getRootPathIds($id);
 218
 219   /**
 220    * Finds expanded links in a menu given a set of possible parents.
 221    *
 222    * @param string $menu_name
 223    *   The menu name.
 224    * @param array $parents
 225    *   One or more parent IDs to match.
 226    *
 227    * @return array
 228    *   The menu link IDs that are flagged as expanded in this menu.
 229    */
 230   public function getExpanded($menu_name, array $parents);
 231
 232   /**
 233    * Finds the height of a subtree rooted by the given ID.
 234    *
 235    * @param string $id
 236    *   The ID of an item in the storage.
 237    *
 238    * @return int
 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.
 241    */
 242   public function getSubtreeHeight($id);
 243
 244   /**
 245    * Determines whether a specific menu name is used in the tree.
 246    *
 247    * @param string $menu_name
 248    *   The menu name.
 249    *
 250    * @return bool
 251    *   Returns TRUE if the given menu name is used, otherwise FALSE.
 252    */
 253   public function menuNameInUse($menu_name);
 254
 255   /**
 256    * Returns the used menu names in the tree storage.
 257    *
 258    * @return array
 259    *   The menu names.
 260    */
 261   public function getMenuNames();
 262
 263   /**
 264    * Counts the total number of menu links in one menu or all menus.
 265    *
 266    * @param string $menu_name
 267    *   (optional) The menu name to count by. Defaults to all menus.
 268    *
 269    * @return int
 270    *   The number of menu links in the named menu, or in all menus if the menu
 271    *   name is NULL.
 272    */
 273   public function countMenuLinks($menu_name = NULL);
 274
 275 }