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   public function loadRevision($revision_id);
  84
  85   /**
  86    * Delete a specific entity revision.
  87    *
  88    * A revision can only be deleted if it's not the currently active one.
  89    *
  90    * @param int $revision_id
  91    *   The revision id.
  92    */
  93   public function deleteRevision($revision_id);
  94
  95   /**
  96    * Load entities by their property values.
  97    *
  98    * @param array $values
  99    *   An associative array where the keys are the property names and the
 100    *   values are the values those properties must have.
 101    *
 102    * @return \Drupal\Core\Entity\EntityInterface[]
 103    *   An array of entity objects indexed by their ids.
 104    */
 105   public function loadByProperties(array $values = []);
 106
 107   /**
 108    * Constructs a new entity object, without permanently saving it.
 109    *
 110    * @param array $values
 111    *   (optional) An array of values to set, keyed by property name. If the
 112    *   entity type has bundles, the bundle key has to be specified.
 113    *
 114    * @return \Drupal\Core\Entity\EntityInterface
 115    *   A new entity object.
 116    */
 117   public function create(array $values = []);
 118
 119   /**
 120    * Deletes permanently saved entities.
 121    *
 122    * @param array $entities
 123    *   An array of entity objects to delete.
 124    *
 125    * @throws \Drupal\Core\Entity\EntityStorageException
 126    *   In case of failures, an exception is thrown.
 127    */
 128   public function delete(array $entities);
 129
 130   /**
 131    * Saves the entity permanently.
 132    *
 133    * @param \Drupal\Core\Entity\EntityInterface $entity
 134    *   The entity to save.
 135    *
 136    * @return
 137    *   SAVED_NEW or SAVED_UPDATED is returned depending on the operation
 138    *   performed.
 139    *
 140    * @throws \Drupal\Core\Entity\EntityStorageException
 141    *   In case of failures, an exception is thrown.
 142    */
 143   public function save(EntityInterface $entity);
 144
 145   /**
 146    * Determines if the storage contains any data.
 147    *
 148    * @return bool
 149    *   TRUE if the storage contains data, FALSE if not.
 150    */
 151   public function hasData();
 152
 153   /**
 154    * Gets an entity query instance.
 155    *
 156    * @param string $conjunction
 157    *   (optional) The logical operator for the query, either:
 158    *   - AND: all of the conditions on the query need to match.
 159    *   - OR: at least one of the conditions on the query need to match.
 160    *
 161    * @return \Drupal\Core\Entity\Query\QueryInterface
 162    *   The query instance.
 163    *
 164    * @see \Drupal\Core\Entity\EntityStorageBase::getQueryServiceName()
 165    */
 166   public function getQuery($conjunction = 'AND');
 167
 168   /**
 169    * Gets an aggregated query instance.
 170    *
 171    * @param string $conjunction
 172    *   (optional) The logical operator for the query, either:
 173    *   - AND: all of the conditions on the query need to match.
 174    *   - OR: at least one of the conditions on the query need to match.
 175    *
 176    * @return \Drupal\Core\Entity\Query\QueryAggregateInterface
 177    *   The aggregated query object that can query the given entity type.
 178    *
 179    * @see \Drupal\Core\Entity\EntityStorageBase::getQueryServiceName()
 180    */
 181   public function getAggregateQuery($conjunction = 'AND');
 182
 183   /**
 184    * Gets the entity type ID.
 185    *
 186    * @return string
 187    *   The entity type ID.
 188    */
 189   public function getEntityTypeId();
 190
 191   /**
 192    * Gets the entity type definition.
 193    *
 194    * @return \Drupal\Core\Entity\EntityTypeInterface
 195    *   Entity type definition.
 196    */
 197   public function getEntityType();
 198
 199 }