EntityDefinitionUpdateManagerInterface.php 6.82 KB
Newer Older
1 2 3 4
<?php

namespace Drupal\Core\Entity;

5 6
use Drupal\Core\Field\FieldStorageDefinitionInterface;

7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
/**
 * Defines an interface for managing entity definition updates.
 *
 * During the application lifetime, the definitions of various entity types and
 * their data components (e.g., fields for fieldable entity types) can change.
 * For example, updated code can be deployed. Some entity handlers may need to
 * perform complex or long-running logic in response to the change. For
 * example, a SQL-based storage handler may need to update the database schema.
 *
 * To support this, \Drupal\Core\Entity\EntityManagerInterface has methods to
 * retrieve the last installed definitions as well as the definitions specified
 * by the current codebase. It also has create/update/delete methods to bring
 * the former up to date with the latter.
 *
 * However, it is not the responsibility of the entity manager to decide how to
 * report the differences or when to apply each update. This interface is for
 * managing that.
 *
25 26 27 28 29 30 31 32 33 34 35
 * This interface also provides methods to retrieve instances of the definitions
 * to be updated ready to be manipulated. In fact when definitions change in
 * code the system needs to be notified about that and the definitions stored in
 * state need to be reconciled with the ones living in code. This typically
 * happens in Update API functions, which need to take the system from a known
 * state to another known state. Relying on the definitions living in code might
 * prevent this, as the system might transition directly to the last available
 * state, and thus skipping the intermediate steps. Manipulating the definitions
 * in state allows to avoid this and ensures that the various steps of the
 * update process are predictable and repeatable.
 *
36 37 38 39
 * @see \Drupal\Core\Entity\EntityManagerInterface::getDefinition()
 * @see \Drupal\Core\Entity\EntityManagerInterface::getLastInstalledDefinition()
 * @see \Drupal\Core\Entity\EntityManagerInterface::getFieldStorageDefinitions()
 * @see \Drupal\Core\Entity\EntityManagerInterface::getLastInstalledFieldStorageDefinitions()
40
 * @see hook_update_N()
41 42 43
 */
interface EntityDefinitionUpdateManagerInterface {

44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64
  /**
   * Indicates that a definition has just been created.
   *
   * @var int
   */
  const DEFINITION_CREATED = 1;

  /**
   * Indicates that a definition has changes.
   *
   * @var int
   */
  const DEFINITION_UPDATED = 2;

  /**
   * Indicates that a definition has just been deleted.
   *
   * @var int
   */
  const DEFINITION_DELETED = 3;

65 66 67 68 69 70 71 72 73
  /**
   * Checks if there are any definition updates that need to be applied.
   *
   * @return bool
   *   TRUE if updates are needed.
   */
  public function needsUpdates();

  /**
74
   * Gets a human readable summary of the detected changes.
75 76 77 78 79 80 81 82 83 84
   *
   * @return array
   *   An associative array keyed by entity type id. Each entry is an array of
   *   human-readable strings, each describing a change.
   */
  public function getChangeSummary();

  /**
   * Applies all the detected valid changes.
   *
85 86 87
   * Use this with care, as it will apply updates for any module, which will
   * lead to unpredictable results.
   *
88 89 90 91 92 93 94 95
   * @throws \Drupal\Core\Entity\EntityStorageException
   *   This exception is thrown if a change cannot be applied without
   *   unacceptable data loss. In such a case, the site administrator needs to
   *   apply some other process, such as a custom update function or a
   *   migration via the Migrate module.
   */
  public function applyUpdates();

96
  /**
97
   * Returns an entity type definition ready to be manipulated.
98
   *
99 100 101
   * When needing to apply updates to existing entity type definitions, this
   * method should always be used to retrieve a definition ready to be
   * manipulated.
102 103
   *
   * @param string $entity_type_id
104
   *   The entity type identifier.
105
   *
106 107 108 109 110
   * @return \Drupal\Core\Entity\EntityTypeInterface
   *   The entity type definition.
   */
  public function getEntityType($entity_type_id);

111 112 113 114 115 116 117 118 119 120 121 122
  /**
   * Returns all the entity type definitions, ready to be manipulated.
   *
   * When needing to apply updates to existing entity type definitions, this
   * method should always be used to retrieve all the definitions ready to be
   * manipulated.
   *
   * @return \Drupal\Core\Entity\EntityTypeInterface[]
   *   The last installed entity type definitions, keyed by the entity type ID.
   */
  public function getEntityTypes();

123 124
  /**
   * Installs a new entity type definition.
125
   *
126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143
   * @param \Drupal\Core\Entity\EntityTypeInterface $entity_type
   *   The entity type definition.
   */
  public function installEntityType(EntityTypeInterface $entity_type);

  /**
   * Applies any change performed to the passed entity type definition.
   *
   * @param \Drupal\Core\Entity\EntityTypeInterface $entity_type
   *   The entity type definition.
   */
  public function updateEntityType(EntityTypeInterface $entity_type);

  /**
   * Uninstalls an entity type definition.
   *
   * @param \Drupal\Core\Entity\EntityTypeInterface $entity_type
   *   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 151 152
   * When needing to apply updates to existing field storage definitions, this
   * method should always be used to retrieve a storage definition ready to be
   * manipulated.
153
   *
154 155
   * @param string $name
   *   The field name.
156
   * @param string $entity_type_id
157 158 159 160 161 162 163 164 165
   *   The entity type identifier.
   *
   * @return \Drupal\Core\Field\FieldStorageDefinitionInterface
   *   The field storage definition.
   *
   * @todo Make this return a mutable storage definition interface when we have
   *   one. See https://www.drupal.org/node/2346329.
   */
  public function getFieldStorageDefinition($name, $entity_type_id);
166

167 168
  /**
   * Installs a new field storage definition.
169
   *
170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193
   * @param string $name
   *   The field storage definition name.
   * @param string $entity_type_id
   *   The target entity type identifier.
   * @param string $provider
   *   The name of the definition provider.
   * @param \Drupal\Core\Field\FieldStorageDefinitionInterface $storage_definition
   *   The field storage definition.
   */
  public function installFieldStorageDefinition($name, $entity_type_id, $provider, FieldStorageDefinitionInterface $storage_definition);

  /**
   * Applies any change performed to the passed field storage definition.
   *
   * @param \Drupal\Core\Field\FieldStorageDefinitionInterface $storage_definition
   *   The field storage definition.
   */
  public function updateFieldStorageDefinition(FieldStorageDefinitionInterface $storage_definition);

  /**
   * Uninstalls a field storage definition.
   *
   * @param \Drupal\Core\Field\FieldStorageDefinitionInterface $storage_definition
   *   The field storage definition.
194
   */
195
  public function uninstallFieldStorageDefinition(FieldStorageDefinitionInterface $storage_definition);
196

197
}