3 namespace Drupal\Core\Field;
5 use Drupal\Core\Entity\FieldableEntityInterface;
6 use Drupal\Core\Form\FormStateInterface;
7 use Drupal\Core\Session\AccountInterface;
8 use Drupal\Core\Access\AccessibleInterface;
9 use Drupal\Core\TypedData\ListInterface;
12 * Interface for fields, being lists of field items.
14 * This interface must be implemented by every entity field, whereas contained
15 * field items must implement the FieldItemInterface.
16 * Some methods of the fields are delegated to the first contained item, in
17 * particular get() and set() as well as their magic equivalences.
19 * Optionally, a typed data object implementing
20 * Drupal\Core\TypedData\TypedDataInterface may be passed to
21 * ArrayAccess::offsetSet() instead of a plain value.
23 * When implementing this interface which extends Traversable, make sure to list
24 * IteratorAggregate or Iterator before this interface in the implements clause.
26 * @see \Drupal\Core\Field\FieldItemInterface
28 interface FieldItemListInterface extends ListInterface, AccessibleInterface {
31 * Gets the entity that field belongs to.
33 * @return \Drupal\Core\Entity\EntityInterface
36 public function getEntity();
39 * Sets the langcode of the field values held in the object.
41 * @param string $langcode
44 public function setLangcode($langcode);
47 * Gets the langcode of the field values held in the object.
52 public function getLangcode();
55 * Gets the field definition.
57 * @return \Drupal\Core\Field\FieldDefinitionInterface
58 * The field definition.
60 public function getFieldDefinition();
63 * Returns the array of field settings.
66 * An array of key/value pairs.
68 public function getSettings();
71 * Returns the value of a given field setting.
73 * @param string $setting_name
79 public function getSetting($setting_name);
82 * Contains the default access logic of this field.
84 * See \Drupal\Core\Entity\EntityAccessControlHandlerInterface::fieldAccess() for
85 * the parameter documentation.
87 * @return \Drupal\Core\Access\AccessResultInterface
90 public function defaultAccess($operation = 'view', AccountInterface $account = NULL);
93 * Filters out empty field items and re-numbers the item deltas.
97 public function filterEmptyItems();
100 * Magic method: Gets a property value of to the first field item.
102 * @see \Drupal\Core\Field\FieldItemInterface::__set()
104 public function __get($property_name);
107 * Magic method: Sets a property value of the first field item.
109 * @see \Drupal\Core\Field\FieldItemInterface::__get()
111 public function __set($property_name, $value);
114 * Magic method: Determines whether a property of the first field item is set.
116 * @see \Drupal\Core\Field\FieldItemInterface::__unset()
118 public function __isset($property_name);
121 * Magic method: Unsets a property of the first field item.
123 * @see \Drupal\Core\Field\FieldItemInterface::__isset()
125 public function __unset($property_name);
128 * Defines custom presave behavior for field values.
130 * This method is called during the process of saving an entity, just before
131 * item values are written into storage.
133 * @see \Drupal\Core\Field\FieldItemInterface::preSave()
135 public function preSave();
138 * Defines custom post-save behavior for field values.
140 * This method is called during the process of saving an entity, just after
141 * item values are written into storage.
143 * @param bool $update
144 * Specifies whether the entity is being updated or created.
147 * Whether field items should be rewritten to the storage as a consequence
148 * of the logic implemented by the custom behavior.
150 * @see \Drupal\Core\Field\FieldItemInterface::postSave()
152 public function postSave($update);
155 * Defines custom delete behavior for field values.
157 * This method is called during the process of deleting an entity, just before
158 * values are deleted from storage.
160 public function delete();
163 * Defines custom revision delete behavior for field values.
165 * This method is called from during the process of deleting an entity
166 * revision, just before the field values are deleted from storage. It is only
167 * called for entity types that support revisioning.
169 public function deleteRevision();
172 * Returns a renderable array for the field items.
174 * @param array $display_options
175 * Can be either the name of a view mode, or an array of display settings.
176 * See EntityViewBuilderInterface::viewField() for more information.
179 * A renderable array for the field values.
181 * @see \Drupal\Core\Entity\EntityViewBuilderInterface::viewField()
182 * @see \Drupal\Core\Field\FieldItemInterface::view()
184 public function view($display_options = []);
187 * Populates a specified number of field items with valid sample data.
190 * The number of items to create.
192 public function generateSampleItems($count = 1);
195 * Returns a form for the default value input.
197 * Invoked from \Drupal\field_ui\Form\FieldConfigEditForm to allow
198 * administrators to configure instance-level default value.
201 * The form where the settings form is being included in.
202 * @param \Drupal\Core\Form\FormStateInterface $form_state
203 * The form state of the (entire) configuration form.
206 * The form definition for the field default value.
208 public function defaultValuesForm(array &$form, FormStateInterface $form_state);
211 * Validates the submitted default value.
213 * Invoked from \Drupal\field_ui\Form\FieldConfigEditForm to allow
214 * administrators to configure instance-level default value.
216 * @param array $element
217 * The default value form element.
219 * The form where the settings form is being included in.
220 * @param \Drupal\Core\Form\FormStateInterface $form_state
221 * The form state of the (entire) configuration form.
223 public function defaultValuesFormValidate(array $element, array &$form, FormStateInterface $form_state);
226 * Processes the submitted default value.
228 * Invoked from \Drupal\field_ui\Form\FieldConfigEditForm to allow
229 * administrators to configure instance-level default value.
231 * @param array $element
232 * The default value form element.
234 * The form where the settings form is being included in.
235 * @param \Drupal\Core\Form\FormStateInterface $form_state
236 * The form state of the (entire) configuration form.
239 * The field default value.
241 public function defaultValuesFormSubmit(array $element, array &$form, FormStateInterface $form_state);
244 * Processes the default value before being applied.
246 * Defined or configured default values of a field might need some processing
247 * in order to be a valid runtime value for the field type; e.g., a date field
248 * could process the defined value of 'NOW' to a valid date.
250 * @param array $default_value
251 * The unprocessed default value defined for the field, as a numerically
252 * indexed array of items, each item being an array of property/value pairs.
253 * @param \Drupal\Core\Entity\FieldableEntityInterface $entity
254 * The entity for which the default value is generated.
255 * @param \Drupal\Core\Field\FieldDefinitionInterface $definition
256 * The definition of the field.
259 * The return default value for the field.
261 public static function processDefaultValue($default_value, FieldableEntityInterface $entity, FieldDefinitionInterface $definition);
264 * Determines equality to another object implementing FieldItemListInterface.
266 * @param \Drupal\Core\Field\FieldItemListInterface $list_to_compare
267 * The field item list to compare to.
270 * TRUE if the field item lists are equal, FALSE if not.
272 public function equals(FieldItemListInterface $list_to_compare);