3 namespace Drupal\Core\Entity;
5 use Drupal\Core\Field\FieldStorageDefinitionInterface;
8 * Defines an interface for managing entity definition updates.
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.
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.
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
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.
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()
42 interface EntityDefinitionUpdateManagerInterface {
45 * Indicates that a definition has just been created.
49 const DEFINITION_CREATED = 1;
52 * Indicates that a definition has changes.
56 const DEFINITION_UPDATED = 2;
59 * Indicates that a definition has just been deleted.
63 const DEFINITION_DELETED = 3;
66 * Checks if there are any definition updates that need to be applied.
69 * TRUE if updates are needed.
71 public function needsUpdates();
74 * Gets a human readable summary of the detected changes.
77 * An associative array keyed by entity type id. Each entry is an array of
78 * human-readable strings, each describing a change.
80 public function getChangeSummary();
83 * Applies all the detected valid changes.
85 * Use this with care, as it will apply updates for any module, which will
86 * lead to unpredictable results.
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.
94 public function applyUpdates();
97 * Returns an entity type definition ready to be manipulated.
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
103 * @param string $entity_type_id
104 * The entity type identifier.
106 * @return \Drupal\Core\Entity\EntityTypeInterface
107 * The entity type definition.
109 public function getEntityType($entity_type_id);
112 * Installs a new entity type definition.
114 * @param \Drupal\Core\Entity\EntityTypeInterface $entity_type
115 * The entity type definition.
117 public function installEntityType(EntityTypeInterface $entity_type);
120 * Applies any change performed to the passed entity type definition.
122 * @param \Drupal\Core\Entity\EntityTypeInterface $entity_type
123 * The entity type definition.
125 public function updateEntityType(EntityTypeInterface $entity_type);
128 * Uninstalls an entity type definition.
130 * @param \Drupal\Core\Entity\EntityTypeInterface $entity_type
131 * The entity type definition.
133 public function uninstallEntityType(EntityTypeInterface $entity_type);
136 * Returns a field storage definition ready to be manipulated.
138 * When needing to apply updates to existing field storage definitions, this
139 * method should always be used to retrieve a storage definition ready to be
142 * @param string $name
144 * @param string $entity_type_id
145 * The entity type identifier.
147 * @return \Drupal\Core\Field\FieldStorageDefinitionInterface
148 * The field storage definition.
150 * @todo Make this return a mutable storage definition interface when we have
151 * one. See https://www.drupal.org/node/2346329.
153 public function getFieldStorageDefinition($name, $entity_type_id);
156 * Installs a new field storage definition.
158 * @param string $name
159 * The field storage definition name.
160 * @param string $entity_type_id
161 * The target entity type identifier.
162 * @param string $provider
163 * The name of the definition provider.
164 * @param \Drupal\Core\Field\FieldStorageDefinitionInterface $storage_definition
165 * The field storage definition.
167 public function installFieldStorageDefinition($name, $entity_type_id, $provider, FieldStorageDefinitionInterface $storage_definition);
170 * Applies any change performed to the passed field storage definition.
172 * @param \Drupal\Core\Field\FieldStorageDefinitionInterface $storage_definition
173 * The field storage definition.
175 public function updateFieldStorageDefinition(FieldStorageDefinitionInterface $storage_definition);
178 * Uninstalls a field storage definition.
180 * @param \Drupal\Core\Field\FieldStorageDefinitionInterface $storage_definition
181 * The field storage definition.
183 public function uninstallFieldStorageDefinition(FieldStorageDefinitionInterface $storage_definition);