Update versions of API functions in Drupal 7

Same name and namespace in other branches

1. 8 core/lib/Drupal/Core/Extension/module.api.php \update_api
2. 9 core/lib/Drupal/Core/Extension/module.api.php \update_api
3. 10 core/lib/Drupal/Core/Extension/module.api.php \update_api

Functions that are similar to normal API functions, but do not invoke hooks.

These simplified versions of core API functions are provided for use by update functions (hook_update_N() implementations).

During database updates the schema of any module could be out of date. For this reason, caution is needed when using any API function within an update function - particularly CRUD functions, functions that depend on the schema (for example by using drupal_write_record()), and any functions that invoke hooks.

Instead, a simplified utility function should be used. If a utility version of the API function you require does not already exist, then you should create a new function. The new utility function should be named _update_N_mymodule_my_function(). N is the schema version the function acts on (the schema version is the number N from the hook_update_N() implementation where this schema was introduced, or a number following the same numbering scheme), and mymodule_my_function is the name of the original API function including the module's name.

Examples:

• _update_6000_mymodule_save(): This function performs a save operation without invoking any hooks using the 6.x schema.
• _update_7000_mymodule_save(): This function performs the same save operation using the 7.x schema.

The utility function should not invoke any hooks, and should perform database operations using functions from the Database abstraction layer, like db_insert(), db_update(), db_delete(), db_query(), and so on.

If a change to the schema necessitates a change to the utility function, a new function should be created with a name based on the version of the schema it acts on. See _update_7000_bar_get_types() and _update_7001_bar_get_types() in the code examples that follow.

For example, foo.install could contain:

function foo_update_dependencies() {

  // foo_update_7010() needs to run after bar_update_7000().
  $dependencies['foo'][7010] = array(
    'bar' => 7000,
  );

  // foo_update_7036() needs to run after bar_update_7001().
  $dependencies['foo'][7036] = array(
    'bar' => 7001,
  );
  return $dependencies;
}
function foo_update_7000() {

  // No updates have been run on the {bar_types} table yet, so this needs
  // to work with the 6.x schema.
  foreach (_update_6000_bar_get_types() as $type) {

    // Rename a variable.
  }
}
function foo_update_7010() {

  // Since foo_update_7010() is going to run after bar_update_7000(), it
  // needs to operate on the new schema, not the old one.
  foreach (_update_7000_bar_get_types() as $type) {

    // Rename a different variable.
  }
}
function foo_update_7036() {

  // This update will run after bar_update_7001().
  foreach (_update_7001_bar_get_types() as $type) {
  }
}

And bar.install could contain:

function bar_update_7000() {
  // Type and bundle are confusing, so we renamed the table.
  db_rename_table('bar_types', 'bar_bundles');
}

function bar_update_7001() {
  // Database table names should be singular when possible.
  db_rename_table('bar_bundles', 'bar_bundle');
}

function _update_6000_bar_get_types() {
  db_query('SELECT * FROM {bar_types}')->fetchAll();
}

function _update_7000_bar_get_types() {
  db_query('SELECT * FROM {bar_bundles'})->fetchAll();
}

function _update_7001_bar_get_types() {
  db_query('SELECT * FROM {bar_bundle}')->fetchAll();
}

See also

hook_update_N()

hook_update_dependencies()

File

modules/system/system.api.php, line 4917

Hooks provided by Drupal core and the System module.

Functions