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