3 namespace Drupal\Core\Entity;
5 use Drupal\Core\Access\AccessibleInterface;
6 use Drupal\Core\Cache\CacheableDependencyInterface;
7 use Drupal\Core\Cache\RefinableCacheableDependencyInterface;
10 * Defines a common interface for all entity objects.
14 interface EntityInterface extends AccessibleInterface, CacheableDependencyInterface, RefinableCacheableDependencyInterface {
17 * Gets the entity UUID (Universally Unique Identifier).
19 * The UUID is guaranteed to be unique and can be used to identify an entity
20 * across multiple systems.
23 * The UUID of the entity, or NULL if the entity does not have one.
25 public function uuid();
28 * Gets the identifier.
30 * @return string|int|null
31 * The entity identifier, or NULL if the object does not yet have an
37 * Gets the language of the entity.
39 * @return \Drupal\Core\Language\LanguageInterface
40 * The language object.
42 public function language();
45 * Determines whether the entity is new.
47 * Usually an entity is new if no ID exists for it yet. However, entities may
48 * be enforced to be new with existing IDs too.
51 * TRUE if the entity is new, or FALSE if the entity has already been saved.
53 * @see \Drupal\Core\Entity\EntityInterface::enforceIsNew()
55 public function isNew();
58 * Enforces an entity to be new.
60 * Allows migrations to create entities with pre-defined IDs by forcing the
61 * entity to be new before saving.
64 * (optional) Whether the entity should be forced to be new. Defaults to
69 * @see \Drupal\Core\Entity\EntityInterface::isNew()
71 public function enforceIsNew($value = TRUE);
74 * Gets the ID of the type of the entity.
79 public function getEntityTypeId();
82 * Gets the bundle of the entity.
85 * The bundle of the entity. Defaults to the entity type ID if the entity
86 * type does not make use of different bundles.
88 public function bundle();
91 * Gets the label of the entity.
94 * The label of the entity, or NULL if there is no label defined.
96 public function label();
99 * Gets the URL object for the entity.
102 * The link relationship type, for example: canonical or edit-form.
103 * @param array $options
104 * See \Drupal\Core\Routing\UrlGeneratorInterface::generateFromRoute() for
105 * the available options.
107 * @return \Drupal\Core\Url
110 * @deprecated in Drupal 8.0.0, intended to be removed in Drupal 9.0.0
111 * Use \Drupal\Core\Entity\EntityInterface::toUrl() instead.
113 * @see https://www.drupal.org/node/2614344
114 * @see \Drupal\Core\Entity\EntityInterface::toUrl
116 public function urlInfo($rel = 'canonical', array $options = []);
119 * Gets the URL object for the entity.
121 * The entity must have an id already. Content entities usually get their IDs
124 * URI templates might be set in the links array in an annotation, for
128 * "canonical" = "/node/{node}",
129 * "edit-form" = "/node/{node}/edit",
130 * "version-history" = "/node/{node}/revisions"
133 * or specified in a callback function set like:
135 * uri_callback = "comment_uri",
137 * If the path is not set in the links array, the uri_callback function is
138 * used for setting the path. If this does not exist and the link relationship
139 * type is canonical, the path is set using the default template:
140 * entity/entityType/id.
143 * The link relationship type, for example: canonical or edit-form.
144 * @param array $options
145 * See \Drupal\Core\Routing\UrlGeneratorInterface::generateFromRoute() for
146 * the available options.
148 * @return \Drupal\Core\Url
151 * @throws \Drupal\Core\Entity\EntityMalformedException
152 * @throws \Drupal\Core\Entity\Exception\UndefinedLinkTemplateException
154 public function toUrl($rel = 'canonical', array $options = []);
157 * Gets the public URL for this entity.
160 * The link relationship type, for example: canonical or edit-form.
161 * @param array $options
162 * See \Drupal\Core\Routing\UrlGeneratorInterface::generateFromRoute() for
163 * the available options.
166 * The URL for this entity.
168 * @deprecated in Drupal 8.0.0, intended to be removed in Drupal 9.0.0
169 * Please use toUrl() instead.
171 * @see https://www.drupal.org/node/2614344
172 * @see \Drupal\Core\Entity\EntityInterface::toUrl
174 public function url($rel = 'canonical', $options = []);
177 * Deprecated way of generating a link to the entity. See toLink().
179 * @param string|null $text
180 * (optional) The link text for the anchor tag as a translated string.
181 * If NULL, it will use the entity's label. Defaults to NULL.
183 * (optional) The link relationship type. Defaults to 'canonical'.
184 * @param array $options
185 * See \Drupal\Core\Routing\UrlGeneratorInterface::generateFromRoute() for
186 * the available options.
189 * An HTML string containing a link to the entity.
191 * @deprecated in Drupal 8.0.0, intended to be removed in Drupal 9.0.0
192 * Please use toLink() instead.
194 * @see https://www.drupal.org/node/2614344
195 * @see \Drupal\Core\Entity\EntityInterface::toLink
197 public function link($text = NULL, $rel = 'canonical', array $options = []);
200 * Generates the HTML for a link to this entity.
202 * @param string|null $text
203 * (optional) The link text for the anchor tag as a translated string.
204 * If NULL, it will use the entity's label. Defaults to NULL.
206 * (optional) The link relationship type. Defaults to 'canonical'.
207 * @param array $options
208 * See \Drupal\Core\Routing\UrlGeneratorInterface::generateFromRoute() for
209 * the available options.
211 * @return \Drupal\Core\Link
212 * A Link to the entity.
214 * @throws \Drupal\Core\Entity\EntityMalformedException
215 * @throws \Drupal\Core\Entity\Exception\UndefinedLinkTemplateException
217 public function toLink($text = NULL, $rel = 'canonical', array $options = []);
220 * Indicates if a link template exists for a given key.
226 * TRUE if the link template exists, FALSE otherwise.
228 public function hasLinkTemplate($key);
231 * Gets a list of URI relationships supported by this entity.
234 * An array of link relationships supported by this entity.
236 public function uriRelationships();
242 * The id of the entity to load.
245 * The entity object or NULL if there is no entity with the given ID.
247 public static function load($id);
250 * Loads one or more entities.
253 * An array of entity IDs, or NULL to load all entities.
256 * An array of entity objects indexed by their IDs.
258 public static function loadMultiple(array $ids = NULL);
261 * Constructs a new entity object, without permanently saving it.
263 * @param array $values
264 * (optional) An array of values to set, keyed by property name. If the
265 * entity type has bundles, the bundle key has to be specified.
270 public static function create(array $values = []);
273 * Saves an entity permanently.
275 * When saving existing entities, the entity is assumed to be complete,
276 * partial updates of entities are not supported.
279 * Either SAVED_NEW or SAVED_UPDATED, depending on the operation performed.
281 * @throws \Drupal\Core\Entity\EntityStorageException
282 * In case of failures an exception is thrown.
284 public function save();
287 * Deletes an entity permanently.
289 * @throws \Drupal\Core\Entity\EntityStorageException
290 * In case of failures an exception is thrown.
292 public function delete();
295 * Acts on an entity before the presave hook is invoked.
297 * Used before the entity is saved and before invoking the presave hook. Note
298 * that in case of translatable content entities this callback is only fired
299 * on their current translation. It is up to the developer to iterate
300 * over all translations if needed. This is different from its counterpart in
301 * the Field API, FieldItemListInterface::preSave(), which is fired on all
302 * field translations automatically.
303 * @todo Adjust existing implementations and the documentation according to
304 * https://www.drupal.org/node/2577609 to have a consistent API.
306 * @param \Drupal\Core\Entity\EntityStorageInterface $storage
307 * The entity storage object.
309 * @see \Drupal\Core\Field\FieldItemListInterface::preSave()
312 * When there is a problem that should prevent saving the entity.
314 public function preSave(EntityStorageInterface $storage);
317 * Acts on a saved entity before the insert or update hook is invoked.
319 * Used after the entity is saved, but before invoking the insert or update
320 * hook. Note that in case of translatable content entities this callback is
321 * only fired on their current translation. It is up to the developer to
322 * iterate over all translations if needed.
324 * @param \Drupal\Core\Entity\EntityStorageInterface $storage
325 * The entity storage object.
326 * @param bool $update
327 * TRUE if the entity has been updated, or FALSE if it has been inserted.
329 public function postSave(EntityStorageInterface $storage, $update = TRUE);
332 * Changes the values of an entity before it is created.
334 * Load defaults for example.
336 * @param \Drupal\Core\Entity\EntityStorageInterface $storage
337 * The entity storage object.
338 * @param mixed[] $values
339 * An array of values to set, keyed by property name. If the entity type has
340 * bundles the bundle key has to be specified.
342 public static function preCreate(EntityStorageInterface $storage, array &$values);
345 * Acts on a created entity before hooks are invoked.
347 * Used after the entity is created, but before saving the entity and before
348 * any of the presave hooks are invoked.
350 * See the @link entity_crud Entity CRUD topic @endlink for more information.
352 * @param \Drupal\Core\Entity\EntityStorageInterface $storage
353 * The entity storage object.
355 * @see \Drupal\Core\Entity\EntityInterface::create()
357 public function postCreate(EntityStorageInterface $storage);
360 * Acts on entities before they are deleted and before hooks are invoked.
362 * Used before the entities are deleted and before invoking the delete hook.
364 * @param \Drupal\Core\Entity\EntityStorageInterface $storage
365 * The entity storage object.
366 * @param \Drupal\Core\Entity\EntityInterface[] $entities
367 * An array of entities.
369 public static function preDelete(EntityStorageInterface $storage, array $entities);
372 * Acts on deleted entities before the delete hook is invoked.
374 * Used after the entities are deleted but before invoking the delete hook.
376 * @param \Drupal\Core\Entity\EntityStorageInterface $storage
377 * The entity storage object.
378 * @param \Drupal\Core\Entity\EntityInterface[] $entities
379 * An array of entities.
381 public static function postDelete(EntityStorageInterface $storage, array $entities);
384 * Acts on loaded entities.
386 * @param \Drupal\Core\Entity\EntityStorageInterface $storage
387 * The entity storage object.
388 * @param \Drupal\Core\Entity\EntityInterface[] $entities
389 * An array of entities.
391 public static function postLoad(EntityStorageInterface $storage, array &$entities);
394 * Creates a duplicate of the entity.
397 * A clone of $this with all identifiers unset, so saving it inserts a new
398 * entity into the storage system.
400 public function createDuplicate();
403 * Gets the entity type definition.
405 * @return \Drupal\Core\Entity\EntityTypeInterface
406 * The entity type definition.
408 public function getEntityType();
411 * Gets a list of entities referenced by this entity.
413 * @return \Drupal\Core\Entity\EntityInterface[]
414 * An array of entities.
416 public function referencedEntities();
419 * Gets the original ID.
421 * @return int|string|null
422 * The original ID, or NULL if no ID was set or for entity types that do not
425 public function getOriginalId();
428 * Returns the cache tags that should be used to invalidate caches.
430 * This will not return additional cache tags added through addCacheTags().
435 * @see \Drupal\Core\Cache\RefinableCacheableDependencyInterface::addCacheTags()
436 * @see \Drupal\Core\Cache\CacheableDependencyInterface::getCacheTags()
438 public function getCacheTagsToInvalidate();
441 * Sets the original ID.
443 * @param int|string|null $id
444 * The new ID to set as original ID. If the entity supports renames, setting
445 * NULL will prevent an update from being considered a rename.
449 public function setOriginalId($id);
452 * Gets an array of all property values.
455 * An array of property values, keyed by property name.
457 public function toArray();
460 * Gets a typed data object for this entity object.
462 * The returned typed data object wraps this entity and allows dealing with
463 * entities based on the generic typed data API.
465 * @return \Drupal\Core\TypedData\ComplexDataInterface
466 * The typed data object for this entity.
468 * @see \Drupal\Core\TypedData\TypedDataInterface
470 public function getTypedData();
473 * Gets the key that is used to store configuration dependencies.
476 * The key to be used in configuration dependencies when storing
477 * dependencies on entities of this type.
479 * @see \Drupal\Core\Entity\EntityTypeInterface::getConfigDependencyKey()
481 public function getConfigDependencyKey();
484 * Gets the configuration dependency name.
486 * Configuration entities can depend on content and configuration entities.
487 * They store an array of content and config dependency names in their
488 * "dependencies" key.
491 * The configuration dependency name.
493 * @see \Drupal\Core\Config\Entity\ConfigDependencyManager
495 public function getConfigDependencyName();
498 * Gets the configuration target identifier for the entity.
500 * Used to supply the correct format for storing a reference targeting this
501 * entity in configuration.
504 * The configuration target identifier.
506 public function getConfigTarget();