You are here

Home » API reference » Drupal 9 » FieldItemListInterface.php

interface FieldItemListInterface in Drupal 9

Same name and namespace in other branches
  1. 8 core/lib/Drupal/Core/Field/FieldItemListInterface.php \Drupal\Core\Field\FieldItemListInterface

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

Expanded class hierarchy of FieldItemListInterface

All classes that implement FieldItemListInterface

See also

\Drupal\Core\Field\FieldItemInterface

157 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
View source 
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

Namesort descending 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