EntityStorageControllerInterface.php 4.82 KB
Newer Older
1 2 3 4
<?php

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

8
namespace Drupal\Core\Entity;
9 10

/**
11 12
 * Defines a common interface for entity controller classes.
 *
13
 * All entity controller classes specified via the "controllers['storage']" key
14 15
 * returned by \Drupal\Core\Entity\EntityManager or hook_entity_info_alter()
 * have to implement this interface.
16 17
 *
 * Most simple, SQL-based entity controllers will do better by extending
18
 * Drupal\Core\Entity\DatabaseStorageController instead of implementing this
19
 * interface directly.
20
 */
21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42
interface EntityStorageControllerInterface {

  /**
   * Resets the internal, static entity cache.
   *
   * @param $ids
   *   (optional) If specified, the cache is reset for the entities with the
   *   given ids only.
   */
  public function resetCache(array $ids = NULL);

  /**
   * Loads one or more entities.
   *
   * @param $ids
   *   An array of entity IDs, or FALSE to load all entities.
   *
   * @return
   *   An array of entity objects indexed by their ids.
   */
  public function load(array $ids = NULL);

43 44 45 46 47 48 49 50 51 52 53 54 55 56
  /**
   * Loads an unchanged entity from the database.
   *
   * @param mixed $id
   *   The ID of the entity to load.
   *
   * @return \Drupal\Core\Entity\EntityInterface
   *   The unchanged entity, or FALSE if the entity cannot be loaded.
   *
   * @todo Remove this method once we have a reliable way to retrieve the
   *   unchanged entity from the entity object.
   */
  public function loadUnchanged($id);

57 58 59 60 61 62
  /**
   * Load a specific entity revision.
   *
   * @param int $revision_id
   *   The revision id.
   *
63
   * @return \Drupal\Core\Entity\EntityInterface|false
64 65 66 67
   *   The specified entity revision or FALSE if not found.
   */
  public function loadRevision($revision_id);

68 69 70 71 72 73 74 75 76 77
  /**
   * Delete a specific entity revision.
   *
   * A revision can only be deleted if it's not the currently active one.
   *
   * @param int $revision_id
   *   The revision id.
   */
  public function deleteRevision($revision_id);

78 79 80 81 82 83 84 85 86 87
  /**
   * Load entities by their property values.
   *
   * @param array $values
   *   An associative array where the keys are the property names and the
   *   values are the values those properties must have.
   *
   * @return array
   *   An array of entity objects indexed by their ids.
   */
88
  public function loadByProperties(array $values = array());
89 90 91 92 93 94 95 96

  /**
   * Constructs a new entity object, without permanently saving it.
   *
   * @param $values
   *   An array of values to set, keyed by property name. If the entity type has
   *   bundles the bundle key has to be specified.
   *
97
   * @return \Drupal\Core\Entity\EntityInterface
98 99 100 101 102 103 104
   *   A new entity object.
   */
  public function create(array $values);

  /**
   * Deletes permanently saved entities.
   *
105 106
   * @param array $entities
   *   An array of entity objects to delete.
107
   *
108
   * @throws \Drupal\Core\Entity\EntityStorageException
109 110
   *   In case of failures, an exception is thrown.
   */
111
  public function delete(array $entities);
112 113 114 115

  /**
   * Saves the entity permanently.
   *
116
   * @param \Drupal\Core\Entity\EntityInterface $entity
117 118 119 120 121 122
   *   The entity to save.
   *
   * @return
   *   SAVED_NEW or SAVED_UPDATED is returned depending on the operation
   *   performed.
   *
123
   * @throws \Drupal\Core\Entity\EntityStorageException
124 125 126
   *   In case of failures, an exception is thrown.
   */
  public function save(EntityInterface $entity);
127

128 129 130 131 132 133 134 135 136 137 138 139 140 141
  /**
   * Gets an array of entity field definitions.
   *
   * If a 'bundle' key is present in the given entity definition, fields
   * specific to this bundle are included.
   * Entity fields are always multi-valued, so 'list' is TRUE for each
   * returned field definition.
   *
   * @param array $constraints
   *   An array of entity constraints as used for entities in typed data
   *   definitions, i.e. an array having an 'entity type' and optionally a
   *   'bundle' key. For example:
   *   @code
   *   array(
142 143
   *     'EntityType' => 'node',
   *     'Bundle' => 'article',
144 145 146 147 148 149 150
   *   )
   *   @endcode
   *
   * @return array
   *   An array of field definitions of entity fields, keyed by field
   *   name. In addition to the typed data definition keys as described at
   *   typed_data()->create() the follow keys are supported:
151
   *   - queryable: Whether the field is queryable via QueryInterface.
152 153 154 155 156 157 158 159 160
   *     Defaults to TRUE if 'computed' is FALSE or not set, to FALSE otherwise.
   *   - translatable: Whether the field is translatable. Defaults to FALSE.
   *   - configurable: A boolean indicating whether the field is configurable
   *     via field.module. Defaults to FALSE.
   *
   * @see Drupal\Core\TypedData\TypedDataManager::create()
   * @see typed_data()
   */
  public function getFieldDefinitions(array $constraints);
161 162 163 164 165 166 167 168

  /**
   * Gets the name of the service for the query for this entity storage.
   *
   * @return string
   */
  public function getQueryServicename();

169
}