3 namespace Drupal\Core\Entity;
6 * Interface for entities having fields.
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.
15 * When implementing this interface which extends Traversable, make sure to list
16 * IteratorAggregate or Iterator before this interface in the implements clause.
18 * @see \Drupal\Core\TypedData\TypedDataManager
19 * @see \Drupal\Core\Field\FieldItemListInterface
23 interface FieldableEntityInterface extends EntityInterface {
26 * Provides base field definitions for an entity type.
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:
32 * $fields['name'] = BaseFieldDefinition::create('string')
33 * ->setLabel(t('Name'));
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().
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.
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.
48 * @return \Drupal\Core\Field\FieldDefinitionInterface[]
49 * An array of base field definitions for the entity type, keyed by field
52 * @see \Drupal\Core\Entity\EntityManagerInterface::getFieldDefinitions()
53 * @see \Drupal\Core\Entity\FieldableEntityInterface::bundleFieldDefinitions()
55 public static function baseFieldDefinitions(EntityTypeInterface $entity_type);
58 * Provides field definitions for a specific bundle.
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
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
82 * @param \Drupal\Core\Field\FieldDefinitionInterface[] $base_field_definitions
83 * The list of base field definitions.
85 * @return \Drupal\Core\Field\FieldDefinitionInterface[]
86 * An array of bundle field definitions, keyed by field name.
88 * @see \Drupal\Core\Entity\EntityManagerInterface::getFieldDefinitions()
89 * @see \Drupal\Core\Entity\FieldableEntityInterface::baseFieldDefinitions()
91 * @todo WARNING: This method will be changed in
92 * https://www.drupal.org/node/2346347.
94 public static function bundleFieldDefinitions(EntityTypeInterface $entity_type, $bundle, array $base_field_definitions);
97 * Determines whether the entity has a field with the given name.
99 * @param string $field_name
103 * TRUE if the entity has a field with the given name. FALSE otherwise.
105 public function hasField($field_name);
108 * Gets the definition of a contained field.
110 * @param string $name
111 * The name of the field.
113 * @return \Drupal\Core\Field\FieldDefinitionInterface|null
114 * The definition of the field or null if the field does not exist.
116 public function getFieldDefinition($name);
119 * Gets an array of field definitions of all contained fields.
121 * @return \Drupal\Core\Field\FieldDefinitionInterface[]
122 * An array of field definitions, keyed by field name.
124 * @see \Drupal\Core\Entity\EntityManagerInterface::getFieldDefinitions()
126 public function getFieldDefinitions();
129 * Gets an array of all field values.
131 * Gets an array of plain field values, including only non-computed values.
132 * Note that the structure varies by entity type and bundle.
135 * An array of field values, keyed by field name.
137 public function toArray();
140 * Gets a field item list.
142 * @param string $field_name
143 * The name of the field to get; e.g., 'title' or 'name'.
145 * @return \Drupal\Core\Field\FieldItemListInterface
146 * The field item list, containing the field items.
148 * @throws \InvalidArgumentException
149 * If an invalid field name is given.
151 public function get($field_name);
154 * Sets a field value.
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.
167 * @throws \InvalidArgumentException
168 * If the specified field does not exist.
170 public function set($field_name, $value, $notify = TRUE);
173 * Gets an array of all field item lists.
175 * @param bool $include_computed
176 * If set to TRUE, computed fields are included. Defaults to TRUE.
178 * @return \Drupal\Core\Field\FieldItemListInterface[]
179 * An array of field item lists implementing, keyed by field name.
181 public function getFields($include_computed = TRUE);
184 * Gets an array of field item lists for translatable fields.
186 * @param bool $include_computed
187 * If set to TRUE, computed fields are included. Defaults to TRUE.
189 * @return \Drupal\Core\Field\FieldItemListInterface[]
190 * An array of field item lists implementing, keyed by field name.
192 public function getTranslatableFields($include_computed = TRUE);
195 * Reacts to changes to a field.
197 * Note that this is invoked after any changes have been applied.
199 * @param string $field_name
200 * The name of the field which is changed.
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.
210 public function onChange($field_name);
213 * Validates the currently set values.
215 * @return \Drupal\Core\Entity\EntityConstraintViolationListInterface
216 * A list of constraint violations. If the list is empty, validation
219 public function validate();
222 * Checks whether entity validation is required before saving the entity.
225 * TRUE if validation is required, FALSE if not.
227 public function isValidationRequired();
230 * Sets whether entity validation is required before saving the entity.
232 * @param bool $required
233 * TRUE if validation is required, FALSE otherwise.
237 public function setValidationRequired($required);