Chris@0: <?php
Chris@0: 
Chris@0: namespace Drupal\Core\Entity;
Chris@0: 
Chris@0: /**
Chris@0:  * Interface for entities having fields.
Chris@0:  *
Chris@0:  * This interface builds upon the general interfaces provided by the typed data
Chris@0:  * API, while extending them with entity-specific additions. I.e., fieldable
Chris@0:  * entities implement the ComplexDataInterface among others, thus it is complex
Chris@0:  * data containing fields as its data properties. The contained fields have to
Chris@0:  * implement \Drupal\Core\Field\FieldItemListInterface, which builds upon typed
Chris@0:  * data interfaces as well.
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\TypedData\TypedDataManager
Chris@0:  * @see \Drupal\Core\Field\FieldItemListInterface
Chris@0:  *
Chris@0:  * @ingroup entity_api
Chris@0:  */
Chris@0: interface FieldableEntityInterface extends EntityInterface {
Chris@0: 
Chris@0:   /**
Chris@0:    * Provides base field definitions for an entity type.
Chris@0:    *
Chris@0:    * Implementations typically use the class
Chris@0:    * \Drupal\Core\Field\BaseFieldDefinition for creating the field definitions;
Chris@0:    * for example a 'name' field could be defined as the following:
Chris@0:    * @code
Chris@0:    * $fields['name'] = BaseFieldDefinition::create('string')
Chris@0:    *   ->setLabel(t('Name'));
Chris@0:    * @endcode
Chris@0:    *
Chris@0:    * By definition, base fields are fields that exist for every bundle. To
Chris@0:    * provide definitions for fields that should only exist on some bundles, use
Chris@0:    * \Drupal\Core\Entity\FieldableEntityInterface::bundleFieldDefinitions().
Chris@0:    *
Chris@0:    * The definitions returned by this function can be overridden for all
Chris@0:    * bundles by hook_entity_base_field_info_alter() or overridden on a
Chris@0:    * per-bundle basis via 'base_field_override' configuration entities.
Chris@0:    *
Chris@0:    * @param \Drupal\Core\Entity\EntityTypeInterface $entity_type
Chris@0:    *   The entity type definition. Useful when a single class is used for multiple,
Chris@0:    *   possibly dynamic entity types.
Chris@0:    *
Chris@0:    * @return \Drupal\Core\Field\FieldDefinitionInterface[]
Chris@0:    *   An array of base field definitions for the entity type, keyed by field
Chris@0:    *   name.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Entity\EntityManagerInterface::getFieldDefinitions()
Chris@0:    * @see \Drupal\Core\Entity\FieldableEntityInterface::bundleFieldDefinitions()
Chris@0:    */
Chris@0:   public static function baseFieldDefinitions(EntityTypeInterface $entity_type);
Chris@0: 
Chris@0:   /**
Chris@0:    * Provides field definitions for a specific bundle.
Chris@0:    *
Chris@0:    * This function can return definitions both for bundle fields (fields that
Chris@0:    * are not defined in $base_field_definitions, and therefore might not exist
Chris@0:    * on some bundles) as well as bundle-specific overrides of base fields
Chris@0:    * (fields that are defined in $base_field_definitions, and therefore exist
Chris@0:    * for all bundles). However, bundle-specific base field overrides can also
Chris@0:    * be provided by 'base_field_override' configuration entities, and that is
Chris@0:    * the recommended approach except in cases where an entity type needs to
Chris@0:    * provide a bundle-specific base field override that is decoupled from
Chris@0:    * configuration. Note that for most entity types, the bundles themselves are
Chris@0:    * derived from configuration (e.g., 'node' bundles are managed via
Chris@0:    * 'node_type' configuration entities), so decoupling bundle-specific base
Chris@0:    * field overrides from configuration only makes sense for entity types that
Chris@0:    * also decouple their bundles from configuration. In cases where both this
Chris@0:    * function returns a bundle-specific override of a base field and a
Chris@0:    * 'base_field_override' configuration entity exists, the latter takes
Chris@0:    * precedence.
Chris@0:    *
Chris@0:    * @param \Drupal\Core\Entity\EntityTypeInterface $entity_type
Chris@0:    *   The entity type definition. Useful when a single class is used for multiple,
Chris@0:    *   possibly dynamic entity types.
Chris@0:    * @param string $bundle
Chris@0:    *   The bundle.
Chris@0:    * @param \Drupal\Core\Field\FieldDefinitionInterface[] $base_field_definitions
Chris@0:    *   The list of base field definitions.
Chris@0:    *
Chris@0:    * @return \Drupal\Core\Field\FieldDefinitionInterface[]
Chris@0:    *   An array of bundle field definitions, keyed by field name.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Entity\EntityManagerInterface::getFieldDefinitions()
Chris@0:    * @see \Drupal\Core\Entity\FieldableEntityInterface::baseFieldDefinitions()
Chris@0:    *
Chris@0:    * @todo WARNING: This method will be changed in
Chris@0:    *   https://www.drupal.org/node/2346347.
Chris@0:    */
Chris@0:   public static function bundleFieldDefinitions(EntityTypeInterface $entity_type, $bundle, array $base_field_definitions);
Chris@0: 
Chris@0:   /**
Chris@0:    * Determines whether the entity has a field with the given name.
Chris@0:    *
Chris@0:    * @param string $field_name
Chris@0:    *   The field name.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if the entity has a field with the given name. FALSE otherwise.
Chris@0:    */
Chris@0:   public function hasField($field_name);
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets the definition of a contained field.
Chris@0:    *
Chris@0:    * @param string $name
Chris@0:    *   The name of the field.
Chris@0:    *
Chris@0:    * @return \Drupal\Core\Field\FieldDefinitionInterface|null
Chris@0:    *   The definition of the field or null if the field does not exist.
Chris@0:    */
Chris@0:   public function getFieldDefinition($name);
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets an array of field definitions of all contained fields.
Chris@0:    *
Chris@0:    * @return \Drupal\Core\Field\FieldDefinitionInterface[]
Chris@0:    *   An array of field definitions, keyed by field name.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Entity\EntityManagerInterface::getFieldDefinitions()
Chris@0:    */
Chris@0:   public function getFieldDefinitions();
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets an array of all field values.
Chris@0:    *
Chris@0:    * Gets an array of plain field values, including only non-computed values.
Chris@0:    * Note that the structure varies by entity type and bundle.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of field values, keyed by field name.
Chris@0:    */
Chris@0:   public function toArray();
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets a field item list.
Chris@0:    *
Chris@0:    * @param string $field_name
Chris@0:    *   The name of the field to get; e.g., 'title' or 'name'.
Chris@0:    *
Chris@0:    * @return \Drupal\Core\Field\FieldItemListInterface
Chris@0:    *   The field item list, containing the field items.
Chris@0:    *
Chris@0:    * @throws \InvalidArgumentException
Chris@0:    *   If an invalid field name is given.
Chris@0:    */
Chris@0:   public function get($field_name);
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets a field value.
Chris@0:    *
Chris@0:    * @param string $field_name
Chris@0:    *   The name of the field to set; e.g., 'title' or 'name'.
Chris@0:    * @param mixed $value
Chris@0:    *   The value to set, or NULL to unset the field.
Chris@0:    * @param bool $notify
Chris@0:    *   (optional) Whether to notify the entity of the change. Defaults to
Chris@0:    *   TRUE. If the update stems from the entity, set it to FALSE to avoid
Chris@0:    *   being notified again.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    *
Chris@0:    * @throws \InvalidArgumentException
Chris@0:    *   If the specified field does not exist.
Chris@0:    */
Chris@0:   public function set($field_name, $value, $notify = TRUE);
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets an array of all field item lists.
Chris@0:    *
Chris@0:    * @param bool $include_computed
Chris@0:    *   If set to TRUE, computed fields are included. Defaults to TRUE.
Chris@0:    *
Chris@0:    * @return \Drupal\Core\Field\FieldItemListInterface[]
Chris@0:    *   An array of field item lists implementing, keyed by field name.
Chris@0:    */
Chris@0:   public function getFields($include_computed = TRUE);
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets an array of field item lists for translatable fields.
Chris@0:    *
Chris@0:    * @param bool $include_computed
Chris@0:    *   If set to TRUE, computed fields are included. Defaults to TRUE.
Chris@0:    *
Chris@0:    * @return \Drupal\Core\Field\FieldItemListInterface[]
Chris@0:    *   An array of field item lists implementing, keyed by field name.
Chris@0:    */
Chris@0:   public function getTranslatableFields($include_computed = TRUE);
Chris@0: 
Chris@0:   /**
Chris@0:    * Reacts to changes to a field.
Chris@0:    *
Chris@0:    * Note that this is invoked after any changes have been applied.
Chris@0:    *
Chris@0:    * @param string $field_name
Chris@0:    *   The name of the field which is changed.
Chris@0:    *
Chris@0:    * @throws \InvalidArgumentException
Chris@0:    *   When trying to assign a value to the language field that matches an
Chris@0:    *   existing translation.
Chris@0:    * @throws \LogicException
Chris@0:    *   When trying to change:
Chris@0:    *   - The language of a translation.
Chris@0:    *   - The value of the flag identifying the default translation object.
Chris@0:    */
Chris@0:   public function onChange($field_name);
Chris@0: 
Chris@0:   /**
Chris@0:    * Validates the currently set values.
Chris@0:    *
Chris@0:    * @return \Drupal\Core\Entity\EntityConstraintViolationListInterface
Chris@0:    *   A list of constraint violations. If the list is empty, validation
Chris@0:    *   succeeded.
Chris@0:    */
Chris@0:   public function validate();
Chris@0: 
Chris@0:   /**
Chris@0:    * Checks whether entity validation is required before saving the entity.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if validation is required, FALSE if not.
Chris@0:    */
Chris@0:   public function isValidationRequired();
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets whether entity validation is required before saving the entity.
Chris@0:    *
Chris@0:    * @param bool $required
Chris@0:    *   TRUE if validation is required, FALSE otherwise.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    */
Chris@0:   public function setValidationRequired($required);
Chris@0: 
Chris@0: }