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

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents af1871eacc83
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 namespace Drupal\Core\Menu;
Chris@0 4
Chris@0 5 /**
Chris@0 6 * Provides a value object to model menu tree parameters.
Chris@0 7 *
Chris@0 8 * Menu tree parameters are used to determine the set of definitions to be
Chris@0 9 * loaded from \Drupal\Core\Menu\MenuTreeStorageInterface. Hence they determine
Chris@0 10 * the shape and content of the tree:
Chris@0 11 * - Which parent IDs should be used to restrict the tree. Only links with
Chris@0 12 * a parent in the list will be included.
Chris@0 13 * - Which menu links are omitted, depending on the minimum and maximum depth.
Chris@0 14 */
Chris@18 15 class MenuTreeParameters implements \Serializable {
Chris@0 16
Chris@0 17 /**
Chris@0 18 * A menu link plugin ID that should be used as the root.
Chris@0 19 *
Chris@0 20 * By default the root ID of empty string '' is used. However, when only the
Chris@0 21 * descendants (subtree) of a certain menu link are needed, a custom root can
Chris@0 22 * be specified.
Chris@0 23 *
Chris@0 24 * @var string
Chris@0 25 */
Chris@0 26 public $root = '';
Chris@0 27
Chris@0 28 /**
Chris@0 29 * The minimum depth of menu links in the resulting tree relative to the root.
Chris@0 30 *
Chris@0 31 * @var int|null
Chris@0 32 */
Chris@0 33 public $minDepth = NULL;
Chris@0 34
Chris@0 35 /**
Chris@0 36 * The maximum depth of menu links in the resulting tree relative to the root.
Chris@0 37 *
Chris@0 38 * @var int|null
Chris@0 39 */
Chris@0 40 public $maxDepth = NULL;
Chris@0 41
Chris@0 42 /**
Chris@0 43 * An array of parent link IDs.
Chris@0 44 *
Chris@0 45 * This restricts the tree to only menu links that are at the top level or
Chris@0 46 * have a parent ID in this list. If empty, the whole menu tree is built.
Chris@0 47 *
Chris@0 48 * @var string[]
Chris@0 49 */
Chris@0 50 public $expandedParents = [];
Chris@0 51
Chris@0 52 /**
Chris@0 53 * The IDs from the currently active menu link to the root of the whole tree.
Chris@0 54 *
Chris@0 55 * This is an array of menu link plugin IDs, representing the trail from the
Chris@0 56 * currently active menu link to the ("real") root of that menu link's menu.
Chris@0 57 * This does not affect the way the tree is built. It is only used to set the
Chris@0 58 * value of the inActiveTrail property for each tree element.
Chris@0 59 *
Chris@0 60 * @var string[]
Chris@0 61 */
Chris@0 62 public $activeTrail = [];
Chris@0 63
Chris@0 64 /**
Chris@0 65 * The conditions used to restrict which links are loaded.
Chris@0 66 *
Chris@0 67 * An associative array of custom query condition key/value pairs.
Chris@0 68 *
Chris@0 69 * @var array
Chris@0 70 */
Chris@0 71 public $conditions = [];
Chris@0 72
Chris@0 73 /**
Chris@0 74 * Sets a root for menu tree loading.
Chris@0 75 *
Chris@0 76 * @param string $root
Chris@0 77 * A menu link plugin ID, or empty string '' to use the root of the whole
Chris@0 78 * tree.
Chris@0 79 *
Chris@0 80 * @return $this
Chris@0 81 *
Chris@0 82 * @codeCoverageIgnore
Chris@0 83 */
Chris@0 84 public function setRoot($root) {
Chris@0 85 $this->root = (string) $root;
Chris@0 86 return $this;
Chris@0 87 }
Chris@0 88
Chris@0 89 /**
Chris@0 90 * Sets a minimum depth for menu tree loading.
Chris@0 91 *
Chris@0 92 * @param int $min_depth
Chris@0 93 * The (root-relative) minimum depth to apply.
Chris@0 94 *
Chris@0 95 * @return $this
Chris@0 96 */
Chris@0 97 public function setMinDepth($min_depth) {
Chris@0 98 $this->minDepth = max(1, $min_depth);
Chris@0 99 return $this;
Chris@0 100 }
Chris@0 101
Chris@0 102 /**
Chris@0 103 * Sets a maximum depth for menu tree loading.
Chris@0 104 *
Chris@0 105 * @param int $max_depth
Chris@0 106 * The (root-relative) maximum depth to apply.
Chris@0 107 *
Chris@0 108 * @return $this
Chris@0 109 *
Chris@0 110 * @codeCoverageIgnore
Chris@0 111 */
Chris@0 112 public function setMaxDepth($max_depth) {
Chris@0 113 $this->maxDepth = $max_depth;
Chris@0 114 return $this;
Chris@0 115 }
Chris@0 116
Chris@0 117 /**
Chris@0 118 * Adds parent menu links IDs to restrict the tree.
Chris@0 119 *
Chris@0 120 * @param string[] $parents
Chris@0 121 * An array containing parent IDs. If supplied, the tree is limited to
Chris@0 122 * links that have these parents.
Chris@0 123 *
Chris@0 124 * @return $this
Chris@0 125 */
Chris@0 126 public function addExpandedParents(array $parents) {
Chris@0 127 $this->expandedParents = array_merge($this->expandedParents, $parents);
Chris@0 128 $this->expandedParents = array_unique($this->expandedParents);
Chris@0 129 return $this;
Chris@0 130 }
Chris@0 131
Chris@0 132 /**
Chris@0 133 * Sets the active trail IDs used to set the inActiveTrail property.
Chris@0 134 *
Chris@0 135 * @param string[] $active_trail
Chris@0 136 * An array containing the active trail: a list of menu link plugin IDs.
Chris@0 137 *
Chris@0 138 * @return $this
Chris@0 139 *
Chris@0 140 * @see \Drupal\Core\Menu\MenuActiveTrail::getActiveTrailIds()
Chris@0 141 *
Chris@0 142 * @codeCoverageIgnore
Chris@0 143 */
Chris@0 144 public function setActiveTrail(array $active_trail) {
Chris@0 145 $this->activeTrail = $active_trail;
Chris@0 146 return $this;
Chris@0 147 }
Chris@0 148
Chris@0 149 /**
Chris@0 150 * Adds a custom query condition.
Chris@0 151 *
Chris@0 152 * @param string $definition_field
Chris@0 153 * Only conditions that are testing menu link definition fields are allowed.
Chris@0 154 * @param mixed $value
Chris@0 155 * The value to test the link definition field against. In most cases, this
Chris@0 156 * is a scalar. For more complex options, it is an array. The meaning of
Chris@0 157 * each element in the array is dependent on the $operator.
Chris@0 158 * @param string|null $operator
Chris@0 159 * (optional) The comparison operator, such as =, <, or >=. It also accepts
Chris@0 160 * more complex options such as IN, LIKE, or BETWEEN. If NULL, defaults to
Chris@0 161 * the = operator.
Chris@0 162 *
Chris@0 163 * @return $this
Chris@0 164 */
Chris@0 165 public function addCondition($definition_field, $value, $operator = NULL) {
Chris@0 166 if (!isset($operator)) {
Chris@0 167 $this->conditions[$definition_field] = $value;
Chris@0 168 }
Chris@0 169 else {
Chris@0 170 $this->conditions[$definition_field] = [$value, $operator];
Chris@0 171 }
Chris@0 172 return $this;
Chris@0 173 }
Chris@0 174
Chris@0 175 /**
Chris@0 176 * Excludes links that are not enabled.
Chris@0 177 *
Chris@0 178 * @return $this
Chris@0 179 */
Chris@0 180 public function onlyEnabledLinks() {
Chris@0 181 $this->addCondition('enabled', 1);
Chris@0 182 return $this;
Chris@0 183 }
Chris@0 184
Chris@0 185 /**
Chris@0 186 * Ensures only the top level of the tree is loaded.
Chris@0 187 *
Chris@0 188 * @return $this
Chris@0 189 */
Chris@0 190 public function setTopLevelOnly() {
Chris@0 191 $this->setMaxDepth(1);
Chris@0 192 return $this;
Chris@0 193 }
Chris@0 194
Chris@0 195 /**
Chris@0 196 * Excludes the root menu link from the tree.
Chris@0 197 *
Chris@0 198 * Note that this is only necessary when you specified a custom root, because
Chris@0 199 * the normal root ID is the empty string, '', which does not correspond to an
Chris@0 200 * actual menu link. Hence when loading a menu link tree without specifying a
Chris@0 201 * custom root the tree will start at the children even if this method has not
Chris@0 202 * been called.
Chris@0 203 *
Chris@0 204 * @return $this
Chris@0 205 */
Chris@0 206 public function excludeRoot() {
Chris@0 207 $this->setMinDepth(1);
Chris@0 208 return $this;
Chris@0 209 }
Chris@0 210
Chris@18 211 /**
Chris@18 212 * {@inheritdoc}
Chris@18 213 */
Chris@18 214 public function serialize() {
Chris@18 215 // Enforce type consistency for all the internal properties of this object.
Chris@18 216 $this->root = (string) $this->root;
Chris@18 217 $this->minDepth = $this->minDepth !== NULL ? (int) $this->minDepth : NULL;
Chris@18 218 $this->maxDepth = $this->maxDepth !== NULL ? (int) $this->maxDepth : NULL;
Chris@18 219 $this->activeTrail = array_values(array_filter($this->activeTrail));
Chris@18 220
Chris@18 221 // Sort 'expanded' and 'conditions' to prevent duplicate cache items.
Chris@18 222 sort($this->expandedParents);
Chris@18 223 asort($this->conditions);
Chris@18 224
Chris@18 225 return serialize([
Chris@18 226 'root' => $this->root,
Chris@18 227 'minDepth' => $this->minDepth,
Chris@18 228 'maxDepth' => $this->maxDepth,
Chris@18 229 'expandedParents' => $this->expandedParents,
Chris@18 230 'activeTrail' => $this->activeTrail,
Chris@18 231 'conditions' => $this->conditions,
Chris@18 232 ]);
Chris@18 233 }
Chris@18 234
Chris@18 235 /**
Chris@18 236 * {@inheritdoc}
Chris@18 237 */
Chris@18 238 public function unserialize($serialized) {
Chris@18 239 foreach (unserialize($serialized) as $key => $value) {
Chris@18 240 $this->{$key} = $value;
Chris@18 241 }
Chris@18 242
Chris@18 243 return $this;
Chris@18 244 }
Chris@18 245
Chris@0 246 }