3 namespace Drupal\Core\Field;
5 use Drupal\Core\Form\FormStateInterface;
6 use Drupal\Core\TypedData\ComplexDataInterface;
9 * Interface for entity field items.
11 * Entity field items are typed data objects containing the field values, i.e.
12 * implementing the ComplexDataInterface.
14 * When implementing this interface which extends Traversable, make sure to list
15 * IteratorAggregate or Iterator before this interface in the implements clause.
17 * @see \Drupal\Core\Field\FieldItemListInterface
18 * @see \Drupal\Core\Field\FieldItemBase
19 * @ingroup field_types
21 interface FieldItemInterface extends ComplexDataInterface {
24 * Defines field item properties.
26 * Properties that are required to constitute a valid, non-empty item should
27 * be denoted with \Drupal\Core\TypedData\DataDefinition::setRequired().
29 * @return \Drupal\Core\TypedData\DataDefinitionInterface[]
30 * An array of property definitions of contained properties, keyed by
33 * @see \Drupal\Core\Field\BaseFieldDefinition
35 public static function propertyDefinitions(FieldStorageDefinitionInterface $field_definition);
38 * Returns the name of the main property, if any.
40 * Some field items consist mainly of one main property, e.g. the value of a
41 * text field or the @code target_id @endcode of an entity reference. If the
42 * field item has no main property, the method returns NULL.
45 * The name of the value property, or NULL if there is none.
47 * @see \Drupal\Core\Field\BaseFieldDefinition
49 public static function mainPropertyName();
52 * Returns the schema for the field.
54 * This method is static because the field schema information is needed on
55 * creation of the field. FieldItemInterface objects instantiated at that
56 * time are not reliable as field settings might be missing.
58 * Computed fields having no schema should return an empty array.
60 * @param \Drupal\Core\Field\FieldStorageDefinitionInterface $field_definition
61 * The field definition.
64 * An empty array if there is no schema, or an associative array with the
65 * following key/value pairs:
66 * - columns: An array of Schema API column specifications, keyed by column
67 * name. The columns need to be a subset of the properties defined in
68 * propertyDefinitions(). The 'not null' property is ignored if present,
69 * as it is determined automatically by the storage controller depending
70 * on the table layout and the property definitions. It is recommended to
71 * avoid having the column definitions depend on field settings when
72 * possible. No assumptions should be made on how storage engines
73 * internally use the original column name to structure their storage.
74 * - unique keys: (optional) An array of Schema API unique key definitions.
75 * Only columns that appear in the 'columns' array are allowed.
76 * - indexes: (optional) An array of Schema API index definitions. Only
77 * columns that appear in the 'columns' array are allowed. Those indexes
78 * will be used as default indexes. Field definitions can specify
79 * additional indexes or, at their own risk, modify the default indexes
80 * specified by the field-type module. Some storage engines might not
82 * - foreign keys: (optional) An array of Schema API foreign key
83 * definitions. Note, however, that the field data is not necessarily
84 * stored in SQL. Also, the possible usage is limited, as you cannot
85 * specify another field as related, only existing SQL tables,
86 * such as {taxonomy_term_data}.
88 public static function schema(FieldStorageDefinitionInterface $field_definition);
91 * Gets the entity that field belongs to.
93 * @return \Drupal\Core\Entity\FieldableEntityInterface
96 public function getEntity();
99 * Gets the langcode of the field values held in the object.
104 public function getLangcode();
107 * Gets the field definition.
109 * @return \Drupal\Core\Field\FieldDefinitionInterface
110 * The field definition.
112 public function getFieldDefinition();
115 * Magic method: Gets a property value.
117 * @param string $property_name
118 * The name of the property to get; e.g., 'title' or 'name'.
121 * The property value.
123 * @throws \InvalidArgumentException
124 * If a not existing property is accessed.
126 public function __get($property_name);
129 * Magic method: Sets a property value.
131 * @param string $property_name
132 * The name of the property to set; e.g., 'title' or 'name'.
133 * @param mixed $value
134 * The value to set, or NULL to unset the property. Optionally, a typed
135 * data object implementing Drupal\Core\TypedData\TypedDataInterface may be
136 * passed instead of a plain value.
138 * @throws \InvalidArgumentException
139 * If a not existing property is set.
141 public function __set($property_name, $value);
144 * Magic method: Determines whether a property is set.
146 * @param string $property_name
147 * The name of the property to get; e.g., 'title' or 'name'.
150 * Returns TRUE if the property exists and is set, FALSE otherwise.
152 public function __isset($property_name);
155 * Magic method: Unsets a property.
157 * @param string $property_name
158 * The name of the property to get; e.g., 'title' or 'name'.
160 public function __unset($property_name);
163 * Returns a renderable array for a single field item.
165 * @param array $display_options
166 * Can be either the name of a view mode, or an array of display settings.
167 * See EntityViewBuilderInterface::viewField() for more information.
170 * A renderable array for the field item.
172 * @see \Drupal\Core\Entity\EntityViewBuilderInterface::viewField()
173 * @see \Drupal\Core\Entity\EntityViewBuilderInterface::viewFieldItem()
174 * @see \Drupal\Core\Field\FieldItemListInterface::view()
176 public function view($display_options = []);
179 * Defines custom presave behavior for field values.
181 * This method is called during the process of saving an entity, just before
182 * values are written into storage. When storing a new entity, its identifier
183 * will not be available yet. This should be used to massage item property
184 * values or perform any other operation that needs to happen before values
185 * are stored. For instance this is the proper phase to auto-create a new
186 * entity for an entity reference field item, because this way it will be
187 * possible to store the referenced entity identifier.
189 public function preSave();
192 * Defines custom post-save behavior for field values.
194 * This method is called during the process of saving an entity, just after
195 * values are written into storage. This is useful mostly when the business
196 * logic to be implemented always requires the entity identifier, even when
197 * storing a new entity. For instance, when implementing circular entity
198 * references, the referenced entity will be created on pre-save with a dummy
199 * value for the referring entity identifier, which will be updated with the
200 * actual one on post-save.
202 * In the rare cases where item properties depend on the entity identifier,
203 * massaging logic will have to be implemented on post-save and returning TRUE
204 * will allow them to be rewritten to the storage with the updated values.
206 * @param bool $update
207 * Specifies whether the entity is being updated or created.
210 * Whether field items should be rewritten to the storage as a consequence
211 * of the logic implemented by the custom behavior.
213 public function postSave($update);
216 * Defines custom delete behavior for field values.
218 * This method is called during the process of deleting an entity, just before
219 * values are deleted from storage.
221 public function delete();
224 * Defines custom revision delete behavior for field values.
226 * This method is called from during the process of deleting an entity
227 * revision, just before the field values are deleted from storage. It is only
228 * called for entity types that support revisioning.
230 public function deleteRevision();
233 * Generates placeholder field values.
235 * Useful when populating site with placeholder content during site building
238 * @param \Drupal\Core\Field\FieldDefinitionInterface $field_definition
239 * The field definition.
242 * An associative array of values.
244 public static function generateSampleValue(FieldDefinitionInterface $field_definition);
247 * Defines the storage-level settings for this plugin.
250 * A list of default settings, keyed by the setting name.
252 public static function defaultStorageSettings();
255 * Defines the field-level settings for this plugin.
258 * A list of default settings, keyed by the setting name.
260 public static function defaultFieldSettings();
263 * Returns a settings array that can be stored as a configuration value.
265 * For all use cases where field settings are stored and managed as
266 * configuration, this method is used to map from the field type's
267 * representation of its settings to a representation compatible with
268 * deployable configuration. This includes:
269 * - Array keys at any depth must not contain a ".".
270 * - Ideally, array keys at any depth are either numeric or can be enumerated
271 * as a "mapping" within the configuration schema. While not strictly
272 * required, this simplifies configuration translation UIs, configuration
273 * migrations between Drupal versions, and other use cases.
274 * - To support configuration deployments, references to content entities
275 * must use UUIDs rather than local IDs.
277 * An example of a conversion between representations might be an
278 * "allowed_values" setting that's structured by the field type as a
279 * \Drupal\Core\TypedData\OptionsProviderInterface::getPossibleOptions()
280 * result (i.e., values as keys and labels as values). For such a use case,
281 * in order to comply with the above, this method could convert that
282 * representation to a numerically indexed array whose values are sub-arrays
283 * with the schema definable keys of "value" and "label".
285 * @param array $settings
286 * The field's settings in the field type's canonical representation.
289 * An array (either the unmodified $settings or a modified representation)
290 * that is suitable for storing as a deployable configuration value.
292 * @see \Drupal\Core\Config\Config::set()
294 public static function storageSettingsToConfigData(array $settings);
297 * Returns a settings array in the field type's canonical representation.
299 * This function does the inverse of static::storageSettingsToConfigData(). It's
300 * called when loading a field's settings from a configuration object.
302 * @param array $settings
303 * The field's settings, as it is stored within a configuration object.
306 * The settings, in the representation expected by the field type and code
307 * that interacts with it.
309 * @see \Drupal\Core\Field\FieldItemInterface::storageSettingsToConfigData()
311 public static function storageSettingsFromConfigData(array $settings);
314 * Returns a settings array that can be stored as a configuration value.
316 * Same as static::storageSettingsToConfigData(), but for the field's settings.
318 * @param array $settings
319 * The field's settings in the field type's canonical representation.
322 * An array (either the unmodified $settings or a modified representation)
323 * that is suitable for storing as a deployable configuration value.
325 * @see \Drupal\Core\Field\FieldItemInterface::storageSettingsToConfigData()
327 public static function fieldSettingsToConfigData(array $settings);
330 * Returns a settings array in the field type's canonical representation.
332 * This function does the inverse of static::fieldSettingsToConfigData().
333 * It's called when loading a field's settings from a configuration
336 * @param array $settings
337 * The field's settings, as it is stored within a configuration
341 * The field settings, in the representation expected by the field type
342 * and code that interacts with it.
344 * @see \Drupal\Core\Field\FieldItemInterface::fieldSettingsToConfigData()
346 public static function fieldSettingsFromConfigData(array $settings);
349 * Returns a form for the storage-level settings.
351 * Invoked from \Drupal\field_ui\Form\FieldStorageConfigEditForm to allow
352 * administrators to configure storage-level settings.
354 * Field storage might reject settings changes that affect the field
355 * storage schema if the storage already has data. When the $has_data
356 * parameter is TRUE, the form should not allow changing the settings that
357 * take part in the schema() method. It is recommended to set #access to
358 * FALSE on the corresponding elements.
361 * The form where the settings form is being included in.
362 * @param \Drupal\Core\Form\FormStateInterface $form_state
363 * The form state of the (entire) configuration form.
364 * @param bool $has_data
365 * TRUE if the field already has data, FALSE if not.
368 * The form definition for the field settings.
370 public function storageSettingsForm(array &$form, FormStateInterface $form_state, $has_data);
373 * Returns a form for the field-level settings.
375 * Invoked from \Drupal\field_ui\Form\FieldConfigEditForm to allow
376 * administrators to configure field-level settings.
379 * The form where the settings form is being included in.
380 * @param \Drupal\Core\Form\FormStateInterface $form_state
381 * The form state of the (entire) configuration form.
384 * The form definition for the field settings.
386 public function fieldSettingsForm(array $form, FormStateInterface $form_state);
389 * Calculates dependencies for field items.
391 * Dependencies are saved in the field configuration entity and are used to
392 * determine configuration synchronization order. For example, if the field
393 * type's default value is a content entity, this method should return an
394 * array of dependencies listing the content entities.
396 * @param \Drupal\Core\Field\FieldDefinitionInterface $field_definition
397 * The field definition.
400 * An array of dependencies grouped by type (config, content, module,
401 * theme). For example:
404 * 'config' => array('user.role.anonymous', 'user.role.authenticated'),
405 * 'content' => array('node:article:f0a189e6-55fb-47fb-8005-5bef81c44d6d'),
406 * 'module' => array('node', 'user'),
407 * 'theme' => array('seven'),
411 * @see \Drupal\Core\Config\Entity\ConfigDependencyManager
412 * @see \Drupal\Core\Config\Entity\ConfigEntityInterface::getConfigDependencyName()
414 public static function calculateDependencies(FieldDefinitionInterface $field_definition);
417 * Calculates dependencies for field items on the storage level.
419 * Dependencies are saved in the field storage configuration entity and are
420 * used to determine configuration synchronization order. For example, if the
421 * field type storage depends on a particular entity type, this method should
422 * return an array of dependencies listing the module that provides the entity
425 * Dependencies returned from this method are stored in field storage
426 * configuration and are always considered hard dependencies. If the
427 * dependency is removed the field storage configuration must be deleted.
429 * @param \Drupal\Core\Field\FieldStorageDefinitionInterface $field_storage_definition
430 * The field storage definition.
433 * An array of dependencies grouped by type (config, content, module,
434 * theme). For example:
437 * 'config' => ['user.role.anonymous', 'user.role.authenticated'],
438 * 'content' => ['node:article:f0a189e6-55fb-47fb-8005-5bef81c44d6d'],
439 * 'module' => ['node', 'user'],
440 * 'theme' => ['seven'],
444 * @see \Drupal\Core\Config\Entity\ConfigDependencyManager
445 * @see \Drupal\Core\Config\Entity\ConfigEntityInterface::getConfigDependencyName()
447 public static function calculateStorageDependencies(FieldStorageDefinitionInterface $field_storage_definition);
450 * Informs the plugin that a dependency of the field will be deleted.
452 * @param \Drupal\Core\Field\FieldDefinitionInterface $field_definition
453 * The field definition.
454 * @param array $dependencies
455 * An array of dependencies that will be deleted keyed by dependency type.
456 * Dependency types are, for example, entity, module and theme.
459 * TRUE if the field definition has been changed as a result, FALSE if not.
461 * @see \Drupal\Core\Config\ConfigEntityInterface::onDependencyRemoval()
463 public static function onDependencyRemoval(FieldDefinitionInterface $field_definition, array $dependencies);