class ItemList in Drupal 9

Same name and namespace in other branches

8 core/lib/Drupal/Core/TypedData/Plugin/DataType/ItemList.php \Drupal\Core\TypedData\Plugin\DataType\ItemList

A generic list class.

This class can serve as list for any type of items and is used by default. Data types may specify the default list class in their definition, see Drupal\Core\TypedData\Annotation\DataType. Note: The class cannot be called "List" as list is a reserved PHP keyword.

Plugin annotation


@DataType(
  id = "list",
  label = @Translation("List of items"),
  definition_class = "\Drupal\Core\TypedData\ListDataDefinition"
)

Hierarchy

class \Drupal\Core\TypedData\TypedData implements PluginInspectionInterface, TypedDataInterface uses DependencySerializationTrait, StringTranslationTrait, TypedDataTrait
- class \Drupal\Core\TypedData\Plugin\DataType\ItemList implements \Drupal\Core\TypedData\Plugin\DataType\IteratorAggregate, ListInterface

Expanded class hierarchy of ItemList

File

core/lib/Drupal/Core/TypedData/Plugin/DataType/ItemList.php, line 26

Namespace

Drupal\Core\TypedData\Plugin\DataType

View source

class ItemList extends TypedData implements \IteratorAggregate, ListInterface {

  /**
   * Numerically indexed array of items.
   *
   * @var \Drupal\Core\TypedData\TypedDataInterface[]
   */
  protected $list = [];

  /**
   * {@inheritdoc}
   */
  public function getValue() {
    $values = [];
    foreach ($this->list as $delta => $item) {
      $values[$delta] = $item
        ->getValue();
    }
    return $values;
  }

  /**
   * Overrides \Drupal\Core\TypedData\TypedData::setValue().
   *
   * @param array|null $values
   *   An array of values of the field items, or NULL to unset the field.
   * @param bool $notify
   *   (optional) Whether to notify the parent object of the change. Defaults to
   *   TRUE.
   */
  public function setValue($values, $notify = TRUE) {
    if (!isset($values) || $values === []) {
      $this->list = [];
    }
    else {

      // Only arrays with numeric keys are supported.
      if (!is_array($values)) {
        throw new \InvalidArgumentException('Cannot set a list with a non-array value.');
      }

      // Assign incoming values. Keys are renumbered to ensure 0-based
      // sequential deltas. If possible, reuse existing items rather than
      // creating new ones.
      foreach (array_values($values) as $delta => $value) {
        if (!isset($this->list[$delta])) {
          $this->list[$delta] = $this
            ->createItem($delta, $value);
        }
        else {
          $this->list[$delta]
            ->setValue($value, FALSE);
        }
      }

      // Truncate extraneous pre-existing values.
      $this->list = array_slice($this->list, 0, count($values));
    }

    // Notify the parent of any changes.
    if ($notify && isset($this->parent)) {
      $this->parent
        ->onChange($this->name);
    }
  }

  /**
   * {@inheritdoc}
   */
  public function getString() {
    $strings = [];
    foreach ($this->list as $item) {
      $strings[] = $item
        ->getString();
    }

    // Remove any empty strings resulting from empty items.
    return implode(', ', array_filter($strings, 'mb_strlen'));
  }

  /**
   * {@inheritdoc}
   */
  public function get($index) {
    if (!is_numeric($index)) {
      throw new \InvalidArgumentException('Unable to get a value with a non-numeric delta in a list.');
    }
    return isset($this->list[$index]) ? $this->list[$index] : NULL;
  }

  /**
   * {@inheritdoc}
   */
  public function set($index, $value) {
    if (!is_numeric($index)) {
      throw new \InvalidArgumentException('Unable to set a value with a non-numeric delta in a list.');
    }

    // Ensure indexes stay sequential. We allow assigning an item at an existing
    // index, or at the next index available.
    if ($index < 0 || $index > count($this->list)) {
      throw new \InvalidArgumentException('Unable to set a value to a non-subsequent delta in a list.');
    }

    // Support setting values via typed data objects.
    if ($value instanceof TypedDataInterface) {
      $value = $value
        ->getValue();
    }

    // If needed, create the item at the next position.
    $item = isset($this->list[$index]) ? $this->list[$index] : $this
      ->appendItem();
    $item
      ->setValue($value);
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function removeItem($index) {
    if (isset($this->list) && array_key_exists($index, $this->list)) {

      // Remove the item, and reassign deltas.
      unset($this->list[$index]);
      $this
        ->rekey($index);
    }
    else {
      throw new \InvalidArgumentException('Unable to remove item at non-existing index.');
    }
    return $this;
  }

  /**
   * Renumbers the items in the list.
   *
   * @param int $from_index
   *   Optionally, the index at which to start the renumbering, if it is known
   *   that items before that can safely be skipped (for example, when removing
   *   an item at a given index).
   */
  protected function rekey($from_index = 0) {

    // Re-key the list to maintain consecutive indexes.
    $this->list = array_values($this->list);

    // Each item holds its own index as a "name", it needs to be updated
    // according to the new list indexes.
    for ($i = $from_index; $i < count($this->list); $i++) {
      $this->list[$i]
        ->setContext($i, $this);
    }
  }

  /**
   * {@inheritdoc}
   */
  public function first() {
    return $this
      ->get(0);
  }

  /**
   * {@inheritdoc}
   */
  public function offsetExists($offset) {

    // We do not want to throw exceptions here, so we do not use get().
    return isset($this->list[$offset]);
  }

  /**
   * {@inheritdoc}
   */
  public function offsetUnset($offset) {
    $this
      ->removeItem($offset);
  }

  /**
   * {@inheritdoc}
   */
  public function offsetGet($offset) {
    return $this
      ->get($offset);
  }

  /**
   * {@inheritdoc}
   */
  public function offsetSet($offset, $value) {
    if (!isset($offset)) {

      // The [] operator has been used.
      $this
        ->appendItem($value);
    }
    else {
      $this
        ->set($offset, $value);
    }
  }

  /**
   * {@inheritdoc}
   */
  public function appendItem($value = NULL) {
    $offset = count($this->list);
    $item = $this
      ->createItem($offset, $value);
    $this->list[$offset] = $item;
    return $item;
  }

  /**
   * Helper for creating a list item object.
   *
   * @return \Drupal\Core\TypedData\TypedDataInterface
   */
  protected function createItem($offset = 0, $value = NULL) {
    return $this
      ->getTypedDataManager()
      ->getPropertyInstance($this, $offset, $value);
  }

  /**
   * {@inheritdoc}
   */
  public function getItemDefinition() {
    return $this->definition
      ->getItemDefinition();
  }

  /**
   * {@inheritdoc}
   */
  public function getIterator() {
    return new \ArrayIterator($this->list);
  }

  /**
   * {@inheritdoc}
   */
  public function count() {
    return count($this->list);
  }

  /**
   * {@inheritdoc}
   */
  public function isEmpty() {
    foreach ($this->list as $item) {
      if ($item instanceof ComplexDataInterface || $item instanceof ListInterface) {
        if (!$item
          ->isEmpty()) {
          return FALSE;
        }
      }
      elseif ($item
        ->getValue() !== NULL) {
        return FALSE;
      }
    }
    return TRUE;
  }

  /**
   * {@inheritdoc}
   */
  public function filter($callback) {
    if (isset($this->list)) {
      $removed = FALSE;

      // Apply the filter, detecting if some items were actually removed.
      $this->list = array_filter($this->list, function ($item) use ($callback, &$removed) {
        if (call_user_func($callback, $item)) {
          return TRUE;
        }
        else {
          $removed = TRUE;
        }
      });
      if ($removed) {
        $this
          ->rekey();
      }
    }
    return $this;
  }

  /**
   * {@inheritdoc}
   */
  public function onChange($delta) {

    // Notify the parent of changes.
    if (isset($this->parent)) {
      $this->parent
        ->onChange($this->name);
    }
  }

  /**
   * Magic method: Implements a deep clone.
   */
  public function __clone() {
    foreach ($this->list as $delta => $item) {
      $this->list[$delta] = clone $item;
      $this->list[$delta]
        ->setContext($delta, $this);
    }
  }

}

Members

Name	Modifiers	Type	Description	Overrides
DependencySerializationTrait::$_entityStorages	protected	property
DependencySerializationTrait::$_serviceIds	protected	property
DependencySerializationTrait::__sleep	public	function		2
DependencySerializationTrait::__wakeup	public	function		2
ItemList::$list	protected	property	Numerically indexed array of items.	1
ItemList::appendItem	public	function	Appends a new item to the list. Overrides ListInterface::appendItem
ItemList::count	public	function
ItemList::createItem	protected	function	Helper for creating a list item object.	1
ItemList::filter	public	function	Filters the items in the list using a custom callback. Overrides ListInterface::filter
ItemList::first	public	function	Returns the first item in this list. Overrides ListInterface::first
ItemList::get	public	function	Returns the item at the specified position in this list. Overrides ListInterface::get	2
ItemList::getItemDefinition	public	function	Gets the definition of a contained item. Overrides ListInterface::getItemDefinition
ItemList::getIterator	public	function
ItemList::getString	public	function	Returns a string representation of the data. Overrides TypedData::getString
ItemList::getValue	public	function	Gets the data value. Overrides TypedData::getValue
ItemList::isEmpty	public	function	Determines whether the list contains any non-empty items. Overrides ListInterface::isEmpty
ItemList::offsetExists	public	function		1
ItemList::offsetGet	public	function
ItemList::offsetSet	public	function
ItemList::offsetUnset	public	function
ItemList::onChange	public	function	React to changes to a child property or item. Overrides TraversableTypedDataInterface::onChange	1
ItemList::rekey	protected	function	Renumbers the items in the list.
ItemList::removeItem	public	function	Removes the item at the specified position. Overrides ListInterface::removeItem
ItemList::set	public	function	Sets the value of the item at a given position in the list. Overrides ListInterface::set
ItemList::setValue	public	function	Overrides \Drupal\Core\TypedData\TypedData::setValue(). Overrides TypedData::setValue	1
ItemList::__clone	public	function	Magic method: Implements a deep clone.
StringTranslationTrait::$stringTranslation	protected	property	The string translation service.	4
StringTranslationTrait::formatPlural	protected	function	Formats a string containing a count of items.
StringTranslationTrait::getNumberOfPlurals	protected	function	Returns the number of plurals supported by a given language.
StringTranslationTrait::getStringTranslation	protected	function	Gets the string translation service.
StringTranslationTrait::setStringTranslation	public	function	Sets the string translation service to use.	2
StringTranslationTrait::t	protected	function	Translates a string to the current language or to a given language.
TypedData::$definition	protected	property	The data definition.	1
TypedData::$name	protected	property	The property name.
TypedData::$parent	protected	property	The parent typed data object.
TypedData::applyDefaultValue	public	function	Applies the default value. Overrides TypedDataInterface::applyDefaultValue	3
TypedData::createInstance	public static	function	Constructs a TypedData object given its definition and context. Overrides TypedDataInterface::createInstance
TypedData::getConstraints	public	function	Gets a list of validation constraints. Overrides TypedDataInterface::getConstraints	9
TypedData::getDataDefinition	public	function	Gets the data definition. Overrides TypedDataInterface::getDataDefinition
TypedData::getName	public	function	Returns the name of a property or item. Overrides TypedDataInterface::getName
TypedData::getParent	public	function	Returns the parent data structure; i.e. either complex data or a list. Overrides TypedDataInterface::getParent
TypedData::getPluginDefinition	public	function	Gets the definition of the plugin implementation. Overrides PluginInspectionInterface::getPluginDefinition
TypedData::getPluginId	public	function	Gets the plugin_id of the plugin instance. Overrides PluginInspectionInterface::getPluginId
TypedData::getPropertyPath	public	function	Returns the property path of the data. Overrides TypedDataInterface::getPropertyPath
TypedData::getRoot	public	function	Returns the root of the typed data tree. Overrides TypedDataInterface::getRoot
TypedData::setContext	public	function	Sets the context of a property or item via a context aware parent. Overrides TypedDataInterface::setContext
TypedData::validate	public	function	Validates the currently set data value. Overrides TypedDataInterface::validate
TypedData::__construct	public	function	Constructs a TypedData object given its definition and context.	3
TypedDataTrait::$typedDataManager	protected	property	The typed data manager used for creating the data types.
TypedDataTrait::getTypedDataManager	public	function	Gets the typed data manager.	2
TypedDataTrait::setTypedDataManager	public	function	Sets the typed data manager.	2

You are here