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

   1 <?php
   2
   3 namespace Drupal\Core\Entity;
   4
   5 /**
   6  * Defines the interface for entity storage classes.
   7  *
   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.
  13  *
  14  * @ingroup entity_api
  15  */
  16 interface EntityStorageInterface {
  17
  18   /**
  19    * Load the most recent version of an entity's field data.
  20    */
  21   const FIELD_LOAD_CURRENT = 'FIELD_LOAD_CURRENT';
  22
  23   /**
  24    * Load the version of an entity's field data specified in the entity.
  25    */
  26   const FIELD_LOAD_REVISION = 'FIELD_LOAD_REVISION';
  27
  28   /**
  29    * Resets the internal, static entity cache.
  30    *
  31    * @param $ids
  32    *   (optional) If specified, the cache is reset for the entities with the
  33    *   given ids only.
  34    */
  35   public function resetCache(array $ids = NULL);
  36
  37   /**
  38    * Loads one or more entities.
  39    *
  40    * @param $ids
  41    *   An array of entity IDs, or NULL to load all entities.
  42    *
  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.
  46    */
  47   public function loadMultiple(array $ids = NULL);
  48
  49   /**
  50    * Loads one entity.
  51    *
  52    * @param mixed $id
  53    *   The ID of the entity to load.
  54    *
  55    * @return \Drupal\Core\Entity\EntityInterface|null
  56    *   An entity object. NULL if no matching entity is found.
  57    */
  58   public function load($id);
  59
  60   /**
  61    * Loads an unchanged entity from the database.
  62    *
  63    * @param mixed $id
  64    *   The ID of the entity to load.
  65    *
  66    * @return \Drupal\Core\Entity\EntityInterface|null
  67    *   The unchanged entity, or NULL if the entity cannot be loaded.
  68    *
  69    * @todo Remove this method once we have a reliable way to retrieve the
  70    *   unchanged entity from the entity object.
  71    */
  72   public function loadUnchanged($id);
  73
  74   /**
  75    * Load a specific entity revision.
  76    *
  77    * @param int|string $revision_id
  78    *   The revision id.
  79    *
  80    * @return \Drupal\Core\Entity\EntityInterface|null
  81    *   The specified entity revision or NULL if not found.
  82    *
  83    * @todo Deprecated in Drupal 8.5.0 and will be removed before Drupal 9.0.0.
  84    *   Use \Drupal\Core\Entity\RevisionableStorageInterface instead.
  85    *
  86    * @see https://www.drupal.org/node/2926958
  87    * @see https://www.drupal.org/node/2927226
  88    */
  89   public function loadRevision($revision_id);
  90
  91   /**
  92    * Delete a specific entity revision.
  93    *
  94    * A revision can only be deleted if it's not the currently active one.
  95    *
  96    * @param int $revision_id
  97    *   The revision id.
  98    *
  99    * @todo Deprecated in Drupal 8.5.0 and will be removed before Drupal 9.0.0.
 100    *   Use \Drupal\Core\Entity\RevisionableStorageInterface instead.
 101    *
 102    * @see https://www.drupal.org/node/2926958
 103    * @see https://www.drupal.org/node/2927226
 104    */
 105   public function deleteRevision($revision_id);
 106
 107   /**
 108    * Load entities by their property values.
 109    *
 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.
 113    *
 114    * @return \Drupal\Core\Entity\EntityInterface[]
 115    *   An array of entity objects indexed by their ids.
 116    */
 117   public function loadByProperties(array $values = []);
 118
 119   /**
 120    * Constructs a new entity object, without permanently saving it.
 121    *
 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.
 125    *
 126    * @return \Drupal\Core\Entity\EntityInterface
 127    *   A new entity object.
 128    */
 129   public function create(array $values = []);
 130
 131   /**
 132    * Deletes permanently saved entities.
 133    *
 134    * @param array $entities
 135    *   An array of entity objects to delete.
 136    *
 137    * @throws \Drupal\Core\Entity\EntityStorageException
 138    *   In case of failures, an exception is thrown.
 139    */
 140   public function delete(array $entities);
 141
 142   /**
 143    * Saves the entity permanently.
 144    *
 145    * @param \Drupal\Core\Entity\EntityInterface $entity
 146    *   The entity to save.
 147    *
 148    * @return
 149    *   SAVED_NEW or SAVED_UPDATED is returned depending on the operation
 150    *   performed.
 151    *
 152    * @throws \Drupal\Core\Entity\EntityStorageException
 153    *   In case of failures, an exception is thrown.
 154    */
 155   public function save(EntityInterface $entity);
 156
 157   /**
 158    * Determines if the storage contains any data.
 159    *
 160    * @return bool
 161    *   TRUE if the storage contains data, FALSE if not.
 162    */
 163   public function hasData();
 164
 165   /**
 166    * Gets an entity query instance.
 167    *
 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.
 172    *
 173    * @return \Drupal\Core\Entity\Query\QueryInterface
 174    *   The query instance.
 175    *
 176    * @see \Drupal\Core\Entity\EntityStorageBase::getQueryServiceName()
 177    */
 178   public function getQuery($conjunction = 'AND');
 179
 180   /**
 181    * Gets an aggregated query instance.
 182    *
 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.
 187    *
 188    * @return \Drupal\Core\Entity\Query\QueryAggregateInterface
 189    *   The aggregated query object that can query the given entity type.
 190    *
 191    * @see \Drupal\Core\Entity\EntityStorageBase::getQueryServiceName()
 192    */
 193   public function getAggregateQuery($conjunction = 'AND');
 194
 195   /**
 196    * Gets the entity type ID.
 197    *
 198    * @return string
 199    *   The entity type ID.
 200    */
 201   public function getEntityTypeId();
 202
 203   /**
 204    * Gets the entity type definition.
 205    *
 206    * @return \Drupal\Core\Entity\EntityTypeInterface
 207    *   Entity type definition.
 208    */
 209   public function getEntityType();
 210
 211 }