www.aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Entity/FieldableEntityInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Entity;
   4
   5 /**
   6  * Interface for entities having fields.
   7  *
   8  * This interface builds upon the general interfaces provided by the typed data
   9  * API, while extending them with entity-specific additions. I.e., fieldable
  10  * entities implement the ComplexDataInterface among others, thus it is complex
  11  * data containing fields as its data properties. The contained fields have to
  12  * implement \Drupal\Core\Field\FieldItemListInterface, which builds upon typed
  13  * data interfaces as well.
  14  *
  15  * When implementing this interface which extends Traversable, make sure to list
  16  * IteratorAggregate or Iterator before this interface in the implements clause.
  17  *
  18  * @see \Drupal\Core\TypedData\TypedDataManager
  19  * @see \Drupal\Core\Field\FieldItemListInterface
  20  *
  21  * @ingroup entity_api
  22  */
  23 interface FieldableEntityInterface extends EntityInterface {
  24
  25   /**
  26    * Provides base field definitions for an entity type.
  27    *
  28    * Implementations typically use the class
  29    * \Drupal\Core\Field\BaseFieldDefinition for creating the field definitions;
  30    * for example a 'name' field could be defined as the following:
  31    * @code
  32    * $fields['name'] = BaseFieldDefinition::create('string')
  33    *   ->setLabel(t('Name'));
  34    * @endcode
  35    *
  36    * By definition, base fields are fields that exist for every bundle. To
  37    * provide definitions for fields that should only exist on some bundles, use
  38    * \Drupal\Core\Entity\FieldableEntityInterface::bundleFieldDefinitions().
  39    *
  40    * The definitions returned by this function can be overridden for all
  41    * bundles by hook_entity_base_field_info_alter() or overridden on a
  42    * per-bundle basis via 'base_field_override' configuration entities.
  43    *
  44    * @param \Drupal\Core\Entity\EntityTypeInterface $entity_type
  45    *   The entity type definition. Useful when a single class is used for multiple,
  46    *   possibly dynamic entity types.
  47    *
  48    * @return \Drupal\Core\Field\FieldDefinitionInterface[]
  49    *   An array of base field definitions for the entity type, keyed by field
  50    *   name.
  51    *
  52    * @see \Drupal\Core\Entity\EntityManagerInterface::getFieldDefinitions()
  53    * @see \Drupal\Core\Entity\FieldableEntityInterface::bundleFieldDefinitions()
  54    */
  55   public static function baseFieldDefinitions(EntityTypeInterface $entity_type);
  56
  57   /**
  58    * Provides field definitions for a specific bundle.
  59    *
  60    * This function can return definitions both for bundle fields (fields that
  61    * are not defined in $base_field_definitions, and therefore might not exist
  62    * on some bundles) as well as bundle-specific overrides of base fields
  63    * (fields that are defined in $base_field_definitions, and therefore exist
  64    * for all bundles). However, bundle-specific base field overrides can also
  65    * be provided by 'base_field_override' configuration entities, and that is
  66    * the recommended approach except in cases where an entity type needs to
  67    * provide a bundle-specific base field override that is decoupled from
  68    * configuration. Note that for most entity types, the bundles themselves are
  69    * derived from configuration (e.g., 'node' bundles are managed via
  70    * 'node_type' configuration entities), so decoupling bundle-specific base
  71    * field overrides from configuration only makes sense for entity types that
  72    * also decouple their bundles from configuration. In cases where both this
  73    * function returns a bundle-specific override of a base field and a
  74    * 'base_field_override' configuration entity exists, the latter takes
  75    * precedence.
  76    *
  77    * @param \Drupal\Core\Entity\EntityTypeInterface $entity_type
  78    *   The entity type definition. Useful when a single class is used for multiple,
  79    *   possibly dynamic entity types.
  80    * @param string $bundle
  81    *   The bundle.
  82    * @param \Drupal\Core\Field\FieldDefinitionInterface[] $base_field_definitions
  83    *   The list of base field definitions.
  84    *
  85    * @return \Drupal\Core\Field\FieldDefinitionInterface[]
  86    *   An array of bundle field definitions, keyed by field name.
  87    *
  88    * @see \Drupal\Core\Entity\EntityManagerInterface::getFieldDefinitions()
  89    * @see \Drupal\Core\Entity\FieldableEntityInterface::baseFieldDefinitions()
  90    *
  91    * @todo WARNING: This method will be changed in
  92    *   https://www.drupal.org/node/2346347.
  93    */
  94   public static function bundleFieldDefinitions(EntityTypeInterface $entity_type, $bundle, array $base_field_definitions);
  95
  96   /**
  97    * Determines whether the entity has a field with the given name.
  98    *
  99    * @param string $field_name
 100    *   The field name.
 101    *
 102    * @return bool
 103    *   TRUE if the entity has a field with the given name. FALSE otherwise.
 104    */
 105   public function hasField($field_name);
 106
 107   /**
 108    * Gets the definition of a contained field.
 109    *
 110    * @param string $name
 111    *   The name of the field.
 112    *
 113    * @return \Drupal\Core\Field\FieldDefinitionInterface|null
 114    *   The definition of the field or null if the field does not exist.
 115    */
 116   public function getFieldDefinition($name);
 117
 118   /**
 119    * Gets an array of field definitions of all contained fields.
 120    *
 121    * @return \Drupal\Core\Field\FieldDefinitionInterface[]
 122    *   An array of field definitions, keyed by field name.
 123    *
 124    * @see \Drupal\Core\Entity\EntityManagerInterface::getFieldDefinitions()
 125    */
 126   public function getFieldDefinitions();
 127
 128   /**
 129    * Gets an array of all field values.
 130    *
 131    * Gets an array of plain field values, including only non-computed values.
 132    * Note that the structure varies by entity type and bundle.
 133    *
 134    * @return array
 135    *   An array of field values, keyed by field name.
 136    */
 137   public function toArray();
 138
 139   /**
 140    * Gets a field item list.
 141    *
 142    * @param string $field_name
 143    *   The name of the field to get; e.g., 'title' or 'name'.
 144    *
 145    * @return \Drupal\Core\Field\FieldItemListInterface
 146    *   The field item list, containing the field items.
 147    *
 148    * @throws \InvalidArgumentException
 149    *   If an invalid field name is given.
 150    */
 151   public function get($field_name);
 152
 153   /**
 154    * Sets a field value.
 155    *
 156    * @param string $field_name
 157    *   The name of the field to set; e.g., 'title' or 'name'.
 158    * @param mixed $value
 159    *   The value to set, or NULL to unset the field.
 160    * @param bool $notify
 161    *   (optional) Whether to notify the entity of the change. Defaults to
 162    *   TRUE. If the update stems from the entity, set it to FALSE to avoid
 163    *   being notified again.
 164    *
 165    * @return $this
 166    *
 167    * @throws \InvalidArgumentException
 168    *   If the specified field does not exist.
 169    */
 170   public function set($field_name, $value, $notify = TRUE);
 171
 172   /**
 173    * Gets an array of all field item lists.
 174    *
 175    * @param bool $include_computed
 176    *   If set to TRUE, computed fields are included. Defaults to TRUE.
 177    *
 178    * @return \Drupal\Core\Field\FieldItemListInterface[]
 179    *   An array of field item lists implementing, keyed by field name.
 180    */
 181   public function getFields($include_computed = TRUE);
 182
 183   /**
 184    * Gets an array of field item lists for translatable fields.
 185    *
 186    * @param bool $include_computed
 187    *   If set to TRUE, computed fields are included. Defaults to TRUE.
 188    *
 189    * @return \Drupal\Core\Field\FieldItemListInterface[]
 190    *   An array of field item lists implementing, keyed by field name.
 191    */
 192   public function getTranslatableFields($include_computed = TRUE);
 193
 194   /**
 195    * Reacts to changes to a field.
 196    *
 197    * Note that this is invoked after any changes have been applied.
 198    *
 199    * @param string $field_name
 200    *   The name of the field which is changed.
 201    *
 202    * @throws \InvalidArgumentException
 203    *   When trying to assign a value to the language field that matches an
 204    *   existing translation.
 205    * @throws \LogicException
 206    *   When trying to change:
 207    *   - The language of a translation.
 208    *   - The value of the flag identifying the default translation object.
 209    */
 210   public function onChange($field_name);
 211
 212   /**
 213    * Validates the currently set values.
 214    *
 215    * @return \Drupal\Core\Entity\EntityConstraintViolationListInterface
 216    *   A list of constraint violations. If the list is empty, validation
 217    *   succeeded.
 218    */
 219   public function validate();
 220
 221   /**
 222    * Checks whether entity validation is required before saving the entity.
 223    *
 224    * @return bool
 225    *   TRUE if validation is required, FALSE if not.
 226    */
 227   public function isValidationRequired();
 228
 229   /**
 230    * Sets whether entity validation is required before saving the entity.
 231    *
 232    * @param bool $required
 233    *   TRUE if validation is required, FALSE otherwise.
 234    *
 235    * @return $this
 236    */
 237   public function setValidationRequired($required);
 238
 239 }