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

   1 <?php
   2
   3 namespace Drupal\Core\Entity;
   4
   5 use Drupal\Core\Access\AccessibleInterface;
   6 use Drupal\Core\Cache\CacheableDependencyInterface;
   7 use Drupal\Core\Cache\RefinableCacheableDependencyInterface;
   8
   9 /**
  10  * Defines a common interface for all entity objects.
  11  *
  12  * @ingroup entity_api
  13  */
  14 interface EntityInterface extends AccessibleInterface, CacheableDependencyInterface, RefinableCacheableDependencyInterface {
  15
  16   /**
  17    * Gets the entity UUID (Universally Unique Identifier).
  18    *
  19    * The UUID is guaranteed to be unique and can be used to identify an entity
  20    * across multiple systems.
  21    *
  22    * @return string|null
  23    *   The UUID of the entity, or NULL if the entity does not have one.
  24    */
  25   public function uuid();
  26
  27   /**
  28    * Gets the identifier.
  29    *
  30    * @return string|int|null
  31    *   The entity identifier, or NULL if the object does not yet have an
  32    *   identifier.
  33    */
  34   public function id();
  35
  36   /**
  37    * Gets the language of the entity.
  38    *
  39    * @return \Drupal\Core\Language\LanguageInterface
  40    *   The language object.
  41    */
  42   public function language();
  43
  44   /**
  45    * Determines whether the entity is new.
  46    *
  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.
  49    *
  50    * @return bool
  51    *   TRUE if the entity is new, or FALSE if the entity has already been saved.
  52    *
  53    * @see \Drupal\Core\Entity\EntityInterface::enforceIsNew()
  54    */
  55   public function isNew();
  56
  57   /**
  58    * Enforces an entity to be new.
  59    *
  60    * Allows migrations to create entities with pre-defined IDs by forcing the
  61    * entity to be new before saving.
  62    *
  63    * @param bool $value
  64    *   (optional) Whether the entity should be forced to be new. Defaults to
  65    *   TRUE.
  66    *
  67    * @return $this
  68    *
  69    * @see \Drupal\Core\Entity\EntityInterface::isNew()
  70    */
  71   public function enforceIsNew($value = TRUE);
  72
  73   /**
  74    * Gets the ID of the type of the entity.
  75    *
  76    * @return string
  77    *   The entity type ID.
  78    */
  79   public function getEntityTypeId();
  80
  81   /**
  82    * Gets the bundle of the entity.
  83    *
  84    * @return string
  85    *   The bundle of the entity. Defaults to the entity type ID if the entity
  86    *   type does not make use of different bundles.
  87    */
  88   public function bundle();
  89
  90   /**
  91    * Gets the label of the entity.
  92    *
  93    * @return string|null
  94    *   The label of the entity, or NULL if there is no label defined.
  95    */
  96   public function label();
  97
  98   /**
  99    * Gets the URL object for the entity.
 100    *
 101    * @param string $rel
 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.
 106    *
 107    * @return \Drupal\Core\Url
 108    *   The URL object.
 109    *
 110    * @deprecated in Drupal 8.0.0, intended to be removed in Drupal 9.0.0
 111    *   Use \Drupal\Core\Entity\EntityInterface::toUrl() instead.
 112    *
 113    * @see https://www.drupal.org/node/2614344
 114    * @see \Drupal\Core\Entity\EntityInterface::toUrl
 115    */
 116   public function urlInfo($rel = 'canonical', array $options = []);
 117
 118   /**
 119    * Gets the URL object for the entity.
 120    *
 121    * The entity must have an id already. Content entities usually get their IDs
 122    * by saving them.
 123    *
 124    * URI templates might be set in the links array in an annotation, for
 125    * example:
 126    * @code
 127    * links = {
 128    *   "canonical" = "/node/{node}",
 129    *   "edit-form" = "/node/{node}/edit",
 130    *   "version-history" = "/node/{node}/revisions"
 131    * }
 132    * @endcode
 133    * or specified in a callback function set like:
 134    * @code
 135    * uri_callback = "comment_uri",
 136    * @endcode
 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.
 141    *
 142    * @param string $rel
 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.
 147    *
 148    * @return \Drupal\Core\Url
 149    *   The URL object.
 150    *
 151    * @throws \Drupal\Core\Entity\EntityMalformedException
 152    * @throws \Drupal\Core\Entity\Exception\UndefinedLinkTemplateException
 153    */
 154   public function toUrl($rel = 'canonical', array $options = []);
 155
 156   /**
 157    * Gets the public URL for this entity.
 158    *
 159    * @param string $rel
 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.
 164    *
 165    * @return string
 166    *   The URL for this entity.
 167    *
 168    * @deprecated in Drupal 8.0.0, intended to be removed in Drupal 9.0.0
 169    *   Please use toUrl() instead.
 170    *
 171    * @see https://www.drupal.org/node/2614344
 172    * @see \Drupal\Core\Entity\EntityInterface::toUrl
 173    */
 174   public function url($rel = 'canonical', $options = []);
 175
 176   /**
 177    * Deprecated way of generating a link to the entity. See toLink().
 178    *
 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.
 182    * @param string $rel
 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.
 187    *
 188    * @return string
 189    *   An HTML string containing a link to the entity.
 190    *
 191    * @deprecated in Drupal 8.0.0, intended to be removed in Drupal 9.0.0
 192    *   Please use toLink() instead.
 193    *
 194    * @see https://www.drupal.org/node/2614344
 195    * @see \Drupal\Core\Entity\EntityInterface::toLink
 196    */
 197   public function link($text = NULL, $rel = 'canonical', array $options = []);
 198
 199   /**
 200    * Generates the HTML for a link to this entity.
 201    *
 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.
 205    * @param string $rel
 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.
 210    *
 211    * @return \Drupal\Core\Link
 212    *   A Link to the entity.
 213    *
 214    * @throws \Drupal\Core\Entity\EntityMalformedException
 215    * @throws \Drupal\Core\Entity\Exception\UndefinedLinkTemplateException
 216    */
 217   public function toLink($text = NULL, $rel = 'canonical', array $options = []);
 218
 219   /**
 220    * Indicates if a link template exists for a given key.
 221    *
 222    * @param string $key
 223    *   The link type.
 224    *
 225    * @return bool
 226    *   TRUE if the link template exists, FALSE otherwise.
 227    */
 228   public function hasLinkTemplate($key);
 229
 230   /**
 231    * Gets a list of URI relationships supported by this entity.
 232    *
 233    * @return string[]
 234    *   An array of link relationships supported by this entity.
 235    */
 236   public function uriRelationships();
 237
 238   /**
 239    * Loads an entity.
 240    *
 241    * @param mixed $id
 242    *   The id of the entity to load.
 243    *
 244    * @return static
 245    *   The entity object or NULL if there is no entity with the given ID.
 246    */
 247   public static function load($id);
 248
 249   /**
 250    * Loads one or more entities.
 251    *
 252    * @param array $ids
 253    *   An array of entity IDs, or NULL to load all entities.
 254    *
 255    * @return static[]
 256    *   An array of entity objects indexed by their IDs.
 257    */
 258   public static function loadMultiple(array $ids = NULL);
 259
 260   /**
 261    * Constructs a new entity object, without permanently saving it.
 262    *
 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.
 266    *
 267    * @return static
 268    *   The entity object.
 269    */
 270   public static function create(array $values = []);
 271
 272   /**
 273    * Saves an entity permanently.
 274    *
 275    * When saving existing entities, the entity is assumed to be complete,
 276    * partial updates of entities are not supported.
 277    *
 278    * @return int
 279    *   Either SAVED_NEW or SAVED_UPDATED, depending on the operation performed.
 280    *
 281    * @throws \Drupal\Core\Entity\EntityStorageException
 282    *   In case of failures an exception is thrown.
 283    */
 284   public function save();
 285
 286   /**
 287    * Deletes an entity permanently.
 288    *
 289    * @throws \Drupal\Core\Entity\EntityStorageException
 290    *   In case of failures an exception is thrown.
 291    */
 292   public function delete();
 293
 294   /**
 295    * Acts on an entity before the presave hook is invoked.
 296    *
 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.
 305    *
 306    * @param \Drupal\Core\Entity\EntityStorageInterface $storage
 307    *   The entity storage object.
 308    *
 309    * @see \Drupal\Core\Field\FieldItemListInterface::preSave()
 310    *
 311    * @throws \Exception
 312    *   When there is a problem that should prevent saving the entity.
 313    */
 314   public function preSave(EntityStorageInterface $storage);
 315
 316   /**
 317    * Acts on a saved entity before the insert or update hook is invoked.
 318    *
 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.
 323    *
 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.
 328    */
 329   public function postSave(EntityStorageInterface $storage, $update = TRUE);
 330
 331   /**
 332    * Changes the values of an entity before it is created.
 333    *
 334    * Load defaults for example.
 335    *
 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.
 341    */
 342   public static function preCreate(EntityStorageInterface $storage, array &$values);
 343
 344   /**
 345    * Acts on a created entity before hooks are invoked.
 346    *
 347    * Used after the entity is created, but before saving the entity and before
 348    * any of the presave hooks are invoked.
 349    *
 350    * See the @link entity_crud Entity CRUD topic @endlink for more information.
 351    *
 352    * @param \Drupal\Core\Entity\EntityStorageInterface $storage
 353    *   The entity storage object.
 354    *
 355    * @see \Drupal\Core\Entity\EntityInterface::create()
 356    */
 357   public function postCreate(EntityStorageInterface $storage);
 358
 359   /**
 360    * Acts on entities before they are deleted and before hooks are invoked.
 361    *
 362    * Used before the entities are deleted and before invoking the delete hook.
 363    *
 364    * @param \Drupal\Core\Entity\EntityStorageInterface $storage
 365    *   The entity storage object.
 366    * @param \Drupal\Core\Entity\EntityInterface[] $entities
 367    *   An array of entities.
 368    */
 369   public static function preDelete(EntityStorageInterface $storage, array $entities);
 370
 371   /**
 372    * Acts on deleted entities before the delete hook is invoked.
 373    *
 374    * Used after the entities are deleted but before invoking the delete hook.
 375    *
 376    * @param \Drupal\Core\Entity\EntityStorageInterface $storage
 377    *   The entity storage object.
 378    * @param \Drupal\Core\Entity\EntityInterface[] $entities
 379    *   An array of entities.
 380    */
 381   public static function postDelete(EntityStorageInterface $storage, array $entities);
 382
 383   /**
 384    * Acts on loaded entities.
 385    *
 386    * @param \Drupal\Core\Entity\EntityStorageInterface $storage
 387    *   The entity storage object.
 388    * @param \Drupal\Core\Entity\EntityInterface[] $entities
 389    *   An array of entities.
 390    */
 391   public static function postLoad(EntityStorageInterface $storage, array &$entities);
 392
 393   /**
 394    * Creates a duplicate of the entity.
 395    *
 396    * @return static
 397    *   A clone of $this with all identifiers unset, so saving it inserts a new
 398    *   entity into the storage system.
 399    */
 400   public function createDuplicate();
 401
 402   /**
 403    * Gets the entity type definition.
 404    *
 405    * @return \Drupal\Core\Entity\EntityTypeInterface
 406    *   The entity type definition.
 407    */
 408   public function getEntityType();
 409
 410   /**
 411    * Gets a list of entities referenced by this entity.
 412    *
 413    * @return \Drupal\Core\Entity\EntityInterface[]
 414    *   An array of entities.
 415    */
 416   public function referencedEntities();
 417
 418   /**
 419    * Gets the original ID.
 420    *
 421    * @return int|string|null
 422    *   The original ID, or NULL if no ID was set or for entity types that do not
 423    *   support renames.
 424    */
 425   public function getOriginalId();
 426
 427   /**
 428    * Returns the cache tags that should be used to invalidate caches.
 429    *
 430    * This will not return additional cache tags added through addCacheTags().
 431    *
 432    * @return string[]
 433    *   Set of cache tags.
 434    *
 435    * @see \Drupal\Core\Cache\RefinableCacheableDependencyInterface::addCacheTags()
 436    * @see \Drupal\Core\Cache\CacheableDependencyInterface::getCacheTags()
 437    */
 438   public function getCacheTagsToInvalidate();
 439
 440   /**
 441    * Sets the original ID.
 442    *
 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.
 446    *
 447    * @return $this
 448    */
 449   public function setOriginalId($id);
 450
 451   /**
 452    * Gets an array of all property values.
 453    *
 454    * @return mixed[]
 455    *   An array of property values, keyed by property name.
 456    */
 457   public function toArray();
 458
 459   /**
 460    * Gets a typed data object for this entity object.
 461    *
 462    * The returned typed data object wraps this entity and allows dealing with
 463    * entities based on the generic typed data API.
 464    *
 465    * @return \Drupal\Core\TypedData\ComplexDataInterface
 466    *   The typed data object for this entity.
 467    *
 468    * @see \Drupal\Core\TypedData\TypedDataInterface
 469    */
 470   public function getTypedData();
 471
 472   /**
 473    * Gets the key that is used to store configuration dependencies.
 474    *
 475    * @return string
 476    *   The key to be used in configuration dependencies when storing
 477    *   dependencies on entities of this type.
 478    *
 479    * @see \Drupal\Core\Entity\EntityTypeInterface::getConfigDependencyKey()
 480    */
 481   public function getConfigDependencyKey();
 482
 483   /**
 484    * Gets the configuration dependency name.
 485    *
 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.
 489    *
 490    * @return string
 491    *   The configuration dependency name.
 492    *
 493    * @see \Drupal\Core\Config\Entity\ConfigDependencyManager
 494    */
 495   public function getConfigDependencyName();
 496
 497   /**
 498    * Gets the configuration target identifier for the entity.
 499    *
 500    * Used to supply the correct format for storing a reference targeting this
 501    * entity in configuration.
 502    *
 503    * @return string
 504    *   The configuration target identifier.
 505    */
 506   public function getConfigTarget();
 507
 508 }