MenuTreeStorageInterface.php
Same filename in other branches
Namespace
Drupal\Core\MenuFile
-
core/
lib/ Drupal/ Core/ Menu/ MenuTreeStorageInterface.php
View source
<?php
namespace Drupal\Core\Menu;
/**
* Defines an interface for storing a menu tree containing menu link IDs.
*
* The tree contains a hierarchy of menu links which have an ID as well as a
* route name or external URL.
*/
interface MenuTreeStorageInterface {
/**
* The maximum depth of tree the storage implementation supports.
*
* @return int
* The maximum depth.
*/
public function maxDepth();
/**
* Clears all definitions cached in memory.
*/
public function resetDefinitions();
/**
* Rebuilds the stored menu link definitions.
*
* Links that saved by passing definitions into this method must be included
* on all future calls, or they will be purged. This allows for automatic
* cleanup e.g. when modules are uninstalled.
*
* @param array $definitions
* The new menu link definitions.
*/
public function rebuild(array $definitions);
/**
* Loads a menu link plugin definition from the storage.
*
* @param string $id
* The menu link plugin ID.
*
* @return array|false
* The plugin definition, or FALSE if no definition was found for the ID.
*/
public function load($id);
/**
* Loads multiple plugin definitions from the storage.
*
* @param array $ids
* An array of plugin IDs.
*
* @return array
* An array of plugin definition arrays keyed by plugin ID, which are the
* actual definitions after the loadMultiple() including all those plugins
* from $ids.
*/
public function loadMultiple(array $ids);
/**
* Loads multiple plugin definitions from the storage based on properties.
*
* @param array $properties
* The properties to filter by.
*
* @return array
* An array of menu link definition arrays.
*
* @throws \InvalidArgumentException
* Thrown if an invalid property name is specified in $properties.
*/
public function loadByProperties(array $properties);
/**
* Loads multiple plugin definitions from the storage based on route.
*
* @param string $route_name
* The route name.
* @param array $route_parameters
* (optional) The route parameters. Defaults to an empty array.
* @param string $menu_name
* (optional) Restricts the found links to just those in the named menu.
*
* @return array
* An array of menu link definitions keyed by ID and ordered by depth.
*/
public function loadByRoute($route_name, array $route_parameters = [], $menu_name = NULL);
/**
* Saves a plugin definition to the storage.
*
* @param array $definition
* A definition for a \Drupal\Core\Menu\MenuLinkInterface plugin.
*
* @return array
* The menu names affected by the save operation. This will be one menu
* name if the link is saved to the sane menu, or two if it is saved to a
* new menu.
*
* @throws \Exception
* Thrown if the storage back-end does not exist and could not be created.
* @throws \Drupal\Component\Plugin\Exception\PluginException
* Thrown if the definition is invalid - for example, if the specified
* parent would cause the links children to be moved to greater than the
* maximum depth.
*/
public function save(array $definition);
/**
* Deletes a menu link definition from the storage.
*
* @param string $id
* The menu link plugin ID.
*/
public function delete($id);
/**
* Loads a menu link tree from the storage.
*
* This function may be used build the data for a menu tree only, for example
* to further massage the data manually before further processing happens.
* MenuLinkTree::checkAccess() needs to be invoked afterwards.
*
* The tree order is maintained using an optimized algorithm, for example by
* storing each parent in an individual field, see
* https://www.drupal.org/node/141866 for more details. However, any details
* of the storage should not be relied upon since it may be swapped with a
* different implementation.
*
* @param string $menu_name
* The name of the menu.
* @param \Drupal\Core\Menu\MenuTreeParameters $parameters
* The parameters to determine which menu links to be loaded into a tree.
*
* @return array
* An array with 2 elements:
* - tree: A fully built menu tree containing an array.
* @see static::treeDataRecursive()
* - route_names: An array of all route names used in the tree.
*/
public function loadTreeData($menu_name, MenuTreeParameters $parameters);
/**
* Loads all the enabled menu links that are below the given ID.
*
* The returned links are not ordered, and visible children will be included
* even if they have parent that is not enabled or ancestor so would not
* normally appear in a rendered tree.
*
* @param string $id
* The parent menu link ID.
* @param int $max_relative_depth
* The maximum relative depth of the children relative to the passed parent.
*
* @return array
* An array of enabled link definitions, keyed by ID.
*/
public function loadAllChildren($id, $max_relative_depth = NULL);
/**
* Loads all the IDs for menu links that are below the given ID.
*
* @param string $id
* The parent menu link ID.
*
* @return array
* An unordered array of plugin IDs corresponding to all children.
*/
public function getAllChildIds($id);
/**
* Loads a subtree rooted by the given ID.
*
* The returned links are structured like those from loadTreeData().
*
* @param string $id
* The menu link plugin ID.
* @param int $max_relative_depth
* (optional) The maximum depth of child menu links relative to the passed
* in. Defaults to NULL, in which case the full subtree will be returned.
*
* @return array
* An array with 2 elements:
* - subtree: A fully built menu tree element or FALSE.
* - route_names: An array of all route names used in the subtree.
*/
public function loadSubtreeData($id, $max_relative_depth = NULL);
/**
* Returns all the IDs that represent the path to the root of the tree.
*
* @param string $id
* A menu link ID.
*
* @return array
* An associative array of IDs with keys equal to values that represents the
* path from the given ID to the root of the tree. If $id is an ID that
* exists, the returned array will at least include it. An empty array is
* returned if the ID does not exist in the storage. An example $id (8) with
* two parents (1, 6) looks like the following:
* @code
* array(
* 'p1' => 1,
* 'p2' => 6,
* 'p3' => 8,
* 'p4' => 0,
* 'p5' => 0,
* 'p6' => 0,
* 'p7' => 0,
* 'p8' => 0,
* 'p9' => 0
* )
* @endcode
*/
public function getRootPathIds($id);
/**
* Finds expanded links in a menu given a set of possible parents.
*
* @param string $menu_name
* The menu name.
* @param array $parents
* One or more parent IDs to match.
*
* @return array
* The menu link IDs that are flagged as expanded in this menu.
*/
public function getExpanded($menu_name, array $parents);
/**
* Finds the height of a subtree rooted by the given ID.
*
* @param string $id
* The ID of an item in the storage.
*
* @return int
* Returns the height of the subtree. This will be at least 1 if the ID
* exists, or 0 if the ID does not exist in the storage.
*/
public function getSubtreeHeight($id);
/**
* Determines whether a specific menu name is used in the tree.
*
* @param string $menu_name
* The menu name.
*
* @return bool
* Returns TRUE if the given menu name is used, otherwise FALSE.
*/
public function menuNameInUse($menu_name);
/**
* Returns the used menu names in the tree storage.
*
* @return array
* The menu names.
*/
public function getMenuNames();
/**
* Counts the total number of menu links in one menu or all menus.
*
* @param string $menu_name
* (optional) The menu name to count by. Defaults to all menus.
*
* @return int
* The number of menu links in the named menu, or in all menus if the menu
* name is NULL.
*/
public function countMenuLinks($menu_name = NULL);
}
Interfaces
Title | Deprecated | Summary |
---|---|---|
MenuTreeStorageInterface | Defines an interface for storing a menu tree containing menu link IDs. |
Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.