EntityInterface.php 9.9 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
12
13
use Drupal\Core\TypedData\AccessibleInterface;
use Drupal\Core\TypedData\ComplexDataInterface;
use Drupal\Core\TypedData\TranslatableInterface;

14
15
/**
 * Defines a common interface for all entity objects.
16
 *
17
18
19
20
21
22
23
 * 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.
 *
24
25
 * When implementing this interface which extends Traversable, make sure to list
 * IteratorAggregate or Iterator before this interface in the implements clause.
26
27
28
 *
 * @see \Drupal\Core\TypedData\TypedDataManager
 * @see \Drupal\Core\Field\FieldInterface
29
 */
30
interface EntityInterface extends ComplexDataInterface, AccessibleInterface, TranslatableInterface {
31

32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
  /**
   * Returns the entity identifier (the entity's machine name or numeric ID).
   *
   * @return
   *   The identifier of the entity, or NULL if the entity does not yet have
   *   an identifier.
   */
  public function id();

  /**
   * 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.
   *
61
   * @see \Drupal\Core\Entity\EntityInterface::enforceIsNew()
62
63
64
   */
  public function isNew();

65
66
67
68
69
70
  /**
   * Returns whether a new revision should be created on save.
   *
   * @return bool
   *   TRUE if a new revision should be created.
   *
71
   * @see \Drupal\Core\Entity\EntityInterface::setNewRevision()
72
73
74
75
76
77
78
79
80
   */
  public function isNewRevision();

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

85
86
87
88
89
90
91
92
93
94
  /**
   * 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.
   *
95
   * @see \Drupal\Core\Entity\EntityInterface::isNew()
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
126
127
128
129
130
131
132
133
   */
  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
134
   *   of the entity, and matching the signature of url().
135
136
137
   */
  public function uri();

138
139
140
141
142
143
144
145
  /**
   * Returns a list of URI relationships supported by this entity.
   *
   * @return array
   *   An array of link relationships supported by this entity.
   */
  public function uriRelationships();

146
147
148
149
150
151
  /**
   * Saves an entity permanently.
   *
   * @return
   *   Either SAVED_NEW or SAVED_UPDATED, depending on the operation performed.
   *
152
   * @throws \Drupal\Core\Entity\EntityStorageException
153
154
155
156
157
158
159
   *   In case of failures an exception is thrown.
   */
  public function save();

  /**
   * Deletes an entity permanently.
   *
160
   * @throws \Drupal\Core\Entity\EntityStorageException
161
162
163
164
   *   In case of failures an exception is thrown.
   */
  public function delete();

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
248
249
250
251
252
  /**
   * 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);

253
254
255
  /**
   * Creates a duplicate of the entity.
   *
256
   * @return \Drupal\Core\Entity\EntityInterface
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
   *   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();

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

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

298
299
300
301
302
303
  /**
   * Gets a backward compatibility decorator entity.
   *
   * @return \Drupal\Core\Entity\EntityInterface
   *   The backward compatible entity.
   *
304
   * @see \Drupal\Core\Entity\EntityInterface::getNGEntity()
305
306
307
308
309
310
311
312
313
314
315
   */
  public function getBCEntity();

  /**
   * Removes any possible (backward compatibility) decorator in use.
   *
   * @return \Drupal\Core\Entity\EntityInterface
   *   The original, not backward compatible entity object.
   *
   * @see \Drupal\Core\Entity\EntityInterface::getBCEntity()
   */
316
  public function getNGEntity();
317
318
319
320
321
322
323
324
325

  /**
   * Returns the translation support status.
   *
   * @return bool
   *   TRUE if the entity bundle has translation support enabled.
   */
  public function isTranslatable();

326
327
328
329
330
331
332
333
334
335
336
  /**
   * 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);

337
}