Chris@0: <?php
Chris@0: 
Chris@0: namespace Drupal\Core\Field;
Chris@0: 
Chris@0: use Drupal\Core\Cache\CacheableDependencyInterface;
Chris@0: use Drupal\Core\Entity\FieldableEntityInterface;
Chris@0: use Drupal\Core\TypedData\ListDataDefinitionInterface;
Chris@0: 
Chris@0: /**
Chris@0:  * Defines an interface for entity field definitions.
Chris@0:  *
Chris@0:  * An entity field is a data object that holds the values of a particular field
Chris@0:  * for a particular entity (see \Drupal\Core\Field\FieldItemListInterface). For
Chris@0:  * example, $node_1->body and $node_2->body contain different data and therefore
Chris@0:  * are different field objects.
Chris@0:  *
Chris@0:  * In contrast, an entity field *definition* is an object that returns
Chris@0:  * information *about* a field (e.g., its type and settings) rather than its
Chris@0:  * values. As such, if all the information about $node_1->body and $node_2->body
Chris@0:  * is the same, then the same field definition object can be used to describe
Chris@0:  * both.
Chris@0:  *
Chris@0:  * It is up to the class implementing this interface to manage where the
Chris@0:  * information comes from. For example, field.module provides an implementation
Chris@0:  * based on two levels of configuration. It allows the site administrator to add
Chris@0:  * custom fields to any entity type and bundle via the "field_storage_config"
Chris@0:  * and "field_config" configuration entities. The former for storing
Chris@0:  * configuration that is independent of which entity type and bundle the field
Chris@0:  * is added to, and the latter for storing configuration that is specific to the
Chris@0:  * entity type and bundle. The class that implements "field_config"
Chris@0:  * configuration entities also implements this interface, returning information
Chris@0:  * from either itself, or from the corresponding "field_storage_config"
Chris@0:  * configuration, as appropriate.
Chris@0:  *
Chris@0:  * However, entity base fields, such as $node->title, are not managed by
Chris@0:  * field.module and its "field_storage_config"/"field_config"
Chris@0:  * configuration entities. Therefore, their definitions are provided by
Chris@0:  * different objects based on the class \Drupal\Core\Field\BaseFieldDefinition,
Chris@0:  * which implements this interface as well.
Chris@0:  *
Chris@0:  * Field definitions may fully define a concrete data object (e.g.,
Chris@0:  * $node_1->body), or may provide a best-guess definition for a data object that
Chris@0:  * might come into existence later. For example, $node_1->body and $node_2->body
Chris@0:  * may have different definitions (e.g., if the node types are different). When
Chris@0:  * adding the "body" field to a View that can return nodes of different types,
Chris@0:  * the View can get a field definition that represents the "body" field
Chris@0:  * abstractly, and present Views configuration options to the administrator
Chris@0:  * based on that abstract definition, even though that abstract definition can
Chris@0:  * differ from the concrete definition of any particular node's body field.
Chris@0:  */
Chris@0: interface FieldDefinitionInterface extends ListDataDefinitionInterface, CacheableDependencyInterface {
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the machine name of the field.
Chris@0:    *
Chris@0:    * This defines how the field data is accessed from the entity. For example,
Chris@0:    * if the field name is "foo", then $entity->foo returns its data.
Chris@0:    *
Chris@0:    * @return string
Chris@0:    *   The field name.
Chris@0:    */
Chris@0:   public function getName();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the field type.
Chris@0:    *
Chris@0:    * @return string
Chris@0:    *   The field type, i.e. the id of a field type plugin. For example 'text'.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Field\FieldTypePluginManagerInterface
Chris@0:    */
Chris@0:   public function getType();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the ID of the entity type the field is attached to.
Chris@0:    *
Chris@0:    * This method should not be confused with EntityInterface::getEntityTypeId()
Chris@0:    * (configurable fields are config entities, and thus implement both
Chris@0:    * interfaces):
Chris@0:    *   - FieldDefinitionInterface::getTargetEntityTypeId() answers "as a field,
Chris@0:    *     which entity type are you attached to?".
Chris@0:    *   - EntityInterface::getEntityTypeId() answers "as a (config) entity, what
Chris@0:    *     is your own entity type?".
Chris@0:    *
Chris@0:    * @return string
Chris@0:    *   The entity type ID.
Chris@0:    */
Chris@0:   public function getTargetEntityTypeId();
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets the bundle the field is attached to.
Chris@0:    *
Chris@0:    * This method should not be confused with EntityInterface::bundle()
Chris@0:    * (configurable fields are config entities, and thus implement both
Chris@0:    * interfaces):
Chris@0:    *   - FieldDefinitionInterface::getTargetBundle() answers "as a field,
Chris@0:    *     which bundle are you attached to?".
Chris@0:    *   - EntityInterface::bundle() answers "as a (config) entity, what
Chris@0:    *     is your own bundle?" (not relevant in our case, the config entity types
Chris@0:    *     used to store the definitions of configurable fields do not have
Chris@0:    *     bundles).
Chris@0:    *
Chris@0:    * @return string|null
Chris@0:    *   The bundle the field is defined for, or NULL if it is a base field; i.e.,
Chris@0:    *   it is not bundle-specific.
Chris@0:    */
Chris@0:   public function getTargetBundle();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns whether the display for the field can be configured.
Chris@0:    *
Chris@0:    * @param string $display_context
Chris@0:    *   The display context. Either 'view' or 'form'.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if the display for this field is configurable in the given context.
Chris@0:    *   If TRUE, the display options returned by getDisplayOptions() may be
Chris@0:    *   overridden via the respective entity display.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Entity\Display\EntityDisplayInterface
Chris@0:    */
Chris@0:   public function isDisplayConfigurable($display_context);
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the default display options for the field.
Chris@0:    *
Chris@0:    * If the field's display is configurable, the returned display options act
Chris@0:    * as default values and may be overridden via the respective entity display.
Chris@0:    * Otherwise, the display options will be applied to entity displays as is.
Chris@0:    *
Chris@0:    * @param string $display_context
Chris@0:    *   The display context. Either 'view' or 'form'.
Chris@0:    *
Chris@0:    * @return array|null
Chris@0:    *   The array of display options for the field, or NULL if the field is not
Chris@0:    *   displayed. The following key/value pairs may be present:
Chris@0:    *   - label: (string) Position of the field label. The default 'field' theme
Chris@0:    *     implementation supports the values 'inline', 'above' and 'hidden'.
Chris@0:    *     Defaults to 'above'. Only applies to 'view' context.
Chris@0:    *   - region: (string) The region the field is in, or 'hidden'. If not
Chris@0:    *     specified, the default region will be used.
Chris@0:    *   - type: (string) The plugin (widget or formatter depending on
Chris@0:    *     $display_context) to use. If not specified or if the requested plugin
Chris@0:    *     is unknown, the 'default_widget' / 'default_formatter' for the field
Chris@0:    *     type will be used. Previously 'hidden' was a valid value, it is now
Chris@0:    *     deprecated in favor of specifying 'region' => 'hidden'.
Chris@0:    *   - settings: (array) Settings for the plugin specified above. The default
Chris@0:    *     settings for the plugin will be used for settings left unspecified.
Chris@0:    *   - third_party_settings: (array) Settings provided by other extensions
Chris@0:    *     through hook_field_formatter_third_party_settings_form().
Chris@0:    *   - weight: (float) The weight of the element. Not needed if 'type' is
Chris@0:    *     'hidden'.
Chris@0:    *   The defaults of the various display options above get applied by the used
Chris@0:    *   entity display.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Entity\Display\EntityDisplayInterface
Chris@0:    */
Chris@0:   public function getDisplayOptions($display_context);
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns whether the field can be empty.
Chris@0:    *
Chris@0:    * If a field is required, an entity needs to have at least a valid,
Chris@0:    * non-empty item in that field's FieldItemList in order to pass validation.
Chris@0:    *
Chris@0:    * An item is considered empty if its isEmpty() method returns TRUE.
Chris@0:    * Typically, that is if at least one of its required properties is empty.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if the field is required.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\TypedData\Plugin\DataType\ItemList::isEmpty()
Chris@0:    * @see \Drupal\Core\Field\FieldItemInterface::isEmpty()
Chris@0:    * @see \Drupal\Core\TypedData\DataDefinitionInterface:isRequired()
Chris@0:    * @see \Drupal\Core\TypedData\TypedDataManager::getDefaultConstraints()
Chris@0:    */
Chris@0:   public function isRequired();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the default value literal for the field.
Chris@0:    *
Chris@0:    * This method retrieves the raw property assigned to the field definition.
Chris@0:    * When computing the runtime default value for a field in a given entity,
Chris@0:    * ::getDefaultValue() should be used instead.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   The default value for the field, as a numerically indexed array of items,
Chris@0:    *   each item being a property/value array (array() for no default value).
Chris@0:    *
Chris@0:    * @see FieldDefinitionInterface::getDefaultValue()
Chris@0:    * @see FieldDefinitionInterface::getDefaultValueCallback()
Chris@0:    */
Chris@0:   public function getDefaultValueLiteral();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the default value callback for the field.
Chris@0:    *
Chris@0:    * This method retrieves the raw property assigned to the field definition.
Chris@0:    * When computing the runtime default value for a field in a given entity,
Chris@0:    * ::getDefaultValue() should be used instead.
Chris@0:    *
Chris@0:    * @return string|null
Chris@0:    *   The default value callback for the field.
Chris@0:    *
Chris@0:    * @see FieldDefinitionInterface::getDefaultValue()
Chris@0:    * @see FieldDefinitionInterface::getDefaultValueLiteral()
Chris@0:    */
Chris@0:   public function getDefaultValueCallback();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the default value for the field in a newly created entity.
Chris@0:    *
Chris@0:    * This method computes the runtime default value for a field in a given
Chris@0:    * entity. To access the raw properties assigned to the field definition,
Chris@0:    * ::getDefaultValueLiteral() or ::getDefaultValueCallback() should be used
Chris@0:    * instead.
Chris@0:    *
Chris@0:    * @param \Drupal\Core\Entity\FieldableEntityInterface $entity
Chris@0:    *   The entity for which the default value is generated.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   The default value for the field, as a numerically indexed array of items,
Chris@0:    *   each item being a property/value array (array() for no default value).
Chris@0:    *
Chris@0:    * @see FieldDefinitionInterface::getDefaultValueLiteral()
Chris@0:    * @see FieldDefinitionInterface::getDefaultValueCallback()
Chris@0:    */
Chris@0:   public function getDefaultValue(FieldableEntityInterface $entity);
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns whether the field is translatable.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if the field is translatable.
Chris@0:    */
Chris@0:   public function isTranslatable();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the field storage definition.
Chris@0:    *
Chris@0:    * @return \Drupal\Core\Field\FieldStorageDefinitionInterface
Chris@0:    *   The field storage definition.
Chris@0:    */
Chris@0:   public function getFieldStorageDefinition();
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets an object that can be saved in configuration.
Chris@0:    *
Chris@0:    * Base fields are defined in code. In order to configure field definition
Chris@0:    * properties per bundle use this method to create an override that can be
Chris@0:    * saved in configuration.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Field\Entity\BaseFieldBundleOverride
Chris@0:    *
Chris@0:    * @param string $bundle
Chris@0:    *   The bundle to get the configurable field for.
Chris@0:    *
Chris@0:    * @return \Drupal\Core\Field\FieldConfigInterface
Chris@0:    */
Chris@0:   public function getConfig($bundle);
Chris@0: 
Chris@14:   /**
Chris@14:    * Returns a unique identifier for the field.
Chris@14:    *
Chris@14:    * @return string
Chris@14:    */
Chris@14:   public function getUniqueIdentifier();
Chris@14: 
Chris@0: }