FieldItemInterface.php 17.4 KB
Newer Older
1 2
<?php

3
namespace Drupal\Core\Field;
4

5
use Drupal\Core\Form\FormStateInterface;
6 7 8
use Drupal\Core\TypedData\ComplexDataInterface;

/**
9 10 11 12
 * Interface for entity field items.
 *
 * Entity field items are typed data objects containing the field values, i.e.
 * implementing the ComplexDataInterface.
13 14 15 16
 *
 * When implementing this interface which extends Traversable, make sure to list
 * IteratorAggregate or Iterator before this interface in the implements clause.
 *
17 18
 * @see \Drupal\Core\Field\FieldItemListInterface
 * @see \Drupal\Core\Field\FieldItemBase
19
 * @ingroup field_types
20
 */
21
interface FieldItemInterface extends ComplexDataInterface {
22

23 24 25
  /**
   * Defines field item properties.
   *
26 27 28
   * Properties that are required to constitute a valid, non-empty item should
   * be denoted with \Drupal\Core\TypedData\DataDefinition::setRequired().
   *
29 30 31 32
   * @return \Drupal\Core\TypedData\DataDefinitionInterface[]
   *   An array of property definitions of contained properties, keyed by
   *   property name.
   *
33
   * @see \Drupal\Core\Field\BaseFieldDefinition
34
   */
35
  public static function propertyDefinitions(FieldStorageDefinitionInterface $field_definition);
36 37 38 39 40 41 42 43 44 45 46

  /**
   * Returns the name of the main property, if any.
   *
   * Some field items consist mainly of one main property, e.g. the value of a
   * text field or the @code target_id @endcode of an entity reference. If the
   * field item has no main property, the method returns NULL.
   *
   * @return string|null
   *   The name of the value property, or NULL if there is none.
   *
47
   * @see \Drupal\Core\Field\BaseFieldDefinition
48 49 50
   */
  public static function mainPropertyName();

51 52 53 54 55
  /**
   * Returns the schema for the field.
   *
   * This method is static because the field schema information is needed on
   * creation of the field. FieldItemInterface objects instantiated at that
56
   * time are not reliable as field settings might be missing.
57 58 59
   *
   * Computed fields having no schema should return an empty array.
   *
60
   * @param \Drupal\Core\Field\FieldStorageDefinitionInterface $field_definition
61 62 63 64 65 66 67
   *   The field definition.
   *
   * @return array
   *   An empty array if there is no schema, or an associative array with the
   *   following key/value pairs:
   *   - columns: An array of Schema API column specifications, keyed by column
   *     name. The columns need to be a subset of the properties defined in
68 69 70 71 72 73
   *     propertyDefinitions(). The 'not null' property is ignored if present,
   *     as it is determined automatically by the storage controller depending
   *     on the table layout and the property definitions. It is recommended to
   *     avoid having the column definitions depend on field settings when
   *     possible. No assumptions should be made on how storage engines
   *     internally use the original column name to structure their storage.
74 75
   *   - unique keys: (optional) An array of Schema API unique key definitions.
   *     Only columns that appear in the 'columns' array are allowed.
76 77
   *   - indexes: (optional) An array of Schema API index definitions. Only
   *     columns that appear in the 'columns' array are allowed. Those indexes
78 79 80 81
   *     will be used as default indexes. Field definitions can specify
   *     additional indexes or, at their own risk, modify the default indexes
   *     specified by the field-type module. Some storage engines might not
   *     support indexes.
82 83 84 85 86 87
   *   - foreign keys: (optional) An array of Schema API foreign key
   *     definitions. Note, however, that the field data is not necessarily
   *     stored in SQL. Also, the possible usage is limited, as you cannot
   *     specify another field as related, only existing SQL tables,
   *     such as {taxonomy_term_data}.
   */
88
  public static function schema(FieldStorageDefinitionInterface $field_definition);
89

90 91 92
  /**
   * Gets the entity that field belongs to.
   *
93
   * @return \Drupal\Core\Entity\FieldableEntityInterface
94 95 96 97
   *   The entity object.
   */
  public function getEntity();

98 99 100
  /**
   * Gets the langcode of the field values held in the object.
   *
101
   * @return string
102 103 104 105
   *   The langcode.
   */
  public function getLangcode();

106 107 108
  /**
   * Gets the field definition.
   *
109
   * @return \Drupal\Core\Field\FieldDefinitionInterface
110 111 112 113
   *   The field definition.
   */
  public function getFieldDefinition();

114
  /**
115
   * Magic method: Gets a property value.
116
   *
117
   * @param string $property_name
118 119
   *   The name of the property to get; e.g., 'title' or 'name'.
   *
120 121
   * @return mixed
   *   The property value.
122 123 124
   *
   * @throws \InvalidArgumentException
   *   If a not existing property is accessed.
125 126 127 128
   */
  public function __get($property_name);

  /**
129
   * Magic method: Sets a property value.
130
   *
131
   * @param string $property_name
132
   *   The name of the property to set; e.g., 'title' or 'name'.
133
   * @param mixed $value
134 135 136 137 138 139 140 141 142 143
   *   The value to set, or NULL to unset the property. Optionally, a typed
   *   data object implementing Drupal\Core\TypedData\TypedDataInterface may be
   *   passed instead of a plain value.
   *
   * @throws \InvalidArgumentException
   *   If a not existing property is set.
   */
  public function __set($property_name, $value);

  /**
144
   * Magic method: Determines whether a property is set.
145
   *
146
   * @param string $property_name
147 148
   *   The name of the property to get; e.g., 'title' or 'name'.
   *
149
   * @return bool
150 151 152 153 154
   *   Returns TRUE if the property exists and is set, FALSE otherwise.
   */
  public function __isset($property_name);

  /**
155
   * Magic method: Unsets a property.
156
   *
157
   * @param string $property_name
158 159 160
   *   The name of the property to get; e.g., 'title' or 'name'.
   */
  public function __unset($property_name);
161

162 163 164 165 166 167 168 169 170 171 172 173 174 175
  /**
   * Returns a renderable array for a single field item.
   *
   * @param 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 item.
   *
   * @see \Drupal\Core\Entity\EntityViewBuilderInterface::viewField()
   * @see \Drupal\Core\Entity\EntityViewBuilderInterface::viewFieldItem()
   * @see \Drupal\Core\Field\FieldItemListInterface::view()
   */
176
  public function view($display_options = []);
177

178 179 180
  /**
   * Defines custom presave behavior for field values.
   *
181 182 183 184 185 186 187
   * This method is called during the process of saving an entity, just before
   * values are written into storage. When storing a new entity, its identifier
   * will not be available yet. This should be used to massage item property
   * values or perform any other operation that needs to happen before values
   * are stored. For instance this is the proper phase to auto-create a new
   * entity for an entity reference field item, because this way it will be
   * possible to store the referenced entity identifier.
188 189 190 191
   */
  public function preSave();

  /**
192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211
   * Defines custom post-save behavior for field values.
   *
   * This method is called during the process of saving an entity, just after
   * values are written into storage. This is useful mostly when the business
   * logic to be implemented always requires the entity identifier, even when
   * storing a new entity. For instance, when implementing circular entity
   * references, the referenced entity will be created on pre-save with a dummy
   * value for the referring entity identifier, which will be updated with the
   * actual one on post-save.
   *
   * In the rare cases where item properties depend on the entity identifier,
   * massaging logic will have to be implemented on post-save and returning TRUE
   * will allow them to be rewritten to the storage with the updated values.
   *
   * @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.
212
   */
213
  public function postSave($update);
214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231

  /**
   * 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();

232 233 234 235 236 237 238 239 240 241 242 243 244 245
  /**
   * Generates placeholder field values.
   *
   * Useful when populating site with placeholder content during site building
   * or profiling.
   *
   * @param \Drupal\Core\Field\FieldDefinitionInterface $field_definition
   *   The field definition.
   *
   * @return array
   *   An associative array of values.
   */
  public static function generateSampleValue(FieldDefinitionInterface $field_definition);

246
  /**
247
   * Defines the storage-level settings for this plugin.
248 249 250 251
   *
   * @return array
   *   A list of default settings, keyed by the setting name.
   */
252
  public static function defaultStorageSettings();
253 254

  /**
255
   * Defines the field-level settings for this plugin.
256 257 258 259
   *
   * @return array
   *   A list of default settings, keyed by the setting name.
   */
260
  public static function defaultFieldSettings();
261

262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278
  /**
   * Returns a settings array that can be stored as a configuration value.
   *
   * For all use cases where field settings are stored and managed as
   * configuration, this method is used to map from the field type's
   * representation of its settings to a representation compatible with
   * deployable configuration. This includes:
   * - Array keys at any depth must not contain a ".".
   * - Ideally, array keys at any depth are either numeric or can be enumerated
   *   as a "mapping" within the configuration schema. While not strictly
   *   required, this simplifies configuration translation UIs, configuration
   *   migrations between Drupal versions, and other use cases.
   * - To support configuration deployments, references to content entities
   *   must use UUIDs rather than local IDs.
   *
   * An example of a conversion between representations might be an
   * "allowed_values" setting that's structured by the field type as a
279
   * \Drupal\Core\TypedData\OptionsProviderInterface::getPossibleOptions()
280 281 282 283 284 285 286 287 288 289 290 291 292 293
   * result (i.e., values as keys and labels as values). For such a use case,
   * in order to comply with the above, this method could convert that
   * representation to a numerically indexed array whose values are sub-arrays
   * with the schema definable keys of "value" and "label".
   *
   * @param array $settings
   *   The field's settings in the field type's canonical representation.
   *
   * @return array
   *   An array (either the unmodified $settings or a modified representation)
   *   that is suitable for storing as a deployable configuration value.
   *
   * @see \Drupal\Core\Config\Config::set()
   */
294
  public static function storageSettingsToConfigData(array $settings);
295 296 297 298

  /**
   * Returns a settings array in the field type's canonical representation.
   *
299
   * This function does the inverse of static::storageSettingsToConfigData(). It's
300 301 302 303 304 305 306 307 308
   * called when loading a field's settings from a configuration object.
   *
   * @param array $settings
   *   The field's settings, as it is stored within a configuration object.
   *
   * @return array
   *   The settings, in the representation expected by the field type and code
   *   that interacts with it.
   *
309
   * @see \Drupal\Core\Field\FieldItemInterface::storageSettingsToConfigData()
310
   */
311
  public static function storageSettingsFromConfigData(array $settings);
312 313 314 315

  /**
   * Returns a settings array that can be stored as a configuration value.
   *
316
   * Same as static::storageSettingsToConfigData(), but for the field's settings.
317 318
   *
   * @param array $settings
319
   *   The field's settings in the field type's canonical representation.
320 321 322 323 324
   *
   * @return array
   *   An array (either the unmodified $settings or a modified representation)
   *   that is suitable for storing as a deployable configuration value.
   *
325
   * @see \Drupal\Core\Field\FieldItemInterface::storageSettingsToConfigData()
326
   */
327
  public static function fieldSettingsToConfigData(array $settings);
328 329 330 331

  /**
   * Returns a settings array in the field type's canonical representation.
   *
332 333
   * This function does the inverse of static::fieldSettingsToConfigData().
   * It's called when loading a field's settings from a configuration
334 335 336
   * object.
   *
   * @param array $settings
337
   *   The field's settings, as it is stored within a configuration
338 339 340
   *   object.
   *
   * @return array
341
   *   The field settings, in the representation expected by the field type
342 343
   *   and code that interacts with it.
   *
344
   * @see \Drupal\Core\Field\FieldItemInterface::fieldSettingsToConfigData()
345
   */
346
  public static function fieldSettingsFromConfigData(array $settings);
347

348
  /**
349
   * Returns a form for the storage-level settings.
350
   *
351
   * Invoked from \Drupal\field_ui\Form\FieldStorageConfigEditForm to allow
352
   * administrators to configure storage-level settings.
353
   *
354 355 356 357 358
   * Field storage might reject settings changes that affect the field
   * storage schema if the storage already has data. When the $has_data
   * parameter is TRUE, the form should not allow changing the settings that
   * take part in the schema() method. It is recommended to set #access to
   * FALSE on the corresponding elements.
359 360 361
   *
   * @param array $form
   *   The form where the settings form is being included in.
362
   * @param \Drupal\Core\Form\FormStateInterface $form_state
363 364 365 366
   *   The form state of the (entire) configuration form.
   * @param bool $has_data
   *   TRUE if the field already has data, FALSE if not.
   *
367
   * @return array
368 369
   *   The form definition for the field settings.
   */
370
  public function storageSettingsForm(array &$form, FormStateInterface $form_state, $has_data);
371 372

  /**
373
   * Returns a form for the field-level settings.
374
   *
375
   * Invoked from \Drupal\field_ui\Form\FieldConfigEditForm to allow
376
   * administrators to configure field-level settings.
377 378 379
   *
   * @param array $form
   *   The form where the settings form is being included in.
380
   * @param \Drupal\Core\Form\FormStateInterface $form_state
381 382 383
   *   The form state of the (entire) configuration form.
   *
   * @return array
384
   *   The form definition for the field settings.
385
   */
386
  public function fieldSettingsForm(array $form, FormStateInterface $form_state);
387

388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415
  /**
   * Calculates dependencies for field items.
   *
   * Dependencies are saved in the field configuration entity and are used to
   * determine configuration synchronization order. For example, if the field
   * type's default value is a content entity, this method should return an
   * array of dependencies listing the content entities.
   *
   * @param \Drupal\Core\Field\FieldDefinitionInterface $field_definition
   *   The field definition.
   *
   * @return array
   *   An array of dependencies grouped by type (config, content, module,
   *   theme). For example:
   *   @code
   *   array(
   *     'config' => array('user.role.anonymous', 'user.role.authenticated'),
   *     'content' => array('node:article:f0a189e6-55fb-47fb-8005-5bef81c44d6d'),
   *     'module' => array('node', 'user'),
   *     'theme' => array('seven'),
   *   );
   *   @endcode
   *
   * @see \Drupal\Core\Config\Entity\ConfigDependencyManager
   * @see \Drupal\Core\Config\Entity\ConfigEntityInterface::getConfigDependencyName()
   */
  public static function calculateDependencies(FieldDefinitionInterface $field_definition);

416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448
  /**
   * Calculates dependencies for field items on the storage level.
   *
   * Dependencies are saved in the field storage configuration entity and are
   * used to determine configuration synchronization order. For example, if the
   * field type storage depends on a particular entity type, this method should
   * return an array of dependencies listing the module that provides the entity
   * type.
   *
   * Dependencies returned from this method are stored in field storage
   * configuration and are always considered hard dependencies. If the
   * dependency is removed the field storage configuration must be deleted.
   *
   * @param \Drupal\Core\Field\FieldStorageDefinitionInterface $field_storage_definition
   *   The field storage definition.
   *
   * @return array
   *   An array of dependencies grouped by type (config, content, module,
   *   theme). For example:
   *   @code
   *   [
   *     'config' => ['user.role.anonymous', 'user.role.authenticated'],
   *     'content' => ['node:article:f0a189e6-55fb-47fb-8005-5bef81c44d6d'],
   *     'module' => ['node', 'user'],
   *     'theme' => ['seven'],
   *   ];
   *   @endcode
   *
   * @see \Drupal\Core\Config\Entity\ConfigDependencyManager
   * @see \Drupal\Core\Config\Entity\ConfigEntityInterface::getConfigDependencyName()
   */
  public static function calculateStorageDependencies(FieldStorageDefinitionInterface $field_storage_definition);

449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464
  /**
   * Informs the plugin that a dependency of the field will be deleted.
   *
   * @param \Drupal\Core\Field\FieldDefinitionInterface $field_definition
   *   The field definition.
   * @param array $dependencies
   *   An array of dependencies that will be deleted keyed by dependency type.
   *   Dependency types are, for example, entity, module and theme.
   *
   * @return bool
   *   TRUE if the field definition has been changed as a result, FALSE if not.
   *
   * @see \Drupal\Core\Config\ConfigEntityInterface::onDependencyRemoval()
   */
  public static function onDependencyRemoval(FieldDefinitionInterface $field_definition, array $dependencies);

465
}