3 namespace Drupal\Core\Menu;
6 * Provides a value object to model menu tree parameters.
8 * Menu tree parameters are used to determine the set of definitions to be
9 * loaded from \Drupal\Core\Menu\MenuTreeStorageInterface. Hence they determine
10 * the shape and content of the tree:
11 * - Which parent IDs should be used to restrict the tree. Only links with
12 * a parent in the list will be included.
13 * - Which menu links are omitted, depending on the minimum and maximum depth.
15 class MenuTreeParameters {
18 * A menu link plugin ID that should be used as the root.
20 * By default the root ID of empty string '' is used. However, when only the
21 * descendants (subtree) of a certain menu link are needed, a custom root can
29 * The minimum depth of menu links in the resulting tree relative to the root.
31 * Defaults to 1, which is the default to build a whole tree for a menu
32 * (excluding the root).
36 public $minDepth = NULL;
39 * The maximum depth of menu links in the resulting tree relative to the root.
43 public $maxDepth = NULL;
46 * An array of parent link IDs.
48 * This restricts the tree to only menu links that are at the top level or
49 * have a parent ID in this list. If empty, the whole menu tree is built.
53 public $expandedParents = [];
56 * The IDs from the currently active menu link to the root of the whole tree.
58 * This is an array of menu link plugin IDs, representing the trail from the
59 * currently active menu link to the ("real") root of that menu link's menu.
60 * This does not affect the way the tree is built. It is only used to set the
61 * value of the inActiveTrail property for each tree element.
65 public $activeTrail = [];
68 * The conditions used to restrict which links are loaded.
70 * An associative array of custom query condition key/value pairs.
74 public $conditions = [];
77 * Sets a root for menu tree loading.
80 * A menu link plugin ID, or empty string '' to use the root of the whole
87 public function setRoot($root) {
88 $this->root = (string) $root;
93 * Sets a minimum depth for menu tree loading.
95 * @param int $min_depth
96 * The (root-relative) minimum depth to apply.
100 public function setMinDepth($min_depth) {
101 $this->minDepth = max(1, $min_depth);
106 * Sets a maximum depth for menu tree loading.
108 * @param int $max_depth
109 * The (root-relative) maximum depth to apply.
113 * @codeCoverageIgnore
115 public function setMaxDepth($max_depth) {
116 $this->maxDepth = $max_depth;
121 * Adds parent menu links IDs to restrict the tree.
123 * @param string[] $parents
124 * An array containing parent IDs. If supplied, the tree is limited to
125 * links that have these parents.
129 public function addExpandedParents(array $parents) {
130 $this->expandedParents = array_merge($this->expandedParents, $parents);
131 $this->expandedParents = array_unique($this->expandedParents);
136 * Sets the active trail IDs used to set the inActiveTrail property.
138 * @param string[] $active_trail
139 * An array containing the active trail: a list of menu link plugin IDs.
143 * @see \Drupal\Core\Menu\MenuActiveTrail::getActiveTrailIds()
145 * @codeCoverageIgnore
147 public function setActiveTrail(array $active_trail) {
148 $this->activeTrail = $active_trail;
153 * Adds a custom query condition.
155 * @param string $definition_field
156 * Only conditions that are testing menu link definition fields are allowed.
157 * @param mixed $value
158 * The value to test the link definition field against. In most cases, this
159 * is a scalar. For more complex options, it is an array. The meaning of
160 * each element in the array is dependent on the $operator.
161 * @param string|null $operator
162 * (optional) The comparison operator, such as =, <, or >=. It also accepts
163 * more complex options such as IN, LIKE, or BETWEEN. If NULL, defaults to
168 public function addCondition($definition_field, $value, $operator = NULL) {
169 if (!isset($operator)) {
170 $this->conditions[$definition_field] = $value;
173 $this->conditions[$definition_field] = [$value, $operator];
179 * Excludes links that are not enabled.
183 public function onlyEnabledLinks() {
184 $this->addCondition('enabled', 1);
189 * Ensures only the top level of the tree is loaded.
193 public function setTopLevelOnly() {
194 $this->setMaxDepth(1);
199 * Excludes the root menu link from the tree.
201 * Note that this is only necessary when you specified a custom root, because
202 * the normal root ID is the empty string, '', which does not correspond to an
203 * actual menu link. Hence when loading a menu link tree without specifying a
204 * custom root the tree will start at the children even if this method has not
209 public function excludeRoot() {
210 $this->setMinDepth(1);