function update_do_one in Drupal 7

Same name and namespace in other branches

1. 8 core/includes/update.inc \update_do_one()
2. 6 update.php \update_do_one()
3. 9 core/includes/update.inc \update_do_one()

Implements callback_batch_operation().

Performs one update and stores the results for display on the results page.

If an update function completes successfully, it should return a message as a string indicating success, for example:

return t('New index added successfully.');

Alternatively, it may return nothing. In that case, no message will be displayed at all.

If it fails for whatever reason, it should throw an instance of DrupalUpdateException with an appropriate error message, for example:

throw new DrupalUpdateException(t('Description of what went wrong'));

If an exception is thrown, the current update and all updates that depend on it will be aborted. The schema version will not be updated in this case, and all the aborted updates will continue to appear on update.php as updates that have not yet been run.

If an update function needs to be re-run as part of a batch process, it should accept the $sandbox array by reference as its first parameter and set the #finished property to the percentage completed that it is, as a fraction of 1.

Parameters

$module: The module whose update will be run.

$number: The update number to run.

$dependency_map: An array whose keys are the names of all update functions that will be performed during this batch process, and whose values are arrays of other update functions that each one depends on.

$context: The batch context array.

See also

update_resolve_dependencies()

1 string reference to 'update_do_one'

update_batch in includes/update.inc

Starts the database update batch process.

File

includes/update.inc, line 961

Drupal database update API.

Code

function update_do_one($module, $number, $dependency_map, &$context) {
  $function = $module . '_update_' . $number;

  // If this update was aborted in a previous step, or has a dependency that
  // was aborted in a previous step, go no further.
  if (!empty($context['results']['#abort']) && array_intersect($context['results']['#abort'], array_merge($dependency_map, array(
    $function,
  )))) {
    return;
  }
  $ret = array();
  if (function_exists($function)) {
    try {
      $ret['results']['query'] = $function($context['sandbox']);
      $ret['results']['success'] = TRUE;
    } catch (Exception $e) {
      watchdog_exception('update', $e);
      require_once DRUPAL_ROOT . '/includes/errors.inc';
      $variables = _drupal_decode_exception($e);

      // The exception message is run through check_plain() by _drupal_decode_exception().
      $ret['#abort'] = array(
        'success' => FALSE,
        'query' => t('%type: !message in %function (line %line of %file).', $variables),
      );
    }
  }
  if (isset($context['sandbox']['#finished'])) {
    $context['finished'] = $context['sandbox']['#finished'];
    unset($context['sandbox']['#finished']);
  }
  if (!isset($context['results'][$module])) {
    $context['results'][$module] = array();
  }
  if (!isset($context['results'][$module][$number])) {
    $context['results'][$module][$number] = array();
  }
  $context['results'][$module][$number] = array_merge($context['results'][$module][$number], $ret);
  if (!empty($ret['#abort'])) {

    // Record this function in the list of updates that were aborted.
    $context['results']['#abort'][] = $function;
  }

  // Record the schema update if it was completed successfully.
  if ($context['finished'] == 1 && empty($ret['#abort'])) {
    drupal_set_installed_schema_version($module, $number);
  }
  $context['message'] = 'Updating ' . check_plain($module) . ' module';
}