Chris@0: <?php
Chris@0: 
Chris@0: namespace Drupal\Core\Menu;
Chris@0: 
Chris@0: /**
Chris@0:  * Provides a value object to model menu tree parameters.
Chris@0:  *
Chris@0:  * Menu tree parameters are used to determine the set of definitions to be
Chris@0:  * loaded from \Drupal\Core\Menu\MenuTreeStorageInterface. Hence they determine
Chris@0:  * the shape and content of the tree:
Chris@0:  * - Which parent IDs should be used to restrict the tree. Only links with
Chris@0:  *   a parent in the list will be included.
Chris@0:  * - Which menu links are omitted, depending on the minimum and maximum depth.
Chris@0:  */
Chris@18: class MenuTreeParameters implements \Serializable {
Chris@0: 
Chris@0:   /**
Chris@0:    * A menu link plugin ID that should be used as the root.
Chris@0:    *
Chris@0:    * By default the root ID of empty string '' is used. However, when only the
Chris@0:    * descendants (subtree) of a certain menu link are needed, a custom root can
Chris@0:    * be specified.
Chris@0:    *
Chris@0:    * @var string
Chris@0:    */
Chris@0:   public $root = '';
Chris@0: 
Chris@0:   /**
Chris@0:    * The minimum depth of menu links in the resulting tree relative to the root.
Chris@0:    *
Chris@0:    * @var int|null
Chris@0:    */
Chris@0:   public $minDepth = NULL;
Chris@0: 
Chris@0:   /**
Chris@0:    * The maximum depth of menu links in the resulting tree relative to the root.
Chris@0:    *
Chris@0:    * @var int|null
Chris@0:    */
Chris@0:   public $maxDepth = NULL;
Chris@0: 
Chris@0:   /**
Chris@0:    * An array of parent link IDs.
Chris@0:    *
Chris@0:    * This restricts the tree to only menu links that are at the top level or
Chris@0:    * have a parent ID in this list. If empty, the whole menu tree is built.
Chris@0:    *
Chris@0:    * @var string[]
Chris@0:    */
Chris@0:   public $expandedParents = [];
Chris@0: 
Chris@0:   /**
Chris@0:    * The IDs from the currently active menu link to the root of the whole tree.
Chris@0:    *
Chris@0:    * This is an array of menu link plugin IDs, representing the trail from the
Chris@0:    * currently active menu link to the ("real") root of that menu link's menu.
Chris@0:    * This does not affect the way the tree is built. It is only used to set the
Chris@0:    * value of the inActiveTrail property for each tree element.
Chris@0:    *
Chris@0:    * @var string[]
Chris@0:    */
Chris@0:   public $activeTrail = [];
Chris@0: 
Chris@0:   /**
Chris@0:    * The conditions used to restrict which links are loaded.
Chris@0:    *
Chris@0:    * An associative array of custom query condition key/value pairs.
Chris@0:    *
Chris@0:    * @var array
Chris@0:    */
Chris@0:   public $conditions = [];
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets a root for menu tree loading.
Chris@0:    *
Chris@0:    * @param string $root
Chris@0:    *   A menu link plugin ID, or empty string '' to use the root of the whole
Chris@0:    *   tree.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    *
Chris@0:    * @codeCoverageIgnore
Chris@0:    */
Chris@0:   public function setRoot($root) {
Chris@0:     $this->root = (string) $root;
Chris@0:     return $this;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets a minimum depth for menu tree loading.
Chris@0:    *
Chris@0:    * @param int $min_depth
Chris@0:    *   The (root-relative) minimum depth to apply.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    */
Chris@0:   public function setMinDepth($min_depth) {
Chris@0:     $this->minDepth = max(1, $min_depth);
Chris@0:     return $this;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets a maximum depth for menu tree loading.
Chris@0:    *
Chris@0:    * @param int $max_depth
Chris@0:    *   The (root-relative) maximum depth to apply.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    *
Chris@0:    * @codeCoverageIgnore
Chris@0:    */
Chris@0:   public function setMaxDepth($max_depth) {
Chris@0:     $this->maxDepth = $max_depth;
Chris@0:     return $this;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Adds parent menu links IDs to restrict the tree.
Chris@0:    *
Chris@0:    * @param string[] $parents
Chris@0:    *   An array containing parent IDs. If supplied, the tree is limited to
Chris@0:    *   links that have these parents.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    */
Chris@0:   public function addExpandedParents(array $parents) {
Chris@0:     $this->expandedParents = array_merge($this->expandedParents, $parents);
Chris@0:     $this->expandedParents = array_unique($this->expandedParents);
Chris@0:     return $this;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets the active trail IDs used to set the inActiveTrail property.
Chris@0:    *
Chris@0:    * @param string[] $active_trail
Chris@0:    *   An array containing the active trail: a list of menu link plugin IDs.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Menu\MenuActiveTrail::getActiveTrailIds()
Chris@0:    *
Chris@0:    * @codeCoverageIgnore
Chris@0:    */
Chris@0:   public function setActiveTrail(array $active_trail) {
Chris@0:     $this->activeTrail = $active_trail;
Chris@0:     return $this;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Adds a custom query condition.
Chris@0:    *
Chris@0:    * @param string $definition_field
Chris@0:    *   Only conditions that are testing menu link definition fields are allowed.
Chris@0:    * @param mixed $value
Chris@0:    *   The value to test the link definition field against. In most cases, this
Chris@0:    *   is a scalar. For more complex options, it is an array. The meaning of
Chris@0:    *   each element in the array is dependent on the $operator.
Chris@0:    * @param string|null $operator
Chris@0:    *   (optional) The comparison operator, such as =, <, or >=. It also accepts
Chris@0:    *   more complex options such as IN, LIKE, or BETWEEN. If NULL, defaults to
Chris@0:    *   the = operator.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    */
Chris@0:   public function addCondition($definition_field, $value, $operator = NULL) {
Chris@0:     if (!isset($operator)) {
Chris@0:       $this->conditions[$definition_field] = $value;
Chris@0:     }
Chris@0:     else {
Chris@0:       $this->conditions[$definition_field] = [$value, $operator];
Chris@0:     }
Chris@0:     return $this;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Excludes links that are not enabled.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    */
Chris@0:   public function onlyEnabledLinks() {
Chris@0:     $this->addCondition('enabled', 1);
Chris@0:     return $this;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Ensures only the top level of the tree is loaded.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    */
Chris@0:   public function setTopLevelOnly() {
Chris@0:     $this->setMaxDepth(1);
Chris@0:     return $this;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Excludes the root menu link from the tree.
Chris@0:    *
Chris@0:    * Note that this is only necessary when you specified a custom root, because
Chris@0:    * the normal root ID is the empty string, '', which does not correspond to an
Chris@0:    * actual menu link. Hence when loading a menu link tree without specifying a
Chris@0:    * custom root the tree will start at the children even if this method has not
Chris@0:    * been called.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    */
Chris@0:   public function excludeRoot() {
Chris@0:     $this->setMinDepth(1);
Chris@0:     return $this;
Chris@0:   }
Chris@0: 
Chris@18:   /**
Chris@18:    * {@inheritdoc}
Chris@18:    */
Chris@18:   public function serialize() {
Chris@18:     // Enforce type consistency for all the internal properties of this object.
Chris@18:     $this->root = (string) $this->root;
Chris@18:     $this->minDepth = $this->minDepth !== NULL ? (int) $this->minDepth : NULL;
Chris@18:     $this->maxDepth = $this->maxDepth !== NULL ? (int) $this->maxDepth : NULL;
Chris@18:     $this->activeTrail = array_values(array_filter($this->activeTrail));
Chris@18: 
Chris@18:     // Sort 'expanded' and 'conditions' to prevent duplicate cache items.
Chris@18:     sort($this->expandedParents);
Chris@18:     asort($this->conditions);
Chris@18: 
Chris@18:     return serialize([
Chris@18:       'root' => $this->root,
Chris@18:       'minDepth' => $this->minDepth,
Chris@18:       'maxDepth' => $this->maxDepth,
Chris@18:       'expandedParents' => $this->expandedParents,
Chris@18:       'activeTrail' => $this->activeTrail,
Chris@18:       'conditions' => $this->conditions,
Chris@18:     ]);
Chris@18:   }
Chris@18: 
Chris@18:   /**
Chris@18:    * {@inheritdoc}
Chris@18:    */
Chris@18:   public function unserialize($serialized) {
Chris@18:     foreach (unserialize($serialized) as $key => $value) {
Chris@18:       $this->{$key} = $value;
Chris@18:     }
Chris@18: 
Chris@18:     return $this;
Chris@18:   }
Chris@18: 
Chris@0: }