annotate core/lib/Drupal/Core/Entity/EntityInterface.php @ 19:fa3358dc1485 tip

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