Update API in Zircon Profile 8
Same name and namespace in other branches
Updating minor versions of modules
When you update code in a module, you may need to update stored data so that the stored data is compatible with the new code. If this update is between two minor versions of your module within the same major version of Drupal, you can use the Update API to update the data. This API is described in brief here; for more details, see https://www.drupal.org/node/2535316. If you are updating your module for a major version of Drupal (for instance, Drupal 7 to Drupal 8), updates will not run and you will need to use the Migrate API instead.
When to write update code
You need to provide code that performs an update to stored data whenever your module makes a change to its data model. A data model change is any change that makes stored data on an existing site incompatible with that site's updated codebase. Examples:
- Configuration changes: adding/removing/renaming a config key, changing the expected data type or value structure, changing dependencies, schema changes, etc.
- Database schema changes: adding, changing, or removing a database table or field; moving stored data to different fields or tables; changing the format of stored data.
- Content entity or field changes: adding, changing, or removing a field definition, entity definition, or any of their properties.
How to write update code
Update code for a module is put into an implementation of hook_update_N(), which goes into file mymodule.install (if your module's machine name is mymodule). See the documentation of hook_update_N() and https://www.drupal.org/node/2535316 for details and examples.
Testing update code
Update code should be tested both manually and by writing an automated test. Automated tests for update code extend \Drupal\system\Tests\Update\UpdatePathTestBase -- see that class for details, and find classes that extend it for examples.
See also
File
- core/
lib/ Drupal/ Core/ Extension/ module.api.php, line 13 - Hooks related to module and update systems.
Functions
Name |
Location | Description |
|---|---|---|
| hook_post_update_NAME |
core/ |
Executes an update which is intended to update data, like entities. |
| hook_updater_info |
core/ |
Provide information on Updaters (classes that can update Drupal). |
| hook_updater_info_alter |
core/ |
Alter the Updater information array. |
| hook_update_dependencies |
core/ |
Return an array of information about module update dependencies. |
| hook_update_last_removed |
core/ |
Return a number which is no longer available as hook_update_N(). |
| hook_update_N |
core/ |
Perform a single update between minor versions. |
Classes
|
Name |
Location | Description |
|---|---|---|
| UpdatePathTestBase |
core/ |
Provides a base class for writing an update test. |