3 namespace Drupal\Core\Entity;
6 * Defines the interface for entity storage classes.
8 * For common default implementations, see
9 * \Drupal\Core\Entity\Sql\SqlContentEntityStorage for content entities and
10 * \Drupal\Core\Config\Entity\ConfigEntityStorage for config entities. Those
11 * implementations are used by default when the @ContentEntityType or
12 * @ConfigEntityType annotations are used.
16 interface EntityStorageInterface {
19 * Load the most recent version of an entity's field data.
21 const FIELD_LOAD_CURRENT = 'FIELD_LOAD_CURRENT';
24 * Load the version of an entity's field data specified in the entity.
26 const FIELD_LOAD_REVISION = 'FIELD_LOAD_REVISION';
29 * Resets the internal, static entity cache.
32 * (optional) If specified, the cache is reset for the entities with the
35 public function resetCache(array $ids = NULL);
38 * Loads one or more entities.
41 * An array of entity IDs, or NULL to load all entities.
43 * @return \Drupal\Core\Entity\EntityInterface[]
44 * An array of entity objects indexed by their IDs. Returns an empty array
45 * if no matching entities are found.
47 public function loadMultiple(array $ids = NULL);
53 * The ID of the entity to load.
55 * @return \Drupal\Core\Entity\EntityInterface|null
56 * An entity object. NULL if no matching entity is found.
58 public function load($id);
61 * Loads an unchanged entity from the database.
64 * The ID of the entity to load.
66 * @return \Drupal\Core\Entity\EntityInterface|null
67 * The unchanged entity, or NULL if the entity cannot be loaded.
69 * @todo Remove this method once we have a reliable way to retrieve the
70 * unchanged entity from the entity object.
72 public function loadUnchanged($id);
75 * Load a specific entity revision.
77 * @param int|string $revision_id
80 * @return \Drupal\Core\Entity\EntityInterface|null
81 * The specified entity revision or NULL if not found.
83 * @todo Deprecated in Drupal 8.5.0 and will be removed before Drupal 9.0.0.
84 * Use \Drupal\Core\Entity\RevisionableStorageInterface instead.
86 * @see https://www.drupal.org/node/2926958
87 * @see https://www.drupal.org/node/2927226
89 public function loadRevision($revision_id);
92 * Delete a specific entity revision.
94 * A revision can only be deleted if it's not the currently active one.
96 * @param int $revision_id
99 * @todo Deprecated in Drupal 8.5.0 and will be removed before Drupal 9.0.0.
100 * Use \Drupal\Core\Entity\RevisionableStorageInterface instead.
102 * @see https://www.drupal.org/node/2926958
103 * @see https://www.drupal.org/node/2927226
105 public function deleteRevision($revision_id);
108 * Load entities by their property values.
110 * @param array $values
111 * An associative array where the keys are the property names and the
112 * values are the values those properties must have.
114 * @return \Drupal\Core\Entity\EntityInterface[]
115 * An array of entity objects indexed by their ids.
117 public function loadByProperties(array $values = []);
120 * Constructs a new entity object, without permanently saving it.
122 * @param array $values
123 * (optional) An array of values to set, keyed by property name. If the
124 * entity type has bundles, the bundle key has to be specified.
126 * @return \Drupal\Core\Entity\EntityInterface
127 * A new entity object.
129 public function create(array $values = []);
132 * Deletes permanently saved entities.
134 * @param array $entities
135 * An array of entity objects to delete.
137 * @throws \Drupal\Core\Entity\EntityStorageException
138 * In case of failures, an exception is thrown.
140 public function delete(array $entities);
143 * Saves the entity permanently.
145 * @param \Drupal\Core\Entity\EntityInterface $entity
146 * The entity to save.
149 * SAVED_NEW or SAVED_UPDATED is returned depending on the operation
152 * @throws \Drupal\Core\Entity\EntityStorageException
153 * In case of failures, an exception is thrown.
155 public function save(EntityInterface $entity);
158 * Determines if the storage contains any data.
161 * TRUE if the storage contains data, FALSE if not.
163 public function hasData();
166 * Gets an entity query instance.
168 * @param string $conjunction
169 * (optional) The logical operator for the query, either:
170 * - AND: all of the conditions on the query need to match.
171 * - OR: at least one of the conditions on the query need to match.
173 * @return \Drupal\Core\Entity\Query\QueryInterface
174 * The query instance.
176 * @see \Drupal\Core\Entity\EntityStorageBase::getQueryServiceName()
178 public function getQuery($conjunction = 'AND');
181 * Gets an aggregated query instance.
183 * @param string $conjunction
184 * (optional) The logical operator for the query, either:
185 * - AND: all of the conditions on the query need to match.
186 * - OR: at least one of the conditions on the query need to match.
188 * @return \Drupal\Core\Entity\Query\QueryAggregateInterface
189 * The aggregated query object that can query the given entity type.
191 * @see \Drupal\Core\Entity\EntityStorageBase::getQueryServiceName()
193 public function getAggregateQuery($conjunction = 'AND');
196 * Gets the entity type ID.
199 * The entity type ID.
201 public function getEntityTypeId();
204 * Gets the entity type definition.
206 * @return \Drupal\Core\Entity\EntityTypeInterface
207 * Entity type definition.
209 public function getEntityType();