Chris@0: <?php
Chris@0: 
Chris@0: namespace Drupal\Core\Field;
Chris@0: 
Chris@0: use Drupal\Core\Form\FormStateInterface;
Chris@0: use Drupal\Core\TypedData\ComplexDataInterface;
Chris@0: 
Chris@0: /**
Chris@0:  * Interface for entity field items.
Chris@0:  *
Chris@0:  * Entity field items are typed data objects containing the field values, i.e.
Chris@0:  * implementing the ComplexDataInterface.
Chris@0:  *
Chris@0:  * When implementing this interface which extends Traversable, make sure to list
Chris@0:  * IteratorAggregate or Iterator before this interface in the implements clause.
Chris@0:  *
Chris@0:  * @see \Drupal\Core\Field\FieldItemListInterface
Chris@0:  * @see \Drupal\Core\Field\FieldItemBase
Chris@0:  * @ingroup field_types
Chris@0:  */
Chris@0: interface FieldItemInterface extends ComplexDataInterface {
Chris@0: 
Chris@0:   /**
Chris@0:    * Defines field item properties.
Chris@0:    *
Chris@0:    * Properties that are required to constitute a valid, non-empty item should
Chris@0:    * be denoted with \Drupal\Core\TypedData\DataDefinition::setRequired().
Chris@0:    *
Chris@0:    * @return \Drupal\Core\TypedData\DataDefinitionInterface[]
Chris@0:    *   An array of property definitions of contained properties, keyed by
Chris@0:    *   property name.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Field\BaseFieldDefinition
Chris@0:    */
Chris@0:   public static function propertyDefinitions(FieldStorageDefinitionInterface $field_definition);
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the name of the main property, if any.
Chris@0:    *
Chris@0:    * Some field items consist mainly of one main property, e.g. the value of a
Chris@16:    * text field or the target_id of an entity reference. If the field item has
Chris@16:    * no main property, the method returns NULL.
Chris@0:    *
Chris@0:    * @return string|null
Chris@0:    *   The name of the value property, or NULL if there is none.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Field\BaseFieldDefinition
Chris@0:    */
Chris@0:   public static function mainPropertyName();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the schema for the field.
Chris@0:    *
Chris@0:    * This method is static because the field schema information is needed on
Chris@0:    * creation of the field. FieldItemInterface objects instantiated at that
Chris@0:    * time are not reliable as field settings might be missing.
Chris@0:    *
Chris@0:    * Computed fields having no schema should return an empty array.
Chris@0:    *
Chris@0:    * @param \Drupal\Core\Field\FieldStorageDefinitionInterface $field_definition
Chris@0:    *   The field definition.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An empty array if there is no schema, or an associative array with the
Chris@0:    *   following key/value pairs:
Chris@0:    *   - columns: An array of Schema API column specifications, keyed by column
Chris@0:    *     name. The columns need to be a subset of the properties defined in
Chris@0:    *     propertyDefinitions(). The 'not null' property is ignored if present,
Chris@0:    *     as it is determined automatically by the storage controller depending
Chris@0:    *     on the table layout and the property definitions. It is recommended to
Chris@0:    *     avoid having the column definitions depend on field settings when
Chris@0:    *     possible. No assumptions should be made on how storage engines
Chris@0:    *     internally use the original column name to structure their storage.
Chris@0:    *   - unique keys: (optional) An array of Schema API unique key definitions.
Chris@0:    *     Only columns that appear in the 'columns' array are allowed.
Chris@0:    *   - indexes: (optional) An array of Schema API index definitions. Only
Chris@0:    *     columns that appear in the 'columns' array are allowed. Those indexes
Chris@0:    *     will be used as default indexes. Field definitions can specify
Chris@0:    *     additional indexes or, at their own risk, modify the default indexes
Chris@0:    *     specified by the field-type module. Some storage engines might not
Chris@0:    *     support indexes.
Chris@0:    *   - foreign keys: (optional) An array of Schema API foreign key
Chris@0:    *     definitions. Note, however, that the field data is not necessarily
Chris@0:    *     stored in SQL. Also, the possible usage is limited, as you cannot
Chris@0:    *     specify another field as related, only existing SQL tables,
Chris@0:    *     such as {taxonomy_term_data}.
Chris@0:    */
Chris@0:   public static function schema(FieldStorageDefinitionInterface $field_definition);
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets the entity that field belongs to.
Chris@0:    *
Chris@0:    * @return \Drupal\Core\Entity\FieldableEntityInterface
Chris@0:    *   The entity object.
Chris@0:    */
Chris@0:   public function getEntity();
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets the langcode of the field values held in the object.
Chris@0:    *
Chris@0:    * @return string
Chris@0:    *   The langcode.
Chris@0:    */
Chris@0:   public function getLangcode();
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets the field definition.
Chris@0:    *
Chris@0:    * @return \Drupal\Core\Field\FieldDefinitionInterface
Chris@0:    *   The field definition.
Chris@0:    */
Chris@0:   public function getFieldDefinition();
Chris@0: 
Chris@0:   /**
Chris@0:    * Magic method: Gets a property value.
Chris@0:    *
Chris@0:    * @param string $property_name
Chris@0:    *   The name of the property to get; e.g., 'title' or 'name'.
Chris@0:    *
Chris@0:    * @return mixed
Chris@0:    *   The property value.
Chris@0:    *
Chris@0:    * @throws \InvalidArgumentException
Chris@0:    *   If a not existing property is accessed.
Chris@0:    */
Chris@0:   public function __get($property_name);
Chris@0: 
Chris@0:   /**
Chris@0:    * Magic method: Sets a property value.
Chris@0:    *
Chris@0:    * @param string $property_name
Chris@0:    *   The name of the property to set; e.g., 'title' or 'name'.
Chris@0:    * @param mixed $value
Chris@0:    *   The value to set, or NULL to unset the property. Optionally, a typed
Chris@0:    *   data object implementing Drupal\Core\TypedData\TypedDataInterface may be
Chris@0:    *   passed instead of a plain value.
Chris@0:    *
Chris@0:    * @throws \InvalidArgumentException
Chris@0:    *   If a not existing property is set.
Chris@0:    */
Chris@0:   public function __set($property_name, $value);
Chris@0: 
Chris@0:   /**
Chris@0:    * Magic method: Determines whether a property is set.
Chris@0:    *
Chris@0:    * @param string $property_name
Chris@0:    *   The name of the property to get; e.g., 'title' or 'name'.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   Returns TRUE if the property exists and is set, FALSE otherwise.
Chris@0:    */
Chris@0:   public function __isset($property_name);
Chris@0: 
Chris@0:   /**
Chris@0:    * Magic method: Unsets a property.
Chris@0:    *
Chris@0:    * @param string $property_name
Chris@0:    *   The name of the property to get; e.g., 'title' or 'name'.
Chris@0:    */
Chris@0:   public function __unset($property_name);
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns a renderable array for a single field item.
Chris@0:    *
Chris@0:    * @param array $display_options
Chris@0:    *   Can be either the name of a view mode, or an array of display settings.
Chris@0:    *   See EntityViewBuilderInterface::viewField() for more information.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   A renderable array for the field item.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Entity\EntityViewBuilderInterface::viewField()
Chris@0:    * @see \Drupal\Core\Entity\EntityViewBuilderInterface::viewFieldItem()
Chris@0:    * @see \Drupal\Core\Field\FieldItemListInterface::view()
Chris@0:    */
Chris@0:   public function view($display_options = []);
Chris@0: 
Chris@0:   /**
Chris@0:    * Defines custom presave behavior for field values.
Chris@0:    *
Chris@0:    * This method is called during the process of saving an entity, just before
Chris@0:    * values are written into storage. When storing a new entity, its identifier
Chris@0:    * will not be available yet. This should be used to massage item property
Chris@0:    * values or perform any other operation that needs to happen before values
Chris@0:    * are stored. For instance this is the proper phase to auto-create a new
Chris@0:    * entity for an entity reference field item, because this way it will be
Chris@0:    * possible to store the referenced entity identifier.
Chris@0:    */
Chris@0:   public function preSave();
Chris@0: 
Chris@0:   /**
Chris@0:    * Defines custom post-save behavior for field values.
Chris@0:    *
Chris@0:    * This method is called during the process of saving an entity, just after
Chris@0:    * values are written into storage. This is useful mostly when the business
Chris@0:    * logic to be implemented always requires the entity identifier, even when
Chris@0:    * storing a new entity. For instance, when implementing circular entity
Chris@0:    * references, the referenced entity will be created on pre-save with a dummy
Chris@0:    * value for the referring entity identifier, which will be updated with the
Chris@0:    * actual one on post-save.
Chris@0:    *
Chris@0:    * In the rare cases where item properties depend on the entity identifier,
Chris@0:    * massaging logic will have to be implemented on post-save and returning TRUE
Chris@0:    * will allow them to be rewritten to the storage with the updated values.
Chris@0:    *
Chris@0:    * @param bool $update
Chris@0:    *   Specifies whether the entity is being updated or created.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   Whether field items should be rewritten to the storage as a consequence
Chris@0:    *   of the logic implemented by the custom behavior.
Chris@0:    */
Chris@0:   public function postSave($update);
Chris@0: 
Chris@0:   /**
Chris@0:    * Defines custom delete behavior for field values.
Chris@0:    *
Chris@0:    * This method is called during the process of deleting an entity, just before
Chris@0:    * values are deleted from storage.
Chris@0:    */
Chris@0:   public function delete();
Chris@0: 
Chris@0:   /**
Chris@0:    * Defines custom revision delete behavior for field values.
Chris@0:    *
Chris@0:    * This method is called from during the process of deleting an entity
Chris@0:    * revision, just before the field values are deleted from storage. It is only
Chris@0:    * called for entity types that support revisioning.
Chris@0:    */
Chris@0:   public function deleteRevision();
Chris@0: 
Chris@0:   /**
Chris@0:    * Generates placeholder field values.
Chris@0:    *
Chris@0:    * Useful when populating site with placeholder content during site building
Chris@0:    * or profiling.
Chris@0:    *
Chris@0:    * @param \Drupal\Core\Field\FieldDefinitionInterface $field_definition
Chris@0:    *   The field definition.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An associative array of values.
Chris@0:    */
Chris@0:   public static function generateSampleValue(FieldDefinitionInterface $field_definition);
Chris@0: 
Chris@0:   /**
Chris@0:    * Defines the storage-level settings for this plugin.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   A list of default settings, keyed by the setting name.
Chris@0:    */
Chris@0:   public static function defaultStorageSettings();
Chris@0: 
Chris@0:   /**
Chris@0:    * Defines the field-level settings for this plugin.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   A list of default settings, keyed by the setting name.
Chris@0:    */
Chris@0:   public static function defaultFieldSettings();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns a settings array that can be stored as a configuration value.
Chris@0:    *
Chris@0:    * For all use cases where field settings are stored and managed as
Chris@0:    * configuration, this method is used to map from the field type's
Chris@0:    * representation of its settings to a representation compatible with
Chris@0:    * deployable configuration. This includes:
Chris@0:    * - Array keys at any depth must not contain a ".".
Chris@0:    * - Ideally, array keys at any depth are either numeric or can be enumerated
Chris@0:    *   as a "mapping" within the configuration schema. While not strictly
Chris@0:    *   required, this simplifies configuration translation UIs, configuration
Chris@0:    *   migrations between Drupal versions, and other use cases.
Chris@0:    * - To support configuration deployments, references to content entities
Chris@0:    *   must use UUIDs rather than local IDs.
Chris@0:    *
Chris@0:    * An example of a conversion between representations might be an
Chris@0:    * "allowed_values" setting that's structured by the field type as a
Chris@0:    * \Drupal\Core\TypedData\OptionsProviderInterface::getPossibleOptions()
Chris@0:    * result (i.e., values as keys and labels as values). For such a use case,
Chris@0:    * in order to comply with the above, this method could convert that
Chris@0:    * representation to a numerically indexed array whose values are sub-arrays
Chris@0:    * with the schema definable keys of "value" and "label".
Chris@0:    *
Chris@0:    * @param array $settings
Chris@0:    *   The field's settings in the field type's canonical representation.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array (either the unmodified $settings or a modified representation)
Chris@0:    *   that is suitable for storing as a deployable configuration value.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Config\Config::set()
Chris@0:    */
Chris@0:   public static function storageSettingsToConfigData(array $settings);
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns a settings array in the field type's canonical representation.
Chris@0:    *
Chris@0:    * This function does the inverse of static::storageSettingsToConfigData(). It's
Chris@0:    * called when loading a field's settings from a configuration object.
Chris@0:    *
Chris@0:    * @param array $settings
Chris@0:    *   The field's settings, as it is stored within a configuration object.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   The settings, in the representation expected by the field type and code
Chris@0:    *   that interacts with it.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Field\FieldItemInterface::storageSettingsToConfigData()
Chris@0:    */
Chris@0:   public static function storageSettingsFromConfigData(array $settings);
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns a settings array that can be stored as a configuration value.
Chris@0:    *
Chris@0:    * Same as static::storageSettingsToConfigData(), but for the field's settings.
Chris@0:    *
Chris@0:    * @param array $settings
Chris@0:    *   The field's settings in the field type's canonical representation.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array (either the unmodified $settings or a modified representation)
Chris@0:    *   that is suitable for storing as a deployable configuration value.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Field\FieldItemInterface::storageSettingsToConfigData()
Chris@0:    */
Chris@0:   public static function fieldSettingsToConfigData(array $settings);
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns a settings array in the field type's canonical representation.
Chris@0:    *
Chris@0:    * This function does the inverse of static::fieldSettingsToConfigData().
Chris@0:    * It's called when loading a field's settings from a configuration
Chris@0:    * object.
Chris@0:    *
Chris@0:    * @param array $settings
Chris@0:    *   The field's settings, as it is stored within a configuration
Chris@0:    *   object.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   The field settings, in the representation expected by the field type
Chris@0:    *   and code that interacts with it.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Field\FieldItemInterface::fieldSettingsToConfigData()
Chris@0:    */
Chris@0:   public static function fieldSettingsFromConfigData(array $settings);
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns a form for the storage-level settings.
Chris@0:    *
Chris@0:    * Invoked from \Drupal\field_ui\Form\FieldStorageConfigEditForm to allow
Chris@0:    * administrators to configure storage-level settings.
Chris@0:    *
Chris@0:    * Field storage might reject settings changes that affect the field
Chris@0:    * storage schema if the storage already has data. When the $has_data
Chris@0:    * parameter is TRUE, the form should not allow changing the settings that
Chris@0:    * take part in the schema() method. It is recommended to set #access to
Chris@0:    * FALSE on the corresponding elements.
Chris@0:    *
Chris@0:    * @param array $form
Chris@0:    *   The form where the settings form is being included in.
Chris@0:    * @param \Drupal\Core\Form\FormStateInterface $form_state
Chris@0:    *   The form state of the (entire) configuration form.
Chris@0:    * @param bool $has_data
Chris@0:    *   TRUE if the field already has data, FALSE if not.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   The form definition for the field settings.
Chris@0:    */
Chris@0:   public function storageSettingsForm(array &$form, FormStateInterface $form_state, $has_data);
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns a form for the field-level settings.
Chris@0:    *
Chris@0:    * Invoked from \Drupal\field_ui\Form\FieldConfigEditForm to allow
Chris@0:    * administrators to configure field-level settings.
Chris@0:    *
Chris@0:    * @param array $form
Chris@0:    *   The form where the settings form is being included in.
Chris@0:    * @param \Drupal\Core\Form\FormStateInterface $form_state
Chris@0:    *   The form state of the (entire) configuration form.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   The form definition for the field settings.
Chris@0:    */
Chris@0:   public function fieldSettingsForm(array $form, FormStateInterface $form_state);
Chris@0: 
Chris@0:   /**
Chris@0:    * Calculates dependencies for field items.
Chris@0:    *
Chris@0:    * Dependencies are saved in the field configuration entity and are used to
Chris@0:    * determine configuration synchronization order. For example, if the field
Chris@0:    * type's default value is a content entity, this method should return an
Chris@0:    * array of dependencies listing the content entities.
Chris@0:    *
Chris@0:    * @param \Drupal\Core\Field\FieldDefinitionInterface $field_definition
Chris@0:    *   The field definition.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of dependencies grouped by type (config, content, module,
Chris@0:    *   theme). For example:
Chris@0:    *   @code
Chris@0:    *   array(
Chris@0:    *     'config' => array('user.role.anonymous', 'user.role.authenticated'),
Chris@0:    *     'content' => array('node:article:f0a189e6-55fb-47fb-8005-5bef81c44d6d'),
Chris@0:    *     'module' => array('node', 'user'),
Chris@0:    *     'theme' => array('seven'),
Chris@0:    *   );
Chris@0:    *   @endcode
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Config\Entity\ConfigDependencyManager
Chris@0:    * @see \Drupal\Core\Config\Entity\ConfigEntityInterface::getConfigDependencyName()
Chris@0:    */
Chris@0:   public static function calculateDependencies(FieldDefinitionInterface $field_definition);
Chris@0: 
Chris@0:   /**
Chris@0:    * Calculates dependencies for field items on the storage level.
Chris@0:    *
Chris@0:    * Dependencies are saved in the field storage configuration entity and are
Chris@0:    * used to determine configuration synchronization order. For example, if the
Chris@0:    * field type storage depends on a particular entity type, this method should
Chris@0:    * return an array of dependencies listing the module that provides the entity
Chris@0:    * type.
Chris@0:    *
Chris@0:    * Dependencies returned from this method are stored in field storage
Chris@0:    * configuration and are always considered hard dependencies. If the
Chris@0:    * dependency is removed the field storage configuration must be deleted.
Chris@0:    *
Chris@0:    * @param \Drupal\Core\Field\FieldStorageDefinitionInterface $field_storage_definition
Chris@0:    *   The field storage definition.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of dependencies grouped by type (config, content, module,
Chris@0:    *   theme). For example:
Chris@0:    *   @code
Chris@0:    *   [
Chris@0:    *     'config' => ['user.role.anonymous', 'user.role.authenticated'],
Chris@0:    *     'content' => ['node:article:f0a189e6-55fb-47fb-8005-5bef81c44d6d'],
Chris@0:    *     'module' => ['node', 'user'],
Chris@0:    *     'theme' => ['seven'],
Chris@0:    *   ];
Chris@0:    *   @endcode
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Config\Entity\ConfigDependencyManager
Chris@0:    * @see \Drupal\Core\Config\Entity\ConfigEntityInterface::getConfigDependencyName()
Chris@0:    */
Chris@0:   public static function calculateStorageDependencies(FieldStorageDefinitionInterface $field_storage_definition);
Chris@0: 
Chris@0:   /**
Chris@0:    * Informs the plugin that a dependency of the field will be deleted.
Chris@0:    *
Chris@0:    * @param \Drupal\Core\Field\FieldDefinitionInterface $field_definition
Chris@0:    *   The field definition.
Chris@0:    * @param array $dependencies
Chris@0:    *   An array of dependencies that will be deleted keyed by dependency type.
Chris@0:    *   Dependency types are, for example, entity, module and theme.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if the field definition has been changed as a result, FALSE if not.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Config\ConfigEntityInterface::onDependencyRemoval()
Chris@0:    */
Chris@0:   public static function onDependencyRemoval(FieldDefinitionInterface $field_definition, array $dependencies);
Chris@0: 
Chris@0: }