function update_do_one in Drupal 10

Same name and namespace in other branches

1. 8 core/includes/update.inc \update_do_one()
2. 6 update.php \update_do_one()
3. 7 includes/update.inc \update_do_one()
4. 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 Drupal\Core\Utility\UpdateException with an appropriate error message, for example:

use Drupal\Core\Utility\UpdateException;
throw new UpdateException('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'

DbUpdateController::triggerBatch in core/modules/system/src/Controller/DbUpdateController.php

Starts the database update batch process.

File

core/includes/update.inc, line 158

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, [
    $function,
  ]))) {
    return;
  }
  $ret = [];
  if (function_exists($function)) {
    try {
      $ret['results']['query'] = $function($context['sandbox']);
      $ret['results']['success'] = TRUE;
    } catch (Exception $e) {
      watchdog_exception('update', $e);
      $variables = Error::decodeException($e);
      unset($variables['backtrace'], $variables['exception'], $variables['severity_level']);
      $ret['#abort'] = [
        'success' => FALSE,
        'query' => t(Error::DEFAULT_ERROR_MESSAGE, $variables),
      ];
    }
  }
  if (isset($context['sandbox']['#finished'])) {
    $context['finished'] = $context['sandbox']['#finished'];
    unset($context['sandbox']['#finished']);
  }
  if (!isset($context['results'][$module])) {
    $context['results'][$module] = [];
  }
  if (!isset($context['results'][$module][$number])) {
    $context['results'][$module][$number] = [];
  }
  $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::service('update.update_hook_registry')
      ->setInstalledVersion($module, $number);
  }
  $context['message'] = t('Updating @module', [
    '@module' => $module,
  ]);
}