annotate core/lib/Drupal/Core/Field/FieldItemInterface.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents c2387f117808
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 namespace Drupal\Core\Field;
Chris@0 4
Chris@0 5 use Drupal\Core\Form\FormStateInterface;
Chris@0 6 use Drupal\Core\TypedData\ComplexDataInterface;
Chris@0 7
Chris@0 8 /**
Chris@0 9 * Interface for entity field items.
Chris@0 10 *
Chris@0 11 * Entity field items are typed data objects containing the field values, i.e.
Chris@0 12 * implementing the ComplexDataInterface.
Chris@0 13 *
Chris@0 14 * When implementing this interface which extends Traversable, make sure to list
Chris@0 15 * IteratorAggregate or Iterator before this interface in the implements clause.
Chris@0 16 *
Chris@0 17 * @see \Drupal\Core\Field\FieldItemListInterface
Chris@0 18 * @see \Drupal\Core\Field\FieldItemBase
Chris@0 19 * @ingroup field_types
Chris@0 20 */
Chris@0 21 interface FieldItemInterface extends ComplexDataInterface {
Chris@0 22
Chris@0 23 /**
Chris@0 24 * Defines field item properties.
Chris@0 25 *
Chris@0 26 * Properties that are required to constitute a valid, non-empty item should
Chris@0 27 * be denoted with \Drupal\Core\TypedData\DataDefinition::setRequired().
Chris@0 28 *
Chris@0 29 * @return \Drupal\Core\TypedData\DataDefinitionInterface[]
Chris@0 30 * An array of property definitions of contained properties, keyed by
Chris@0 31 * property name.
Chris@0 32 *
Chris@0 33 * @see \Drupal\Core\Field\BaseFieldDefinition
Chris@0 34 */
Chris@0 35 public static function propertyDefinitions(FieldStorageDefinitionInterface $field_definition);
Chris@0 36
Chris@0 37 /**
Chris@0 38 * Returns the name of the main property, if any.
Chris@0 39 *
Chris@0 40 * Some field items consist mainly of one main property, e.g. the value of a
Chris@16 41 * text field or the target_id of an entity reference. If the field item has
Chris@16 42 * no main property, the method returns NULL.
Chris@0 43 *
Chris@0 44 * @return string|null
Chris@0 45 * The name of the value property, or NULL if there is none.
Chris@0 46 *
Chris@0 47 * @see \Drupal\Core\Field\BaseFieldDefinition
Chris@0 48 */
Chris@0 49 public static function mainPropertyName();
Chris@0 50
Chris@0 51 /**
Chris@0 52 * Returns the schema for the field.
Chris@0 53 *
Chris@0 54 * This method is static because the field schema information is needed on
Chris@0 55 * creation of the field. FieldItemInterface objects instantiated at that
Chris@0 56 * time are not reliable as field settings might be missing.
Chris@0 57 *
Chris@0 58 * Computed fields having no schema should return an empty array.
Chris@0 59 *
Chris@0 60 * @param \Drupal\Core\Field\FieldStorageDefinitionInterface $field_definition
Chris@0 61 * The field definition.
Chris@0 62 *
Chris@0 63 * @return array
Chris@0 64 * An empty array if there is no schema, or an associative array with the
Chris@0 65 * following key/value pairs:
Chris@0 66 * - columns: An array of Schema API column specifications, keyed by column
Chris@0 67 * name. The columns need to be a subset of the properties defined in
Chris@0 68 * propertyDefinitions(). The 'not null' property is ignored if present,
Chris@0 69 * as it is determined automatically by the storage controller depending
Chris@0 70 * on the table layout and the property definitions. It is recommended to
Chris@0 71 * avoid having the column definitions depend on field settings when
Chris@0 72 * possible. No assumptions should be made on how storage engines
Chris@0 73 * internally use the original column name to structure their storage.
Chris@0 74 * - unique keys: (optional) An array of Schema API unique key definitions.
Chris@0 75 * Only columns that appear in the 'columns' array are allowed.
Chris@0 76 * - indexes: (optional) An array of Schema API index definitions. Only
Chris@0 77 * columns that appear in the 'columns' array are allowed. Those indexes
Chris@0 78 * will be used as default indexes. Field definitions can specify
Chris@0 79 * additional indexes or, at their own risk, modify the default indexes
Chris@0 80 * specified by the field-type module. Some storage engines might not
Chris@0 81 * support indexes.
Chris@0 82 * - foreign keys: (optional) An array of Schema API foreign key
Chris@0 83 * definitions. Note, however, that the field data is not necessarily
Chris@0 84 * stored in SQL. Also, the possible usage is limited, as you cannot
Chris@0 85 * specify another field as related, only existing SQL tables,
Chris@0 86 * such as {taxonomy_term_data}.
Chris@0 87 */
Chris@0 88 public static function schema(FieldStorageDefinitionInterface $field_definition);
Chris@0 89
Chris@0 90 /**
Chris@0 91 * Gets the entity that field belongs to.
Chris@0 92 *
Chris@0 93 * @return \Drupal\Core\Entity\FieldableEntityInterface
Chris@0 94 * The entity object.
Chris@0 95 */
Chris@0 96 public function getEntity();
Chris@0 97
Chris@0 98 /**
Chris@0 99 * Gets the langcode of the field values held in the object.
Chris@0 100 *
Chris@0 101 * @return string
Chris@0 102 * The langcode.
Chris@0 103 */
Chris@0 104 public function getLangcode();
Chris@0 105
Chris@0 106 /**
Chris@0 107 * Gets the field definition.
Chris@0 108 *
Chris@0 109 * @return \Drupal\Core\Field\FieldDefinitionInterface
Chris@0 110 * The field definition.
Chris@0 111 */
Chris@0 112 public function getFieldDefinition();
Chris@0 113
Chris@0 114 /**
Chris@0 115 * Magic method: Gets a property value.
Chris@0 116 *
Chris@0 117 * @param string $property_name
Chris@0 118 * The name of the property to get; e.g., 'title' or 'name'.
Chris@0 119 *
Chris@0 120 * @return mixed
Chris@0 121 * The property value.
Chris@0 122 *
Chris@0 123 * @throws \InvalidArgumentException
Chris@0 124 * If a not existing property is accessed.
Chris@0 125 */
Chris@0 126 public function __get($property_name);
Chris@0 127
Chris@0 128 /**
Chris@0 129 * Magic method: Sets a property value.
Chris@0 130 *
Chris@0 131 * @param string $property_name
Chris@0 132 * The name of the property to set; e.g., 'title' or 'name'.
Chris@0 133 * @param mixed $value
Chris@0 134 * The value to set, or NULL to unset the property. Optionally, a typed
Chris@0 135 * data object implementing Drupal\Core\TypedData\TypedDataInterface may be
Chris@0 136 * passed instead of a plain value.
Chris@0 137 *
Chris@0 138 * @throws \InvalidArgumentException
Chris@0 139 * If a not existing property is set.
Chris@0 140 */
Chris@0 141 public function __set($property_name, $value);
Chris@0 142
Chris@0 143 /**
Chris@0 144 * Magic method: Determines whether a property is set.
Chris@0 145 *
Chris@0 146 * @param string $property_name
Chris@0 147 * The name of the property to get; e.g., 'title' or 'name'.
Chris@0 148 *
Chris@0 149 * @return bool
Chris@0 150 * Returns TRUE if the property exists and is set, FALSE otherwise.
Chris@0 151 */
Chris@0 152 public function __isset($property_name);
Chris@0 153
Chris@0 154 /**
Chris@0 155 * Magic method: Unsets a property.
Chris@0 156 *
Chris@0 157 * @param string $property_name
Chris@0 158 * The name of the property to get; e.g., 'title' or 'name'.
Chris@0 159 */
Chris@0 160 public function __unset($property_name);
Chris@0 161
Chris@0 162 /**
Chris@0 163 * Returns a renderable array for a single field item.
Chris@0 164 *
Chris@0 165 * @param array $display_options
Chris@0 166 * Can be either the name of a view mode, or an array of display settings.
Chris@0 167 * See EntityViewBuilderInterface::viewField() for more information.
Chris@0 168 *
Chris@0 169 * @return array
Chris@0 170 * A renderable array for the field item.
Chris@0 171 *
Chris@0 172 * @see \Drupal\Core\Entity\EntityViewBuilderInterface::viewField()
Chris@0 173 * @see \Drupal\Core\Entity\EntityViewBuilderInterface::viewFieldItem()
Chris@0 174 * @see \Drupal\Core\Field\FieldItemListInterface::view()
Chris@0 175 */
Chris@0 176 public function view($display_options = []);
Chris@0 177
Chris@0 178 /**
Chris@0 179 * Defines custom presave behavior for field values.
Chris@0 180 *
Chris@0 181 * This method is called during the process of saving an entity, just before
Chris@0 182 * values are written into storage. When storing a new entity, its identifier
Chris@0 183 * will not be available yet. This should be used to massage item property
Chris@0 184 * values or perform any other operation that needs to happen before values
Chris@0 185 * are stored. For instance this is the proper phase to auto-create a new
Chris@0 186 * entity for an entity reference field item, because this way it will be
Chris@0 187 * possible to store the referenced entity identifier.
Chris@0 188 */
Chris@0 189 public function preSave();
Chris@0 190
Chris@0 191 /**
Chris@0 192 * Defines custom post-save behavior for field values.
Chris@0 193 *
Chris@0 194 * This method is called during the process of saving an entity, just after
Chris@0 195 * values are written into storage. This is useful mostly when the business
Chris@0 196 * logic to be implemented always requires the entity identifier, even when
Chris@0 197 * storing a new entity. For instance, when implementing circular entity
Chris@0 198 * references, the referenced entity will be created on pre-save with a dummy
Chris@0 199 * value for the referring entity identifier, which will be updated with the
Chris@0 200 * actual one on post-save.
Chris@0 201 *
Chris@0 202 * In the rare cases where item properties depend on the entity identifier,
Chris@0 203 * massaging logic will have to be implemented on post-save and returning TRUE
Chris@0 204 * will allow them to be rewritten to the storage with the updated values.
Chris@0 205 *
Chris@0 206 * @param bool $update
Chris@0 207 * Specifies whether the entity is being updated or created.
Chris@0 208 *
Chris@0 209 * @return bool
Chris@0 210 * Whether field items should be rewritten to the storage as a consequence
Chris@0 211 * of the logic implemented by the custom behavior.
Chris@0 212 */
Chris@0 213 public function postSave($update);
Chris@0 214
Chris@0 215 /**
Chris@0 216 * Defines custom delete behavior for field values.
Chris@0 217 *
Chris@0 218 * This method is called during the process of deleting an entity, just before
Chris@0 219 * values are deleted from storage.
Chris@0 220 */
Chris@0 221 public function delete();
Chris@0 222
Chris@0 223 /**
Chris@0 224 * Defines custom revision delete behavior for field values.
Chris@0 225 *
Chris@0 226 * This method is called from during the process of deleting an entity
Chris@0 227 * revision, just before the field values are deleted from storage. It is only
Chris@0 228 * called for entity types that support revisioning.
Chris@0 229 */
Chris@0 230 public function deleteRevision();
Chris@0 231
Chris@0 232 /**
Chris@0 233 * Generates placeholder field values.
Chris@0 234 *
Chris@0 235 * Useful when populating site with placeholder content during site building
Chris@0 236 * or profiling.
Chris@0 237 *
Chris@0 238 * @param \Drupal\Core\Field\FieldDefinitionInterface $field_definition
Chris@0 239 * The field definition.
Chris@0 240 *
Chris@0 241 * @return array
Chris@0 242 * An associative array of values.
Chris@0 243 */
Chris@0 244 public static function generateSampleValue(FieldDefinitionInterface $field_definition);
Chris@0 245
Chris@0 246 /**
Chris@0 247 * Defines the storage-level settings for this plugin.
Chris@0 248 *
Chris@0 249 * @return array
Chris@0 250 * A list of default settings, keyed by the setting name.
Chris@0 251 */
Chris@0 252 public static function defaultStorageSettings();
Chris@0 253
Chris@0 254 /**
Chris@0 255 * Defines the field-level settings for this plugin.
Chris@0 256 *
Chris@0 257 * @return array
Chris@0 258 * A list of default settings, keyed by the setting name.
Chris@0 259 */
Chris@0 260 public static function defaultFieldSettings();
Chris@0 261
Chris@0 262 /**
Chris@0 263 * Returns a settings array that can be stored as a configuration value.
Chris@0 264 *
Chris@0 265 * For all use cases where field settings are stored and managed as
Chris@0 266 * configuration, this method is used to map from the field type's
Chris@0 267 * representation of its settings to a representation compatible with
Chris@0 268 * deployable configuration. This includes:
Chris@0 269 * - Array keys at any depth must not contain a ".".
Chris@0 270 * - Ideally, array keys at any depth are either numeric or can be enumerated
Chris@0 271 * as a "mapping" within the configuration schema. While not strictly
Chris@0 272 * required, this simplifies configuration translation UIs, configuration
Chris@0 273 * migrations between Drupal versions, and other use cases.
Chris@0 274 * - To support configuration deployments, references to content entities
Chris@0 275 * must use UUIDs rather than local IDs.
Chris@0 276 *
Chris@0 277 * An example of a conversion between representations might be an
Chris@0 278 * "allowed_values" setting that's structured by the field type as a
Chris@0 279 * \Drupal\Core\TypedData\OptionsProviderInterface::getPossibleOptions()
Chris@0 280 * result (i.e., values as keys and labels as values). For such a use case,
Chris@0 281 * in order to comply with the above, this method could convert that
Chris@0 282 * representation to a numerically indexed array whose values are sub-arrays
Chris@0 283 * with the schema definable keys of "value" and "label".
Chris@0 284 *
Chris@0 285 * @param array $settings
Chris@0 286 * The field's settings in the field type's canonical representation.
Chris@0 287 *
Chris@0 288 * @return array
Chris@0 289 * An array (either the unmodified $settings or a modified representation)
Chris@0 290 * that is suitable for storing as a deployable configuration value.
Chris@0 291 *
Chris@0 292 * @see \Drupal\Core\Config\Config::set()
Chris@0 293 */
Chris@0 294 public static function storageSettingsToConfigData(array $settings);
Chris@0 295
Chris@0 296 /**
Chris@0 297 * Returns a settings array in the field type's canonical representation.
Chris@0 298 *
Chris@0 299 * This function does the inverse of static::storageSettingsToConfigData(). It's
Chris@0 300 * called when loading a field's settings from a configuration object.
Chris@0 301 *
Chris@0 302 * @param array $settings
Chris@0 303 * The field's settings, as it is stored within a configuration object.
Chris@0 304 *
Chris@0 305 * @return array
Chris@0 306 * The settings, in the representation expected by the field type and code
Chris@0 307 * that interacts with it.
Chris@0 308 *
Chris@0 309 * @see \Drupal\Core\Field\FieldItemInterface::storageSettingsToConfigData()
Chris@0 310 */
Chris@0 311 public static function storageSettingsFromConfigData(array $settings);
Chris@0 312
Chris@0 313 /**
Chris@0 314 * Returns a settings array that can be stored as a configuration value.
Chris@0 315 *
Chris@0 316 * Same as static::storageSettingsToConfigData(), but for the field's settings.
Chris@0 317 *
Chris@0 318 * @param array $settings
Chris@0 319 * The field's settings in the field type's canonical representation.
Chris@0 320 *
Chris@0 321 * @return array
Chris@0 322 * An array (either the unmodified $settings or a modified representation)
Chris@0 323 * that is suitable for storing as a deployable configuration value.
Chris@0 324 *
Chris@0 325 * @see \Drupal\Core\Field\FieldItemInterface::storageSettingsToConfigData()
Chris@0 326 */
Chris@0 327 public static function fieldSettingsToConfigData(array $settings);
Chris@0 328
Chris@0 329 /**
Chris@0 330 * Returns a settings array in the field type's canonical representation.
Chris@0 331 *
Chris@0 332 * This function does the inverse of static::fieldSettingsToConfigData().
Chris@0 333 * It's called when loading a field's settings from a configuration
Chris@0 334 * object.
Chris@0 335 *
Chris@0 336 * @param array $settings
Chris@0 337 * The field's settings, as it is stored within a configuration
Chris@0 338 * object.
Chris@0 339 *
Chris@0 340 * @return array
Chris@0 341 * The field settings, in the representation expected by the field type
Chris@0 342 * and code that interacts with it.
Chris@0 343 *
Chris@0 344 * @see \Drupal\Core\Field\FieldItemInterface::fieldSettingsToConfigData()
Chris@0 345 */
Chris@0 346 public static function fieldSettingsFromConfigData(array $settings);
Chris@0 347
Chris@0 348 /**
Chris@0 349 * Returns a form for the storage-level settings.
Chris@0 350 *
Chris@0 351 * Invoked from \Drupal\field_ui\Form\FieldStorageConfigEditForm to allow
Chris@0 352 * administrators to configure storage-level settings.
Chris@0 353 *
Chris@0 354 * Field storage might reject settings changes that affect the field
Chris@0 355 * storage schema if the storage already has data. When the $has_data
Chris@0 356 * parameter is TRUE, the form should not allow changing the settings that
Chris@0 357 * take part in the schema() method. It is recommended to set #access to
Chris@0 358 * FALSE on the corresponding elements.
Chris@0 359 *
Chris@0 360 * @param array $form
Chris@0 361 * The form where the settings form is being included in.
Chris@0 362 * @param \Drupal\Core\Form\FormStateInterface $form_state
Chris@0 363 * The form state of the (entire) configuration form.
Chris@0 364 * @param bool $has_data
Chris@0 365 * TRUE if the field already has data, FALSE if not.
Chris@0 366 *
Chris@0 367 * @return array
Chris@0 368 * The form definition for the field settings.
Chris@0 369 */
Chris@0 370 public function storageSettingsForm(array &$form, FormStateInterface $form_state, $has_data);
Chris@0 371
Chris@0 372 /**
Chris@0 373 * Returns a form for the field-level settings.
Chris@0 374 *
Chris@0 375 * Invoked from \Drupal\field_ui\Form\FieldConfigEditForm to allow
Chris@0 376 * administrators to configure field-level settings.
Chris@0 377 *
Chris@0 378 * @param array $form
Chris@0 379 * The form where the settings form is being included in.
Chris@0 380 * @param \Drupal\Core\Form\FormStateInterface $form_state
Chris@0 381 * The form state of the (entire) configuration form.
Chris@0 382 *
Chris@0 383 * @return array
Chris@0 384 * The form definition for the field settings.
Chris@0 385 */
Chris@0 386 public function fieldSettingsForm(array $form, FormStateInterface $form_state);
Chris@0 387
Chris@0 388 /**
Chris@0 389 * Calculates dependencies for field items.
Chris@0 390 *
Chris@0 391 * Dependencies are saved in the field configuration entity and are used to
Chris@0 392 * determine configuration synchronization order. For example, if the field
Chris@0 393 * type's default value is a content entity, this method should return an
Chris@0 394 * array of dependencies listing the content entities.
Chris@0 395 *
Chris@0 396 * @param \Drupal\Core\Field\FieldDefinitionInterface $field_definition
Chris@0 397 * The field definition.
Chris@0 398 *
Chris@0 399 * @return array
Chris@0 400 * An array of dependencies grouped by type (config, content, module,
Chris@0 401 * theme). For example:
Chris@0 402 * @code
Chris@0 403 * array(
Chris@0 404 * 'config' => array('user.role.anonymous', 'user.role.authenticated'),
Chris@0 405 * 'content' => array('node:article:f0a189e6-55fb-47fb-8005-5bef81c44d6d'),
Chris@0 406 * 'module' => array('node', 'user'),
Chris@0 407 * 'theme' => array('seven'),
Chris@0 408 * );
Chris@0 409 * @endcode
Chris@0 410 *
Chris@0 411 * @see \Drupal\Core\Config\Entity\ConfigDependencyManager
Chris@0 412 * @see \Drupal\Core\Config\Entity\ConfigEntityInterface::getConfigDependencyName()
Chris@0 413 */
Chris@0 414 public static function calculateDependencies(FieldDefinitionInterface $field_definition);
Chris@0 415
Chris@0 416 /**
Chris@0 417 * Calculates dependencies for field items on the storage level.
Chris@0 418 *
Chris@0 419 * Dependencies are saved in the field storage configuration entity and are
Chris@0 420 * used to determine configuration synchronization order. For example, if the
Chris@0 421 * field type storage depends on a particular entity type, this method should
Chris@0 422 * return an array of dependencies listing the module that provides the entity
Chris@0 423 * type.
Chris@0 424 *
Chris@0 425 * Dependencies returned from this method are stored in field storage
Chris@0 426 * configuration and are always considered hard dependencies. If the
Chris@0 427 * dependency is removed the field storage configuration must be deleted.
Chris@0 428 *
Chris@0 429 * @param \Drupal\Core\Field\FieldStorageDefinitionInterface $field_storage_definition
Chris@0 430 * The field storage definition.
Chris@0 431 *
Chris@0 432 * @return array
Chris@0 433 * An array of dependencies grouped by type (config, content, module,
Chris@0 434 * theme). For example:
Chris@0 435 * @code
Chris@0 436 * [
Chris@0 437 * 'config' => ['user.role.anonymous', 'user.role.authenticated'],
Chris@0 438 * 'content' => ['node:article:f0a189e6-55fb-47fb-8005-5bef81c44d6d'],
Chris@0 439 * 'module' => ['node', 'user'],
Chris@0 440 * 'theme' => ['seven'],
Chris@0 441 * ];
Chris@0 442 * @endcode
Chris@0 443 *
Chris@0 444 * @see \Drupal\Core\Config\Entity\ConfigDependencyManager
Chris@0 445 * @see \Drupal\Core\Config\Entity\ConfigEntityInterface::getConfigDependencyName()
Chris@0 446 */
Chris@0 447 public static function calculateStorageDependencies(FieldStorageDefinitionInterface $field_storage_definition);
Chris@0 448
Chris@0 449 /**
Chris@0 450 * Informs the plugin that a dependency of the field will be deleted.
Chris@0 451 *
Chris@0 452 * @param \Drupal\Core\Field\FieldDefinitionInterface $field_definition
Chris@0 453 * The field definition.
Chris@0 454 * @param array $dependencies
Chris@0 455 * An array of dependencies that will be deleted keyed by dependency type.
Chris@0 456 * Dependency types are, for example, entity, module and theme.
Chris@0 457 *
Chris@0 458 * @return bool
Chris@0 459 * TRUE if the field definition has been changed as a result, FALSE if not.
Chris@0 460 *
Chris@0 461 * @see \Drupal\Core\Config\ConfigEntityInterface::onDependencyRemoval()
Chris@0 462 */
Chris@0 463 public static function onDependencyRemoval(FieldDefinitionInterface $field_definition, array $dependencies);
Chris@0 464
Chris@0 465 }