annotate core/lib/Drupal/Core/Menu/MenuLinkManagerInterface.php @ 19:fa3358dc1485 tip

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