1. class
  2. Drupal
  3. \
  4. Core
  5. \
  6. Field
  7. \
  8. FieldItemList

FieldItemList

class FieldItemList extends ItemList implements FieldItemListInterface (View source)

Represents an entity field; that is, a list of field item objects.

An entity field is a list of field items, each containing a set of properties. Note that even single-valued entity fields are represented as list of field items, however for easy access to the contained item the entity field delegates get() and set() calls directly to the first item.

Traits

DependencySerializationTrait

Provides dependency injection friendly methods for serialization.

StringTranslationTrait

Wrapper methods for \Drupal\Core\StringTranslation\TranslationInterface.

TypedDataTrait

Wrapper methods for classes that needs typed data manager object.

Properties

protected array $_serviceIds

An array of service IDs keyed by property name used for serialization.

 from  DependencySerializationTrait
protected array $_entityStorages

An array of entity type IDs keyed by the property name of their storages.

 from  DependencySerializationTrait
protected TranslationInterface $stringTranslation

The string translation service.

 from  StringTranslationTrait
protected TypedDataManagerInterface $typedDataManager

The typed data manager used for creating the data types.

 from  TypedDataTrait
protected DataDefinitionInterface $definition

The data definition.

 from  TypedData
protected string $name

The property name.

 from  TypedData
protected TraversableTypedDataInterface|null $parent

The parent typed data object.

 from  TypedData
protected FieldItemInterface[] $list

Numerically indexed array of field items.
protected string $langcode

The langcode of the field values held in the object.

Methods

__sleep()

{@inheritdoc}

from  DependencySerializationTrait
__wakeup()

{@inheritdoc}

from  DependencySerializationTrait
TranslatableMarkup
t(string $string, array $args = [], array $options = [])

Translates a string to the current language or to a given language.

from  StringTranslationTrait
formatPlural($count, $singular, $plural, array $args = [], array $options = [])

Formats a string containing a count of items.

from  StringTranslationTrait
getNumberOfPlurals($langcode = NULL)

Returns the number of plurals supported by a given language.

from  StringTranslationTrait
TranslationInterface
getStringTranslation()

Gets the string translation service.

from  StringTranslationTrait
$this
setStringTranslation(TranslationInterface $translation)

Sets the string translation service to use.

from  StringTranslationTrait
$this
setTypedDataManager(TypedDataManagerInterface $typed_data_manager)

Sets the typed data manager.

from  TypedDataTrait
TypedDataManagerInterface
getTypedDataManager()

Gets the typed data manager.

from  TypedDataTrait
static 
createInstance(DataDefinitionInterface $definition, string|null $name = NULL, TraversableTypedDataInterface $parent = NULL)

Constructs a TypedData object given its definition and context.

from  TypedData
__construct(DataDefinitionInterface $definition, string $name = NULL, TypedDataInterface $parent = NULL)

Constructs a TypedData object given its definition and context.

from  TypedData
string
getPluginId()

Gets the plugin_id of the plugin instance.

from  TypedData
array
getPluginDefinition()

Gets the definition of the plugin implementation.

from  TypedData
DataDefinitionInterface
getDataDefinition()

Gets the data definition.

from  TypedData
mixed
getValue()

Gets the data value.

from  ItemList
setValue(array|null $values, bool $notify = TRUE)

Overrides \Drupal\Core\TypedData\TypedData::setValue().

string
getString()

Returns a string representation of the data.

from  ItemList
array
getConstraints()

Gets a list of validation constraints.

ConstraintViolationListInterface
validate()

Validates the currently set data value.

from  TypedData
$this
applyDefaultValue(bool $notify = TRUE)

Applies the default value.

setContext(string|null $name = NULL, TraversableTypedDataInterface $parent = NULL)

Sets the context of a property or item via a context aware parent.

from  TypedData
string|int|null
getName()

Returns the name of a property or item.

from  TypedData
TraversableTypedDataInterface
getRoot()

Returns the root of the typed data tree.

from  TypedData
string
getPropertyPath()

Returns the property path of the data.

from  TypedData
TraversableTypedDataInterface|null
getParent()

Returns the parent data structure; i.e. either complex data or a list.

from  TypedData
TypedDataInterface|null
get(int $index)

Returns the item at the specified position in this list.

from  ItemList
$this
set(int $index, mixed $value)

Sets the value of the item at a given position in the list.

from  ItemList
$this
removeItem(int $index)

Removes the item at the specified position.

from  ItemList
rekey(int $from_index = 0)

Renumbers the items in the list.

from  ItemList
TypedDataInterface|null
first()

Returns the first item in this list.

from  ItemList
offsetExists($offset)

{@inheritdoc}

from  ItemList
offsetUnset($offset)

{@inheritdoc}

from  ItemList
offsetGet($offset)

{@inheritdoc}

from  ItemList
offsetSet($offset, $value)

{@inheritdoc}

from  ItemList
TypedDataInterface
appendItem(mixed $value = NULL)

Appends a new item to the list.

from  ItemList
TypedDataInterface
createItem($offset = 0, $value = NULL)

Helper for creating a list item object.

DataDefinitionInterface
getItemDefinition()

Gets the definition of a contained item.

from  ItemList
getIterator()

{@inheritdoc}

from  ItemList
count()

{@inheritdoc}

from  ItemList
bool
isEmpty()

Determines whether the list contains any non-empty items.

from  ItemList
$this
filter(callable $callback)

Filters the items in the list using a custom callback.

from  ItemList
onChange($delta)

React to changes to a child property or item.

from  ItemList
__clone()

Magic method: Implements a deep clone.

from  ItemList
FieldableEntityInterface
getEntity()

Gets the entity that field belongs to.

setLangcode(string $langcode)

Sets the langcode of the field values held in the object.

string
getLangcode()

Gets the langcode of the field values held in the object.

FieldDefinitionInterface
getFieldDefinition()

Gets the field definition.

array
getSettings()

Returns the array of field settings.

mixed
getSetting(string $setting_name)

Returns the value of a given field setting.

$this
filterEmptyItems()

Filters out empty field items and re-numbers the item deltas.

__get($property_name)

Magic method: Gets a property value of to the first field item.

__set($property_name, $value)

Magic method: Sets a property value of the first field item.

__isset($property_name)

Magic method: Determines whether a property of the first field item is set.

__unset($property_name)

Magic method: Unsets a property of the first field item.

bool|AccessResultInterface
access(string $operation = 'view', AccountInterface $account = NULL, bool $return_as_object = FALSE)

Checks data value access.

AccessResultInterface
defaultAccess($operation = 'view', AccountInterface $account = NULL)

Contains the default access logic of this field.

preSave()

Defines custom presave behavior for field values.

bool
postSave(bool $update)

Defines custom post-save behavior for field values.

delete()

Defines custom delete behavior for field values.

deleteRevision()

Defines custom revision delete behavior for field values.

array
delegateMethod(string $method)

Calls a method on each FieldItem.

array
view(string|array $display_options = [])

Returns a renderable array for the field items.

generateSampleItems(int $count = 1)

Populates a specified number of field items with valid sample data.

array
defaultValuesForm(array $form, FormStateInterface $form_state)

Returns a form for the default value input.

defaultValuesFormValidate(array $element, array $form, FormStateInterface $form_state)

Validates the submitted default value.

array
defaultValuesFormSubmit(array $element, array $form, FormStateInterface $form_state)

Processes the submitted default value.

static array
processDefaultValue(array $default_value, FieldableEntityInterface $entity, FieldDefinitionInterface $definition)

Processes the default value before being applied.

WidgetInterface|null
defaultValueWidget(FormStateInterface $form_state)

Returns the widget object used in default value form.

bool
equals(FieldItemListInterface $list_to_compare)

Determines equality to another object implementing FieldItemListInterface.

bool
hasAffectingChanges(FieldItemListInterface $original_items, string $langcode)

Determines whether the field has relevant changes.

Details

in DependencySerializationTrait at line 32
__sleep()

{@inheritdoc}

in DependencySerializationTrait at line 67
__wakeup()

{@inheritdoc}

in StringTranslationTrait at line 70
protected TranslatableMarkup t(string $string, array $args = [], array $options = [])

Translates a string to the current language or to a given language.

See \Drupal\Core\StringTranslation\TranslatableMarkup::__construct() for important security information and usage guidelines.

In order for strings to be localized, make them available in one of the ways supported by the

Parameters

string $string

A string containing the English text to translate.
array $args

(optional) An associative array of replacements to make after translation. Based on the first character of the key, the value is escaped and/or themed. See \Drupal\Component\Render\FormattableMarkup::placeholderFormat() for details.
array $options

(optional) An associative array of additional options, with the following elements:

  • 'langcode' (defaults to the current language): A language code, to translate to a language other than what is used to display the page.
  • 'context' (defaults to the empty context): The context the source string belongs to. See the @link i18n Internationalization topic @endlink for more information about string contexts.

Return Value

TranslatableMarkup

An object that, when cast to a string, returns the translated string.

See also

FormattableMarkup::placeholderFormat
TranslatableMarkup::__construct

in StringTranslationTrait at line 79
protected formatPlural($count, $singular, $plural, array $args = [], array $options = [])

Formats a string containing a count of items.

Parameters

$count
$singular
$plural
array $args
array $options

See also

TranslationInterface::formatPlural

in StringTranslationTrait at line 88
protected getNumberOfPlurals($langcode = NULL)

Returns the number of plurals supported by a given language.

Parameters

$langcode

See also

PluralFormulaInterface::getNumberOfPlurals

in StringTranslationTrait at line 102
protected TranslationInterface getStringTranslation()

Gets the string translation service.

Return Value

TranslationInterface

The string translation service.

in StringTranslationTrait at line 118
$this setStringTranslation(TranslationInterface $translation)

Sets the string translation service to use.

Parameters

TranslationInterface $translation

The string translation service.

Return Value

$this

in TypedDataTrait at line 25
$this setTypedDataManager(TypedDataManagerInterface $typed_data_manager)

Sets the typed data manager.

Parameters

TypedDataManagerInterface $typed_data_manager

The typed data manager.

Return Value

$this

in TypedDataTrait at line 36
TypedDataManagerInterface getTypedDataManager()

Gets the typed data manager.

Return Value

TypedDataManagerInterface

The typed data manager.

in TypedData at line 46
static createInstance(DataDefinitionInterface $definition, string|null $name = NULL, TraversableTypedDataInterface $parent = NULL)

Constructs a TypedData object given its definition and context.

Parameters

DataDefinitionInterface $definition

The data definition.
string|null $name

(optional) The name of the created property, or NULL if it is the root of a typed data tree. Defaults to NULL.
TraversableTypedDataInterface $parent

(optional) The parent object of the data property, or NULL if it is the root of a typed data tree. Defaults to NULL.

in TypedData at line 64
__construct(DataDefinitionInterface $definition, string $name = NULL, TypedDataInterface $parent = NULL)

Constructs a TypedData object given its definition and context.

Parameters

DataDefinitionInterface $definition

The data definition.
string $name

(optional) The name of the created property, or NULL if it is the root of a typed data tree. Defaults to NULL.
TypedDataInterface $parent

(optional) The parent object of the data property, or NULL if it is the root of a typed data tree. Defaults to NULL.

See also

TypedDataManager::create

in TypedData at line 73
string getPluginId()

Gets the plugin_id of the plugin instance.

Return Value

string

The plugin_id of the plugin instance.

in TypedData at line 80
array getPluginDefinition()

Gets the definition of the plugin implementation.

Return Value

array

The plugin definition, as returned by the discovery object used by the plugin manager.

in TypedData at line 87
DataDefinitionInterface getDataDefinition()

Gets the data definition.

Return Value

DataDefinitionInterface

The data definition object.

in ItemList at line 38
mixed getValue()

Gets the data value.

Return Value

mixed

The data value.

at line 101
setValue(array|null $values, bool $notify = TRUE)

Overrides \Drupal\Core\TypedData\TypedData::setValue().

Parameters

array|null $values

An array of values of the field items, or NULL to unset the field.
bool $notify

(optional) Whether to notify the parent object of the change. Defaults to TRUE. If a property is updated from a parent object, set it to FALSE to avoid being notified again.

in ItemList at line 87
string getString()

Returns a string representation of the data.

Return Value

string

The string representation of the data.

at line 261
array getConstraints()

Gets a list of validation constraints.

Return Value

array

Array of constraints, each being an instance of \Symfony\Component\Validator\Constraint.

in TypedData at line 131
ConstraintViolationListInterface validate()

Validates the currently set data value.

Return Value

ConstraintViolationListInterface

A list of constraint violations. If the list is empty, validation succeeded.

at line 168
$this applyDefaultValue(bool $notify = TRUE)

Applies the default value.

Parameters

bool $notify

(optional) Whether to notify the parent object of the change. Defaults to TRUE. If a property is updated from a parent object, set it to FALSE to avoid being notified again.

Return Value

$this

Returns itself to allow for chaining.

in TypedData at line 147
setContext(string|null $name = NULL, TraversableTypedDataInterface $parent = NULL)

Sets the context of a property or item via a context aware parent.

This method is supposed to be called by the factory only.

Parameters

string|null $name

(optional) The name of the property or the delta of the list item, or NULL if it is the root of a typed data tree. Defaults to NULL.
TraversableTypedDataInterface $parent

(optional) The parent object of the data property, or NULL if it is the root of a typed data tree. Defaults to NULL.

in TypedData at line 155
string|int|null getName()

Returns the name of a property or item.

Return Value

string|int|null

If the data is a property of some complex data, the name of the property. If the data is an item of a list, the name is the numeric position of the item in the list, starting with 0. Otherwise, NULL is returned.

in TypedData at line 162
TraversableTypedDataInterface getRoot()

Returns the root of the typed data tree.

Returns the root data for a tree of typed data objects; e.g. for an entity field item the root of the tree is its parent entity object.

Return Value

TraversableTypedDataInterface

The root data structure, either complex data or a list.

in TypedData at line 173
string getPropertyPath()

Returns the property path of the data.

The trail of property names relative to the root of the typed data tree, separated by dots; e.g. 'field_text.0.format'.

Return Value

string

The property path relative to the root of the typed tree, or an empty string if this is the root.

in TypedData at line 191
TraversableTypedDataInterface|null getParent()

Returns the parent data structure; i.e. either complex data or a list.

Return Value

TraversableTypedDataInterface|null

The parent data structure, either complex data or a list; or NULL if this is the root of the typed data tree.

in ItemList at line 99
TypedDataInterface|null get(int $index)

Returns the item at the specified position in this list.

Parameters

int $index

Index of the item to return.

Return Value

TypedDataInterface|null

The item at the specified position in this list, or NULL if no item exists at that position.

Exceptions

MissingDataException

in ItemList at line 109
$this set(int $index, mixed $value)

Sets the value of the item at a given position in the list.

Parameters

int $index

The position of the item in the list. Since a List only contains sequential, 0-based indexes, $index has to be:

  • Either the position of an existing item in the list. This updates the item value.
  • Or the next available position in the sequence of the current list indexes. This appends a new item with the provided value at the end of the list.
mixed $value

The value of the item to be stored at the specified position.

Return Value

$this

Exceptions

InvalidArgumentException
MissingDataException

in ItemList at line 131
$this removeItem(int $index)

Removes the item at the specified position.

Parameters

int $index

Index of the item to remove.

Return Value

$this

in ItemList at line 151
protected rekey(int $from_index = 0)

Renumbers the items in the list.

Parameters

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).

in ItemList at line 164
TypedDataInterface|null first()

Returns the first item in this list.

Return Value

TypedDataInterface|null

The first item in this list, or NULL if there are no items.

Exceptions

MissingDataException

in ItemList at line 171
offsetExists($offset)

{@inheritdoc}

Parameters

$offset

in ItemList at line 180
offsetUnset($offset)

{@inheritdoc}

Parameters

$offset

in ItemList at line 188
offsetGet($offset)

{@inheritdoc}

Parameters

$offset

in ItemList at line 196
offsetSet($offset, $value)

{@inheritdoc}

Parameters

$offset
$value

in ItemList at line 210
TypedDataInterface appendItem(mixed $value = NULL)

Appends a new item to the list.

Parameters

mixed $value

The value of the new item.

Return Value

TypedDataInterface

The item that was appended.

at line 40
protected TypedDataInterface createItem($offset = 0, $value = NULL)

Helper for creating a list item object.

Parameters

$offset
$value

Return Value

TypedDataInterface

in ItemList at line 229
DataDefinitionInterface getItemDefinition()

Gets the definition of a contained item.

Return Value

DataDefinitionInterface

The data definition of contained items.

in ItemList at line 236
getIterator()

{@inheritdoc}

in ItemList at line 244
count()

{@inheritdoc}

in ItemList at line 252
bool isEmpty()

Determines whether the list contains any non-empty items.

Return Value

bool

TRUE if the list is empty, FALSE otherwise.

in ItemList at line 270
$this filter(callable $callback)

Filters the items in the list using a custom callback.

Parameters

callable $callback

The callback to use for filtering. Like with array_filter(), the callback is called for each item in the list. Only items for which the callback returns TRUE are preserved.

Return Value

$this

in ItemList at line 292
onChange($delta)

React to changes to a child property or item.

Note that this is invoked after any changes have been applied.

Parameters

$delta

in ItemList at line 302
__clone()

Magic method: Implements a deep clone.

at line 47
FieldableEntityInterface getEntity()

Gets the entity that field belongs to.

Return Value

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.

at line 56
setLangcode(string $langcode)

Sets the langcode of the field values held in the object.

Parameters

string $langcode

The langcode.

at line 63
string getLangcode()

Gets the langcode of the field values held in the object.

Return Value

string

The langcode.

at line 70
FieldDefinitionInterface getFieldDefinition()

Gets the field definition.

Return Value

FieldDefinitionInterface

The field definition.

at line 77
array getSettings()

Returns the array of field settings.

Return Value

array

An array of key/value pairs.

at line 84
mixed getSetting(string $setting_name)

Returns the value of a given field setting.

Parameters

string $setting_name

The setting name.

Return Value

mixed

The setting value.

at line 91
$this filterEmptyItems()

Filters out empty field items and re-numbers the item deltas.

Return Value

$this

at line 113
__get($property_name)

Magic method: Gets a property value of to the first field item.

Parameters

$property_name

at line 123
__set($property_name, $value)

Magic method: Sets a property value of the first field item.

Parameters

$property_name
$value

at line 133
__isset($property_name)

Magic method: Determines whether a property of the first field item is set.

Parameters

$property_name

at line 143
__unset($property_name)

Magic method: Unsets a property of the first field item.

Parameters

$property_name

at line 152
bool|AccessResultInterface access(string $operation = 'view', AccountInterface $account = NULL, bool $return_as_object = FALSE)

Checks data value access.

Parameters

string $operation

The operation to be performed.
AccountInterface $account

(optional) The user for which to check access, or NULL to check access for the current user. Defaults to NULL.
bool $return_as_object

(optional) Defaults to FALSE.

Return Value

bool|AccessResultInterface

The access result. Returns a boolean if $return_as_object is FALSE (this is the default) and otherwise an AccessResultInterface object. When a boolean is returned, the result of AccessInterface::isAllowed() is returned, i.e. TRUE means access is explicitly allowed, FALSE means access is either explicitly forbidden or "no opinion".

at line 160
AccessResultInterface defaultAccess($operation = 'view', AccountInterface $account = NULL)

Contains the default access logic of this field.

See \Drupal\Core\Entity\EntityAccessControlHandlerInterface::fieldAccess() for the parameter documentation.

Parameters

$operation
AccountInterface $account

Return Value

AccessResultInterface

The access result.

at line 187
preSave()

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.

at line 197
bool postSave(bool $update)

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.

Parameters

bool $update

Specifies whether the entity is being updated or created.

Return Value

bool

Whether field items should be rewritten to the storage as a consequence of the logic implemented by the custom behavior.

at line 205
delete()

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.

at line 212
deleteRevision()

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.

at line 227
protected array delegateMethod(string $method)

Calls a method on each FieldItem.

Any argument passed will be forwarded to the invoked method.

Parameters

string $method

The name of the method to be invoked.

Return Value

array

An array of results keyed by delta.

at line 241
array view(string|array $display_options = [])

Returns a renderable array for the field items.

Parameters

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 Value

array

A renderable array for the field values.

at line 249
generateSampleItems(int $count = 1)

Populates a specified number of field items with valid sample data.

Parameters

int $count

The number of items to create.

at line 282
array defaultValuesForm(array $form, FormStateInterface $form_state)

Returns a form for the default value input.

Invoked from \Drupal\field_ui\Form\FieldConfigEditForm to allow administrators to configure instance-level default value.

Parameters

array $form

The form where the settings form is being included in.
FormStateInterface $form_state

The form state of the (entire) configuration form.

Return Value

array

The form definition for the field default value.

at line 300
defaultValuesFormValidate(array $element, 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.

Parameters

array $element

The default value form element.
array $form

The form where the settings form is being included in.
FormStateInterface $form_state

The form state of the (entire) configuration form.

at line 319
array defaultValuesFormSubmit(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.

Parameters

array $element

The default value form element.
array $form

The form where the settings form is being included in.
FormStateInterface $form_state

The form state of the (entire) configuration form.

Return Value

array

The field default value.

at line 331
static array processDefaultValue(array $default_value, FieldableEntityInterface $entity, FieldDefinitionInterface $definition)

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.

Parameters

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.
FieldableEntityInterface $entity

The entity for which the default value is generated.
FieldDefinitionInterface $definition

The definition of the field.

Return Value

array

The return default value for the field.

at line 344
protected WidgetInterface|null defaultValueWidget(FormStateInterface $form_state)

Returns the widget object used in default value form.

Parameters

FormStateInterface $form_state

The form state of the (entire) configuration form.

Return Value

WidgetInterface|null

A Widget object or NULL if no widget is available.

at line 371
bool equals(FieldItemListInterface $list_to_compare)

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.

Parameters

FieldItemListInterface $list_to_compare

The field item list to compare to.

Return Value

bool

TRUE if the field item lists are equal, FALSE if not.

at line 417
bool hasAffectingChanges(FieldItemListInterface $original_items, string $langcode)

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.

Parameters

FieldItemListInterface $original_items

The original field items to compare against.
string $langcode

The language that should be checked.

Return Value

bool

TRUE if the field has relevant changes, FALSE if not.