EntityInterface.php 9.86 KB
Newer Older
1 2 3 4
<?php

/**
 * @file
5
 * Contains \Drupal\Core\Entity\EntityInterface.
6 7
 */

8
namespace Drupal\Core\Entity;
9

10 11
use Drupal\Core\TypedData\AccessibleInterface;
use Drupal\Core\TypedData\ComplexDataInterface;
12
use Drupal\Core\TypedData\IdentifiableInterface;
13 14
use Drupal\Core\TypedData\TranslatableInterface;

15 16
/**
 * Defines a common interface for all entity objects.
17
 *
18 19 20 21 22 23 24
 * This interface builds upon the general interfaces provided by the typed data
 * API, while extending them with entity-specific additions. I.e., an entity
 * implements the ComplexDataInterface among others, thus is complex data
 * containing fields as its data properties. The contained fields have to
 * implement the \Drupal\Core\Entity\Field\FieldInterface, which builds upon
 * typed data interfaces as well.
 *
25 26
 * When implementing this interface which extends Traversable, make sure to list
 * IteratorAggregate or Iterator before this interface in the implements clause.
27 28 29
 *
 * @see \Drupal\Core\TypedData\TypedDataManager
 * @see \Drupal\Core\Field\FieldInterface
30
 */
31
interface EntityInterface extends IdentifiableInterface, ComplexDataInterface, AccessibleInterface, TranslatableInterface {
32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52

  /**
   * Returns the entity UUID (Universally Unique Identifier).
   *
   * The UUID is guaranteed to be unique and can be used to identify an entity
   * across multiple systems.
   *
   * @return string
   *   The UUID of the entity, or NULL if the entity does not have one.
   */
  public function uuid();

  /**
   * Returns whether the entity is new.
   *
   * Usually an entity is new if no ID exists for it yet. However, entities may
   * be enforced to be new with existing IDs too.
   *
   * @return
   *   TRUE if the entity is new, or FALSE if the entity has already been saved.
   *
53
   * @see \Drupal\Core\Entity\EntityInterface::enforceIsNew()
54 55 56
   */
  public function isNew();

57 58 59 60 61 62
  /**
   * Returns whether a new revision should be created on save.
   *
   * @return bool
   *   TRUE if a new revision should be created.
   *
63
   * @see \Drupal\Core\Entity\EntityInterface::setNewRevision()
64 65 66 67 68 69 70 71 72
   */
  public function isNewRevision();

  /**
   * Enforces an entity to be saved as a new revision.
   *
   * @param bool $value
   *   (optional) Whether a new revision should be saved.
   *
73
   * @see \Drupal\Core\Entity\EntityInterface::isNewRevision()
74 75 76
   */
  public function setNewRevision($value = TRUE);

77 78 79 80 81 82 83 84 85 86
  /**
   * Enforces an entity to be new.
   *
   * Allows migrations to create entities with pre-defined IDs by forcing the
   * entity to be new before saving.
   *
   * @param bool $value
   *   (optional) Whether the entity should be forced to be new. Defaults to
   *   TRUE.
   *
87
   * @see \Drupal\Core\Entity\EntityInterface::isNew()
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125
   */
  public function enforceIsNew($value = TRUE);

  /**
   * Returns the type of the entity.
   *
   * @return
   *   The type of the entity.
   */
  public function entityType();

  /**
   * Returns the bundle of the entity.
   *
   * @return
   *   The bundle of the entity. Defaults to the entity type if the entity type
   *   does not make use of different bundles.
   */
  public function bundle();

  /**
   * Returns the label of the entity.
   *
   * @param $langcode
   *   (optional) The language code of the language that should be used for
   *   getting the label. If set to NULL, the entity's default language is
   *   used.
   *
   * @return
   *   The label of the entity, or NULL if there is no label defined.
   */
  public function label($langcode = NULL);

  /**
   * Returns the URI elements of the entity.
   *
   * @return
   *   An array containing the 'path' and 'options' keys used to build the URI
126
   *   of the entity, and matching the signature of url().
127 128 129
   */
  public function uri();

130 131 132 133 134 135 136 137
  /**
   * Returns a list of URI relationships supported by this entity.
   *
   * @return array
   *   An array of link relationships supported by this entity.
   */
  public function uriRelationships();

138 139 140
  /**
   * Saves an entity permanently.
   *
141 142 143
   * When saving existing entities, the entity is assumed to be complete,
   * partial updates of entities are not supported.
   *
144 145 146
   * @return
   *   Either SAVED_NEW or SAVED_UPDATED, depending on the operation performed.
   *
147
   * @throws \Drupal\Core\Entity\EntityStorageException
148 149 150 151 152 153 154
   *   In case of failures an exception is thrown.
   */
  public function save();

  /**
   * Deletes an entity permanently.
   *
155
   * @throws \Drupal\Core\Entity\EntityStorageException
156 157 158 159
   *   In case of failures an exception is thrown.
   */
  public function delete();

160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247
  /**
   * Acts on an entity before the presave hook is invoked.
   *
   * Used before the entity is saved and before invoking the presave hook.
   *
   * @param \Drupal\Core\Entity\EntityStorageControllerInterface $storage_controller
   *   The entity storage controller object.
   */
  public function preSave(EntityStorageControllerInterface $storage_controller);

  /**
   * Acts on a revision before it gets saved.
   *
   * @param EntityStorageControllerInterface $storage_controller
   *   The entity storage controller object.
   * @param \stdClass $record
   *   The revision object.
   */
  public function preSaveRevision(EntityStorageControllerInterface $storage_controller, \stdClass $record);

  /**
   * Acts on a saved entity before the insert or update hook is invoked.
   *
   * Used after the entity is saved, but before invoking the insert or update
   * hook.
   *
   * @param \Drupal\Core\Entity\EntityStorageControllerInterface $storage_controller
   *   The entity storage controller object.
   * @param bool $update
   *   TRUE if the entity has been updated, or FALSE if it has been inserted.
   */
  public function postSave(EntityStorageControllerInterface $storage_controller, $update = TRUE);

  /**
   * Changes the values of an entity before it is created.
   *
   * Load defaults for example.
   *
   * @param \Drupal\Core\Entity\EntityStorageControllerInterface $storage_controller
   *   The entity storage controller object.
   * @param array $values
   *   An array of values to set, keyed by property name. If the entity type has
   *   bundles the bundle key has to be specified.
   */
  public static function preCreate(EntityStorageControllerInterface $storage_controller, array &$values);

  /**
   * Acts on an entity after it is created but before hooks are invoked.
   *
   * @param EntityStorageControllerInterface $storage_controller
   *   The entity storage controller object.
   */
  public function postCreate(EntityStorageControllerInterface $storage_controller);

  /**
   * Acts on entities before they are deleted and before hooks are invoked.
   *
   * Used before the entities are deleted and before invoking the delete hook.
   *
   * @param EntityStorageControllerInterface $storage_controller
   *   The entity storage controller object.
   * @param array $entities
   *   An array of entities.
   */
  public static function preDelete(EntityStorageControllerInterface $storage_controller, array $entities);

  /**
   * Acts on deleted entities before the delete hook is invoked.
   *
   * Used after the entities are deleted but before invoking the delete hook.
   *
   * @param EntityStorageControllerInterface $storage_controller
   *   The entity storage controller object.
   * @param array $entities
   *   An array of entities.
   */
  public static function postDelete(EntityStorageControllerInterface $storage_controller, array $entities);

  /**
   * Acts on loaded entities before the load hook is invoked.
   *
   * @param EntityStorageControllerInterface $storage_controller
   *   The entity storage controller object.
   * @param array $entities
   *   An array of entities.
   */
  public static function postLoad(EntityStorageControllerInterface $storage_controller, array $entities);

248 249 250
  /**
   * Creates a duplicate of the entity.
   *
251
   * @return \Drupal\Core\Entity\EntityInterface
252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273
   *   A clone of the current entity with all identifiers unset, so saving
   *   it inserts a new entity into the storage system.
   */
  public function createDuplicate();

  /**
   * Returns the info of the type of the entity.
   *
   * @see entity_get_info()
   */
  public function entityInfo();

  /**
   * Returns the revision identifier of the entity.
   *
   * @return
   *   The revision identifier of the entity, or NULL if the entity does not
   *   have a revision identifier.
   */
  public function getRevisionId();

  /**
274
   * Checks if this entity is the default revision.
275
   *
276
   * @param bool $new_value
277
   *   (optional) A Boolean to (re)set the isDefaultRevision flag.
278
   *
279
   * @return bool
280
   *   TRUE if the entity is the default revision, FALSE otherwise. If
281
   *   $new_value was passed, the previous value is returned.
282
   */
283
  public function isDefaultRevision($new_value = NULL);
284 285 286 287 288 289 290 291 292

  /**
   * Retrieves the exportable properties of the entity.
   *
   * @return array
   *   An array of exportable properties and their values.
   */
  public function getExportProperties();

293 294 295 296 297 298 299 300
  /**
   * Returns the translation support status.
   *
   * @return bool
   *   TRUE if the entity bundle has translation support enabled.
   */
  public function isTranslatable();

301 302 303 304 305 306 307 308 309 310 311
  /**
   * Marks the translation identified by the given language code as existing.
   *
   * @todo Remove this as soon as translation metadata have been converted to
   *    regular fields.
   *
   * @param string $langcode
   *   The language code identifying the translation to be initialized.
   */
  public function initTranslation($langcode);

312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327
  /**
   * Defines the base fields of the entity type.
   *
   * @param string $entity_type
   *   The entity type to return properties for. Useful when a single class is
   *   used for multiple, possibly dynamic entity types.
   *
   * @return array
   *   An array of entity field definitions as specified by
   *   \Drupal\Core\Entity\EntityManager::getFieldDefinitions(), keyed by field
   *   name.
   *
   * @see \Drupal\Core\Entity\EntityManager::getFieldDefinitions()
   */
  public static function baseFieldDefinitions($entity_type);

328
}