interface FieldItemListInterface in Drupal 8

Interface for fields, being lists of field items.

This interface must be implemented by every entity field, whereas contained field items must implement the FieldItemInterface. Some methods of the fields are delegated to the first contained item, in particular get() and set() as well as their magic equivalences.

Optionally, a typed data object implementing Drupal\Core\TypedData\TypedDataInterface may be passed to ArrayAccess::offsetSet() instead of a plain value.

When implementing this interface which extends Traversable, make sure to list IteratorAggregate or Iterator before this interface in the implements clause.

Hierarchy

• interface \Drupal\Core\TypedData\ListInterface extends \Drupal\Core\TypedData\ArrayAccess \Drupal\Core\TypedData\Countable; interface \Drupal\Core\Access\AccessibleInterface
  • interface \Drupal\Core\Field\FieldItemListInterface

See also

\Drupal\Core\Field\FieldItemInterface

158 files declare their use of FieldItemListInterface

AggregatorTitleFormatter.php in core/modules/aggregator/src/Plugin/Field/FieldFormatter/AggregatorTitleFormatter.php

AggregatorXSSFormatter.php in core/modules/aggregator/src/Plugin/Field/FieldFormatter/AggregatorXSSFormatter.php

AttachmentTestFormatter.php in core/modules/views/tests/modules/views_test_formatter/src/Plugin/Field/FieldFormatter/AttachmentTestFormatter.php

AuthorFormatter.php in core/modules/user/src/Plugin/Field/FieldFormatter/AuthorFormatter.php

AuthorNameFormatter.php in core/modules/comment/src/Plugin/Field/FieldFormatter/AuthorNameFormatter.php

... See full list

File

core/lib/Drupal/Core/Field/FieldItemListInterface.php, line 28

Namespace

Drupal\Core\Field

interface FieldItemListInterface extends ListInterface, AccessibleInterface {

  /**
   * Gets the entity that field belongs to.
   *
   * @return \Drupal\Core\Entity\FieldableEntityInterface
   *   The entity object. If the entity is translatable and a specific
   *   translation is required, always request it by calling ::getTranslation()
   *   or ::getUntranslated() as the language of the returned object is not
   *   defined.
   */
  public function getEntity();

  /**
   * Sets the langcode of the field values held in the object.
   *
   * @param string $langcode
   *   The langcode.
   */
  public function setLangcode($langcode);

  /**
   * Gets the langcode of the field values held in the object.
   *
   * @return string
   *   The langcode.
   */
  public function getLangcode();

  /**
   * Gets the field definition.
   *
   * @return \Drupal\Core\Field\FieldDefinitionInterface
   *   The field definition.
   */
  public function getFieldDefinition();

  /**
   * Returns the array of field settings.
   *
   * @return array
   *   An array of key/value pairs.
   */
  public function getSettings();

  /**
   * Returns the value of a given field setting.
   *
   * @param string $setting_name
   *   The setting name.
   *
   * @return mixed
   *   The setting value.
   */
  public function getSetting($setting_name);

  /**
   * Contains the default access logic of this field.
   *
   * See \Drupal\Core\Entity\EntityAccessControlHandlerInterface::fieldAccess() for
   * the parameter documentation.
   *
   * @return \Drupal\Core\Access\AccessResultInterface
   *   The access result.
   */
  public function defaultAccess($operation = 'view', AccountInterface $account = NULL);

  /**
   * Filters out empty field items and re-numbers the item deltas.
   *
   * @return $this
   */
  public function filterEmptyItems();

  /**
   * Magic method: Gets a property value of to the first field item.
   *
   * @see \Drupal\Core\Field\FieldItemInterface::__set()
   */
  public function __get($property_name);

  /**
   * Magic method: Sets a property value of the first field item.
   *
   * @see \Drupal\Core\Field\FieldItemInterface::__get()
   */
  public function __set($property_name, $value);

  /**
   * Magic method: Determines whether a property of the first field item is set.
   *
   * @see \Drupal\Core\Field\FieldItemInterface::__unset()
   */
  public function __isset($property_name);

  /**
   * Magic method: Unsets a property of the first field item.
   *
   * @see \Drupal\Core\Field\FieldItemInterface::__isset()
   */
  public function __unset($property_name);

  /**
   * Defines custom presave behavior for field values.
   *
   * This method is called during the process of saving an entity, just before
   * item values are written into storage.
   *
   * @see \Drupal\Core\Field\FieldItemInterface::preSave()
   */
  public function preSave();

  /**
   * Defines custom post-save behavior for field values.
   *
   * This method is called during the process of saving an entity, just after
   * item values are written into storage.
   *
   * @param bool $update
   *   Specifies whether the entity is being updated or created.
   *
   * @return bool
   *   Whether field items should be rewritten to the storage as a consequence
   *   of the logic implemented by the custom behavior.
   *
   * @see \Drupal\Core\Field\FieldItemInterface::postSave()
   */
  public function postSave($update);

  /**
   * Defines custom delete behavior for field values.
   *
   * This method is called during the process of deleting an entity, just before
   * values are deleted from storage.
   */
  public function delete();

  /**
   * Defines custom revision delete behavior for field values.
   *
   * This method is called from during the process of deleting an entity
   * revision, just before the field values are deleted from storage. It is only
   * called for entity types that support revisioning.
   */
  public function deleteRevision();

  /**
   * Returns a renderable array for the field items.
   *
   * @param string|array $display_options
   *   Can be either the name of a view mode, or an array of display settings.
   *   See EntityViewBuilderInterface::viewField() for more information.
   *
   * @return array
   *   A renderable array for the field values.
   *
   * @see \Drupal\Core\Entity\EntityViewBuilderInterface::viewField()
   * @see \Drupal\Core\Field\FieldItemInterface::view()
   */
  public function view($display_options = []);

  /**
   * Populates a specified number of field items with valid sample data.
   *
   * @param int $count
   *   The number of items to create.
   */
  public function generateSampleItems($count = 1);

  /**
   * Returns a form for the default value input.
   *
   * Invoked from \Drupal\field_ui\Form\FieldConfigEditForm to allow
   * administrators to configure instance-level default value.
   *
   * @param array $form
   *   The form where the settings form is being included in.
   * @param \Drupal\Core\Form\FormStateInterface $form_state
   *   The form state of the (entire) configuration form.
   *
   * @return array
   *   The form definition for the field default value.
   */
  public function defaultValuesForm(array &$form, FormStateInterface $form_state);

  /**
   * Validates the submitted default value.
   *
   * Invoked from \Drupal\field_ui\Form\FieldConfigEditForm to allow
   * administrators to configure instance-level default value.
   *
   * @param array $element
   *   The default value form element.
   * @param array $form
   *   The form where the settings form is being included in.
   * @param \Drupal\Core\Form\FormStateInterface $form_state
   *   The form state of the (entire) configuration form.
   */
  public function defaultValuesFormValidate(array $element, array &$form, FormStateInterface $form_state);

  /**
   * Processes the submitted default value.
   *
   * Invoked from \Drupal\field_ui\Form\FieldConfigEditForm to allow
   * administrators to configure instance-level default value.
   *
   * @param array $element
   *   The default value form element.
   * @param array $form
   *   The form where the settings form is being included in.
   * @param \Drupal\Core\Form\FormStateInterface $form_state
   *   The form state of the (entire) configuration form.
   *
   * @return array
   *   The field default value.
   */
  public function defaultValuesFormSubmit(array $element, array &$form, FormStateInterface $form_state);

  /**
   * Processes the default value before being applied.
   *
   * Defined or configured default values of a field might need some processing
   * in order to be a valid runtime value for the field type; e.g., a date field
   * could process the defined value of 'NOW' to a valid date.
   *
   * @param array $default_value
   *   The unprocessed default value defined for the field, as a numerically
   *   indexed array of items, each item being an array of property/value pairs.
   * @param \Drupal\Core\Entity\FieldableEntityInterface $entity
   *   The entity for which the default value is generated.
   * @param \Drupal\Core\Field\FieldDefinitionInterface $definition
   *   The definition of the field.
   *
   * @return array
   *   The return default value for the field.
   */
  public static function processDefaultValue($default_value, FieldableEntityInterface $entity, FieldDefinitionInterface $definition);

  /**
   * Determines equality to another object implementing FieldItemListInterface.
   *
   * This method is usually used by the storage to check for not computed
   * value changes, which will be saved into the storage.
   *
   * @param \Drupal\Core\Field\FieldItemListInterface $list_to_compare
   *   The field item list to compare to.
   *
   * @return bool
   *   TRUE if the field item lists are equal, FALSE if not.
   */
  public function equals(FieldItemListInterface $list_to_compare);

  /**
   * Determines whether the field has relevant changes.
   *
   * This is for example used to determine if a revision of an entity has
   * changes in a given translation. Unlike
   * \Drupal\Core\Field\FieldItemListInterface::equals(), this can report
   * that for example an untranslatable field, despite being changed and
   * therefore technically affecting all translations, is only internal metadata
   * or only affects a single translation.
   *
   * @param \Drupal\Core\Field\FieldItemListInterface $original_items
   *   The original field items to compare against.
   * @param string $langcode
   *   The language that should be checked.
   *
   * @return bool
   *   TRUE if the field has relevant changes, FALSE if not.
   */
  public function hasAffectingChanges(FieldItemListInterface $original_items, $langcode);

}

Members

Name	Modifiers	Type	Description	Overrides
AccessibleInterface::access	public	function	Checks data value access.	9
FieldItemListInterface::defaultAccess	public	function	Contains the default access logic of this field.	1
FieldItemListInterface::defaultValuesForm	public	function	Returns a form for the default value input.	1
FieldItemListInterface::defaultValuesFormSubmit	public	function	Processes the submitted default value.	1
FieldItemListInterface::defaultValuesFormValidate	public	function	Validates the submitted default value.	1
FieldItemListInterface::delete	public	function	Defines custom delete behavior for field values.	1
FieldItemListInterface::deleteRevision	public	function	Defines custom revision delete behavior for field values.	1
FieldItemListInterface::equals	public	function	Determines equality to another object implementing FieldItemListInterface.	1
FieldItemListInterface::filterEmptyItems	public	function	Filters out empty field items and re-numbers the item deltas.	1
FieldItemListInterface::generateSampleItems	public	function	Populates a specified number of field items with valid sample data.	1
FieldItemListInterface::getEntity	public	function	Gets the entity that field belongs to.	1
FieldItemListInterface::getFieldDefinition	public	function	Gets the field definition.	1
FieldItemListInterface::getLangcode	public	function	Gets the langcode of the field values held in the object.	1
FieldItemListInterface::getSetting	public	function	Returns the value of a given field setting.	1
FieldItemListInterface::getSettings	public	function	Returns the array of field settings.	1
FieldItemListInterface::hasAffectingChanges	public	function	Determines whether the field has relevant changes.	1
FieldItemListInterface::postSave	public	function	Defines custom post-save behavior for field values.	1
FieldItemListInterface::preSave	public	function	Defines custom presave behavior for field values.	1
FieldItemListInterface::processDefaultValue	public static	function	Processes the default value before being applied.	1
FieldItemListInterface::setLangcode	public	function	Sets the langcode of the field values held in the object.	1
FieldItemListInterface::view	public	function	Returns a renderable array for the field items.	1
FieldItemListInterface::__get	public	function	Magic method: Gets a property value of to the first field item.	1
FieldItemListInterface::__isset	public	function	Magic method: Determines whether a property of the first field item is set.	1
FieldItemListInterface::__set	public	function	Magic method: Sets a property value of the first field item.	1
FieldItemListInterface::__unset	public	function	Magic method: Unsets a property of the first field item.	1
ListInterface::appendItem	public	function	Appends a new item to the list.	1
ListInterface::filter	public	function	Filters the items in the list using a custom callback.	1
ListInterface::first	public	function	Returns the first item in this list.	1
ListInterface::get	public	function	Returns the item at the specified position in this list.	1
ListInterface::getDataDefinition	public	function	Gets the data definition. Overrides TypedDataInterface::getDataDefinition
ListInterface::getItemDefinition	public	function	Gets the definition of a contained item.	1
ListInterface::isEmpty	public	function	Determines whether the list contains any non-empty items.	1
ListInterface::removeItem	public	function	Removes the item at the specified position.	1
ListInterface::set	public	function	Sets the value of the item at a given position in the list.	1
TraversableTypedDataInterface::onChange	public	function	React to changes to a child property or item.	4
TypedDataInterface::applyDefaultValue	public	function	Applies the default value.	1
TypedDataInterface::createInstance	public static	function	Constructs a TypedData object given its definition and context.	1
TypedDataInterface::getConstraints	public	function	Gets a list of validation constraints.	1
TypedDataInterface::getName	public	function	Returns the name of a property or item.	1
TypedDataInterface::getParent	public	function	Returns the parent data structure; i.e. either complex data or a list.	1
TypedDataInterface::getPropertyPath	public	function	Returns the property path of the data.	1
TypedDataInterface::getRoot	public	function	Returns the root of the typed data tree.	1
TypedDataInterface::getString	public	function	Returns a string representation of the data.	1
TypedDataInterface::getValue	public	function	Gets the data value.	1
TypedDataInterface::setContext	public	function	Sets the context of a property or item via a context aware parent.	1
TypedDataInterface::setValue	public	function	Sets the data value.	1
TypedDataInterface::validate	public	function	Validates the currently set data value.	1