Update API
Same name in other branches
- 7.x modules/system/system.api.php \update_api
- 9 core/lib/Drupal/Core/Extension/module.api.php \update_api
- 8.9.x core/lib/Drupal/Core/Extension/module.api.php \update_api
- 10 core/lib/Drupal/Core/Extension/module.api.php \update_api
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 my_module.install (if your module's machine name is my_module). 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
Functions
Title Sort descending | File name | Summary |
---|---|---|
hook_post_update_NAME | core/ |
Executes an update which is intended to update data, like entities. |
hook_removed_post_updates | core/ |
Return an array of removed hook_post_update_NAME() function names. |
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
Title Sort descending | File name | Summary |
---|---|---|
UpdatePathTestBase | core/ |
Provides a base class for writing an update test. |
Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.