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

   1 <?php
   2
   3 namespace Drupal\Core\Entity;
   4
   5 use Drupal\Core\Field\FieldStorageDefinitionInterface;
   6
   7 /**
   8  * Defines an interface for managing entity definition updates.
   9  *
  10  * During the application lifetime, the definitions of various entity types and
  11  * their data components (e.g., fields for fieldable entity types) can change.
  12  * For example, updated code can be deployed. Some entity handlers may need to
  13  * perform complex or long-running logic in response to the change. For
  14  * example, a SQL-based storage handler may need to update the database schema.
  15  *
  16  * To support this, \Drupal\Core\Entity\EntityManagerInterface has methods to
  17  * retrieve the last installed definitions as well as the definitions specified
  18  * by the current codebase. It also has create/update/delete methods to bring
  19  * the former up to date with the latter.
  20  *
  21  * However, it is not the responsibility of the entity manager to decide how to
  22  * report the differences or when to apply each update. This interface is for
  23  * managing that.
  24  *
  25  * This interface also provides methods to retrieve instances of the definitions
  26  * to be updated ready to be manipulated. In fact when definitions change in
  27  * code the system needs to be notified about that and the definitions stored in
  28  * state need to be reconciled with the ones living in code. This typically
  29  * happens in Update API functions, which need to take the system from a known
  30  * state to another known state. Relying on the definitions living in code might
  31  * prevent this, as the system might transition directly to the last available
  32  * state, and thus skipping the intermediate steps. Manipulating the definitions
  33  * in state allows to avoid this and ensures that the various steps of the
  34  * update process are predictable and repeatable.
  35  *
  36  * @see \Drupal\Core\Entity\EntityManagerInterface::getDefinition()
  37  * @see \Drupal\Core\Entity\EntityManagerInterface::getLastInstalledDefinition()
  38  * @see \Drupal\Core\Entity\EntityManagerInterface::getFieldStorageDefinitions()
  39  * @see \Drupal\Core\Entity\EntityManagerInterface::getLastInstalledFieldStorageDefinitions()
  40  * @see hook_update_N()
  41  */
  42 interface EntityDefinitionUpdateManagerInterface {
  43
  44   /**
  45    * Indicates that a definition has just been created.
  46    *
  47    * @var int
  48    */
  49   const DEFINITION_CREATED = 1;
  50
  51   /**
  52    * Indicates that a definition has changes.
  53    *
  54    * @var int
  55    */
  56   const DEFINITION_UPDATED = 2;
  57
  58   /**
  59    * Indicates that a definition has just been deleted.
  60    *
  61    * @var int
  62    */
  63   const DEFINITION_DELETED = 3;
  64
  65   /**
  66    * Checks if there are any definition updates that need to be applied.
  67    *
  68    * @return bool
  69    *   TRUE if updates are needed.
  70    */
  71   public function needsUpdates();
  72
  73   /**
  74    * Gets a human readable summary of the detected changes.
  75    *
  76    * @return array
  77    *   An associative array keyed by entity type id. Each entry is an array of
  78    *   human-readable strings, each describing a change.
  79    */
  80   public function getChangeSummary();
  81
  82   /**
  83    * Applies all the detected valid changes.
  84    *
  85    * Use this with care, as it will apply updates for any module, which will
  86    * lead to unpredictable results.
  87    *
  88    * @throws \Drupal\Core\Entity\EntityStorageException
  89    *   This exception is thrown if a change cannot be applied without
  90    *   unacceptable data loss. In such a case, the site administrator needs to
  91    *   apply some other process, such as a custom update function or a
  92    *   migration via the Migrate module.
  93    */
  94   public function applyUpdates();
  95
  96   /**
  97    * Returns an entity type definition ready to be manipulated.
  98    *
  99    * When needing to apply updates to existing entity type definitions, this
 100    * method should always be used to retrieve a definition ready to be
 101    * manipulated.
 102    *
 103    * @param string $entity_type_id
 104    *   The entity type identifier.
 105    *
 106    * @return \Drupal\Core\Entity\EntityTypeInterface
 107    *   The entity type definition.
 108    */
 109   public function getEntityType($entity_type_id);
 110
 111   /**
 112    * Returns all the entity type definitions, ready to be manipulated.
 113    *
 114    * When needing to apply updates to existing entity type definitions, this
 115    * method should always be used to retrieve all the definitions ready to be
 116    * manipulated.
 117    *
 118    * @return \Drupal\Core\Entity\EntityTypeInterface[]
 119    *   The last installed entity type definitions, keyed by the entity type ID.
 120    */
 121   public function getEntityTypes();
 122
 123   /**
 124    * Installs a new entity type definition.
 125    *
 126    * @param \Drupal\Core\Entity\EntityTypeInterface $entity_type
 127    *   The entity type definition.
 128    */
 129   public function installEntityType(EntityTypeInterface $entity_type);
 130
 131   /**
 132    * Applies any change performed to the passed entity type definition.
 133    *
 134    * @param \Drupal\Core\Entity\EntityTypeInterface $entity_type
 135    *   The entity type definition.
 136    */
 137   public function updateEntityType(EntityTypeInterface $entity_type);
 138
 139   /**
 140    * Uninstalls an entity type definition.
 141    *
 142    * @param \Drupal\Core\Entity\EntityTypeInterface $entity_type
 143    *   The entity type definition.
 144    */
 145   public function uninstallEntityType(EntityTypeInterface $entity_type);
 146
 147   /**
 148    * Returns a field storage definition ready to be manipulated.
 149    *
 150    * When needing to apply updates to existing field storage definitions, this
 151    * method should always be used to retrieve a storage definition ready to be
 152    * manipulated.
 153    *
 154    * @param string $name
 155    *   The field name.
 156    * @param string $entity_type_id
 157    *   The entity type identifier.
 158    *
 159    * @return \Drupal\Core\Field\FieldStorageDefinitionInterface
 160    *   The field storage definition.
 161    *
 162    * @todo Make this return a mutable storage definition interface when we have
 163    *   one. See https://www.drupal.org/node/2346329.
 164    */
 165   public function getFieldStorageDefinition($name, $entity_type_id);
 166
 167   /**
 168    * Installs a new field storage definition.
 169    *
 170    * @param string $name
 171    *   The field storage definition name.
 172    * @param string $entity_type_id
 173    *   The target entity type identifier.
 174    * @param string $provider
 175    *   The name of the definition provider.
 176    * @param \Drupal\Core\Field\FieldStorageDefinitionInterface $storage_definition
 177    *   The field storage definition.
 178    */
 179   public function installFieldStorageDefinition($name, $entity_type_id, $provider, FieldStorageDefinitionInterface $storage_definition);
 180
 181   /**
 182    * Applies any change performed to the passed field storage definition.
 183    *
 184    * @param \Drupal\Core\Field\FieldStorageDefinitionInterface $storage_definition
 185    *   The field storage definition.
 186    */
 187   public function updateFieldStorageDefinition(FieldStorageDefinitionInterface $storage_definition);
 188
 189   /**
 190    * Uninstalls a field storage definition.
 191    *
 192    * @param \Drupal\Core\Field\FieldStorageDefinitionInterface $storage_definition
 193    *   The field storage definition.
 194    */
 195   public function uninstallFieldStorageDefinition(FieldStorageDefinitionInterface $storage_definition);
 196
 197 }