Drupal\Core\Field\FieldItemListInterface | Drupal Core API Explorer

interface FieldItemListInterface implements ListInterface, AccessibleInterface (View source)

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.

Methods

static

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

Constructs a TypedData object given its definition and context.

from TypedDataInterface

DataDefinitionInterface

getDataDefinition()

Gets the data definition.

from TypedDataInterface

mixed

getValue()

Gets the data value.

from TypedDataInterface

setValue(mixed|null $value, bool $notify = TRUE)

Sets the data value.

from TypedDataInterface

string

getString()

Returns a string representation of the data.

from TypedDataInterface

array

getConstraints()

Gets a list of validation constraints.

from TypedDataInterface

ConstraintViolationListInterface

validate()

Validates the currently set data value.

from TypedDataInterface

$this

applyDefaultValue(bool $notify = TRUE)

Applies the default value.

from TypedDataInterface

string|int|null

getName()

Returns the name of a property or item.

from TypedDataInterface

TraversableTypedDataInterface|null

getParent()

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

from TypedDataInterface

TraversableTypedDataInterface

getRoot()

Returns the root of the typed data tree.

from TypedDataInterface

string

getPropertyPath()

Returns the property path of the data.

from TypedDataInterface

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

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

from TypedDataInterface

onChange($name)

React to changes to a child property or item.

from TraversableTypedDataInterface

bool

isEmpty()

Determines whether the list contains any non-empty items.

from ListInterface

DataDefinitionInterface

getItemDefinition()

Gets the definition of a contained item.

from ListInterface

TypedDataInterface|null

get(int $index)

Returns the item at the specified position in this list.

from ListInterface

$this

set(int $index, mixed $value)

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

from ListInterface

TypedDataInterface|null

first()

Returns the first item in this list.

from ListInterface

TypedDataInterface

appendItem(mixed $value = NULL)

Appends a new item to the list.

from ListInterface

$this

removeItem(int $index)

Removes the item at the specified position.

from ListInterface

$this

filter(callable $callback)

Filters the items in the list using a custom callback.

from ListInterface

bool|AccessResultInterface

access(string $operation, AccountInterface $account = NULL, bool $return_as_object = FALSE)

Checks data value access.

from AccessibleInterface

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.

AccessResultInterface

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

Contains the default access logic of this field.

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

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

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.

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 TypedDataInterface at line 32
`static createInstance(DataDefinitionInterface $definition, string|null $name = NULL, TraversableTypedDataInterface $parent = NULL)`

Constructs a TypedData object given its definition and context.

When \Drupal\Core\Config\TypedConfigManager has been fixed to use class-based definitions, type-hint $definition to DataDefinitionInterface. https://www.drupal.org/node/1928868

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 TypedDataInterface at line 40
`DataDefinitionInterface getDataDefinition()`

Gets the data definition.

Return Value

DataDefinitionInterface

The data definition object.

in TypedDataInterface at line 48
`mixed getValue()`

Gets the data value.

Return Value

mixed

The data value.

in TypedDataInterface at line 66
`setValue(mixed|null $value, bool $notify = TRUE)`

Sets the data value.

Parameters

mixed\|null	$value	The value to set in the format as documented for the data type or NULL to unset the data value.
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.

Exceptions

InvalidArgumentException
ReadOnlyException

in TypedDataInterface at line 74
`string getString()`

Returns a string representation of the data.

Return Value

string

The string representation of the data.

in TypedDataInterface at line 83
`array getConstraints()`

Gets a list of validation constraints.

Return Value

array

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

in TypedDataInterface at line 92
`ConstraintViolationListInterface validate()`

Validates the currently set data value.

Return Value

ConstraintViolationListInterface

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

in TypedDataInterface at line 105
`$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 TypedDataInterface at line 115
`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 TypedDataInterface at line 124
`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 TypedDataInterface at line 135
`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 TypedDataInterface at line 147
`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 TypedDataInterface at line 161
`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 TraversableTypedDataInterface at line 18
`onChange($name)`

React to changes to a child property or item.

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

Parameters

$name

The name of the property or the delta of the list item which is changed.

in ListInterface at line 34
`bool isEmpty()`

Determines whether the list contains any non-empty items.

Return Value

bool	TRUE if the list is empty, FALSE otherwise.

in ListInterface at line 42
`DataDefinitionInterface getItemDefinition()`

Gets the definition of a contained item.

Return Value

DataDefinitionInterface

The data definition of contained items.

in ListInterface at line 57
`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 ListInterface at line 81
`$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 ListInterface at line 92
`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 ListInterface at line 103
`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.

in ListInterface at line 113
`$this removeItem(int $index)`

Removes the item at the specified position.

Parameters

int

$index

Index of the item to remove.

Return Value

$this

in ListInterface at line 125
`$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 AccessibleInterface at line 32
`bool|AccessResultInterface access(string $operation, 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 39
`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 47
`setLangcode(string $langcode)`

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

Parameters

string

$langcode

The langcode.

at line 55
`string getLangcode()`

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

Return Value

string

The langcode.

at line 63
`FieldDefinitionInterface getFieldDefinition()`

Gets the field definition.

Return Value

FieldDefinitionInterface

The field definition.

at line 71
`array getSettings()`

Returns the array of field settings.

Return Value

array

An array of key/value pairs.

at line 82
`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 93
`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 100
`$this filterEmptyItems()`

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

Return Value

$this

at line 107
`__get($property_name)`

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

Parameters

$property_name

at line 114
`__set($property_name, $value)`

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

Parameters

	$property_name
	$value

at line 121
`__isset($property_name)`

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

Parameters

$property_name

at line 128
`__unset($property_name)`

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

Parameters

$property_name

at line 138
`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 155
`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 163
`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 172
`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 187
`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 195
`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 211
`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 226
`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 244
`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 264
`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 278
`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 298
`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.

EntityViewBuilderInterface::viewField
FieldItemInterface::view

FieldItemListInterface

Methods

Details

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

Parameters

See also

in TypedDataInterface at line 40 DataDefinitionInterface getDataDefinition()

Return Value

in TypedDataInterface at line 48 mixed getValue()

Return Value

in TypedDataInterface at line 66 setValue(mixed|null $value, bool $notify = TRUE)

Parameters

Exceptions

in TypedDataInterface at line 74 string getString()

Return Value

in TypedDataInterface at line 83 array getConstraints()

Return Value

in TypedDataInterface at line 92 ConstraintViolationListInterface validate()

Return Value

in TypedDataInterface at line 105 $this applyDefaultValue(bool $notify = TRUE)

Parameters

Return Value

in TypedDataInterface at line 115 string|int|null getName()

Return Value

in TypedDataInterface at line 124 TraversableTypedDataInterface|null getParent()

Return Value

in TypedDataInterface at line 135 TraversableTypedDataInterface getRoot()

Return Value

in TypedDataInterface at line 147 string getPropertyPath()

Return Value

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

Parameters

in TraversableTypedDataInterface at line 18 onChange($name)

Parameters

in ListInterface at line 34 bool isEmpty()

Return Value

in ListInterface at line 42 DataDefinitionInterface getItemDefinition()

Return Value

in ListInterface at line 57 TypedDataInterface|null get(int $index)

Parameters

Return Value

Exceptions

in ListInterface at line 81 $this set(int $index, mixed $value)

Parameters

Return Value

Exceptions

in ListInterface at line 92 TypedDataInterface|null first()

Return Value

Exceptions

in ListInterface at line 103 TypedDataInterface appendItem(mixed $value = NULL)

Parameters

Return Value

in ListInterface at line 113 $this removeItem(int $index)

Parameters

Return Value

in ListInterface at line 125 $this filter(callable $callback)

Parameters

Return Value

in AccessibleInterface at line 32 bool|AccessResultInterface access(string $operation, AccountInterface $account = NULL, bool $return_as_object = FALSE)

Parameters

Return Value

at line 39 FieldableEntityInterface getEntity()

Return Value

at line 47 setLangcode(string $langcode)

Parameters

at line 55 string getLangcode()

Return Value

at line 63 FieldDefinitionInterface getFieldDefinition()

Return Value

at line 71 array getSettings()

Return Value

at line 82 mixed getSetting(string $setting_name)

Parameters

Return Value

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

Parameters

Return Value

at line 100 $this filterEmptyItems()

Return Value

at line 107 __get($property_name)

in TypedDataInterface at line 32
`static createInstance(DataDefinitionInterface $definition, string|null $name = NULL, TraversableTypedDataInterface $parent = NULL)`

in TypedDataInterface at line 40
`DataDefinitionInterface getDataDefinition()`

in TypedDataInterface at line 48
`mixed getValue()`

in TypedDataInterface at line 66
`setValue(mixed|null $value, bool $notify = TRUE)`

in TypedDataInterface at line 74
`string getString()`

in TypedDataInterface at line 83
`array getConstraints()`

in TypedDataInterface at line 92
`ConstraintViolationListInterface validate()`

in TypedDataInterface at line 105
`$this applyDefaultValue(bool $notify = TRUE)`

in TypedDataInterface at line 115
`string|int|null getName()`

in TypedDataInterface at line 124
`TraversableTypedDataInterface|null getParent()`

in TypedDataInterface at line 135
`TraversableTypedDataInterface getRoot()`

in TypedDataInterface at line 147
`string getPropertyPath()`

in TypedDataInterface at line 161
`setContext(string|null $name = NULL, TraversableTypedDataInterface $parent = NULL)`

in TraversableTypedDataInterface at line 18
`onChange($name)`

in ListInterface at line 34
`bool isEmpty()`

in ListInterface at line 42
`DataDefinitionInterface getItemDefinition()`

in ListInterface at line 57
`TypedDataInterface|null get(int $index)`

in ListInterface at line 81
`$this set(int $index, mixed $value)`

in ListInterface at line 92
`TypedDataInterface|null first()`

in ListInterface at line 103
`TypedDataInterface appendItem(mixed $value = NULL)`

in ListInterface at line 113
`$this removeItem(int $index)`

in ListInterface at line 125
`$this filter(callable $callback)`

in AccessibleInterface at line 32
`bool|AccessResultInterface access(string $operation, AccountInterface $account = NULL, bool $return_as_object = FALSE)`

at line 39
`FieldableEntityInterface getEntity()`

at line 47
`setLangcode(string $langcode)`

at line 55
`string getLangcode()`

at line 63
`FieldDefinitionInterface getFieldDefinition()`

at line 71
`array getSettings()`

at line 82
`mixed getSetting(string $setting_name)`

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

at line 100
`$this filterEmptyItems()`

at line 107
`__get($property_name)`

at line 114
`__set($property_name, $value)`

at line 121
`__isset($property_name)`

at line 128
`__unset($property_name)`

at line 138
`preSave()`

at line 155
`bool postSave(bool $update)`

at line 163
`delete()`

at line 172
`deleteRevision()`

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

at line 195
`generateSampleItems(int $count = 1)`

at line 211
`array defaultValuesForm(array $form, FormStateInterface $form_state)`

at line 226
`defaultValuesFormValidate(array $element, array $form, FormStateInterface $form_state)`

at line 244
`array defaultValuesFormSubmit(array $element, array $form, FormStateInterface $form_state)`

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

at line 278
`bool equals(FieldItemListInterface $list_to_compare)`

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