5 * Drupal database update API.
7 * This file contains functions to perform database updates for a Drupal
8 * installation. It is included and used extensively by update.php.
11 use Drupal\Component\Graph\Graph;
12 use Drupal\Core\Utility\Error;
15 * Disables any extensions that are incompatible with the current core version.
17 function update_fix_compatibility() {
18 $extension_config = \Drupal::configFactory()->getEditable('core.extension');
20 foreach (['module', 'theme'] as $type) {
21 foreach ($extension_config->get($type) as $name => $weight) {
22 if (update_check_incompatibility($name, $type)) {
23 $extension_config->clear("$type.$name");
29 $extension_config->set('module', module_config_sort($extension_config->get('module')));
30 $extension_config->save();
35 * Tests the compatibility of a module or theme.
37 function update_check_incompatibility($name, $type = 'module') {
38 static $themes, $modules;
40 // Store values of expensive functions for future use.
41 if (empty($themes) || empty($modules)) {
42 // We need to do a full rebuild here to make sure the database reflects any
43 // code changes that were made in the filesystem before the update script
45 $themes = \Drupal::service('theme_handler')->rebuildThemeData();
46 $modules = system_rebuild_module_data();
49 if ($type == 'module' && isset($modules[$name])) {
50 $file = $modules[$name];
52 elseif ($type == 'theme' && isset($themes[$name])) {
53 $file = $themes[$name];
56 || !isset($file->info['core'])
57 || $file->info['core'] != \Drupal::CORE_COMPATIBILITY
58 || version_compare(phpversion(), $file->info['php']) < 0) {
65 * Returns whether the minimum schema requirement has been satisfied.
68 * A requirements info array.
70 function update_system_schema_requirements() {
73 $system_schema = drupal_get_installed_schema_version('system');
75 $requirements['minimum schema']['title'] = 'Minimum schema version';
76 if ($system_schema >= \Drupal::CORE_MINIMUM_SCHEMA_VERSION) {
77 $requirements['minimum schema'] += [
78 'value' => 'The installed schema version meets the minimum.',
79 'description' => 'Schema version: ' . $system_schema,
83 $requirements['minimum schema'] += [
84 'value' => 'The installed schema version does not meet the minimum.',
85 'severity' => REQUIREMENT_ERROR,
86 'description' => 'Your system schema version is ' . $system_schema . '. Updating directly from a schema version prior to 8000 is not supported. You must upgrade your site to Drupal 8 first, see https://www.drupal.org/docs/8/upgrade.',
94 * Checks update requirements and reports errors and (optionally) warnings.
96 function update_check_requirements() {
97 // Check requirements of all loaded modules.
98 $requirements = \Drupal::moduleHandler()->invokeAll('requirements', ['update']);
99 $requirements += update_system_schema_requirements();
100 return $requirements;
104 * Forces a module to a given schema version.
106 * This function is rarely necessary.
108 * @param string $module
109 * Name of the module.
110 * @param string $schema_version
111 * The schema version the module should be set to.
113 function update_set_schema($module, $schema_version) {
114 \Drupal::keyValue('system.schema')->set($module, $schema_version);
115 // system_list_reset() is in module.inc but that would only be available
116 // once the variable bootstrap is done.
117 require_once __DIR__ . '/module.inc';
122 * Implements callback_batch_operation().
124 * Performs one update and stores the results for display on the results page.
126 * If an update function completes successfully, it should return a message
127 * as a string indicating success, for example:
129 * return t('New index added successfully.');
132 * Alternatively, it may return nothing. In that case, no message
133 * will be displayed at all.
135 * If it fails for whatever reason, it should throw an instance of
136 * Drupal\Core\Utility\UpdateException with an appropriate error message, for
139 * use Drupal\Core\Utility\UpdateException;
140 * throw new UpdateException(t('Description of what went wrong'));
143 * If an exception is thrown, the current update and all updates that depend on
144 * it will be aborted. The schema version will not be updated in this case, and
145 * all the aborted updates will continue to appear on update.php as updates
146 * that have not yet been run.
148 * If an update function needs to be re-run as part of a batch process, it
149 * should accept the $sandbox array by reference as its first parameter
150 * and set the #finished property to the percentage completed that it is, as a
154 * The module whose update will be run.
156 * The update number to run.
157 * @param $dependency_map
158 * An array whose keys are the names of all update functions that will be
159 * performed during this batch process, and whose values are arrays of other
160 * update functions that each one depends on.
162 * The batch context array.
164 * @see update_resolve_dependencies()
166 function update_do_one($module, $number, $dependency_map, &$context) {
167 $function = $module . '_update_' . $number;
169 // If this update was aborted in a previous step, or has a dependency that
170 // was aborted in a previous step, go no further.
171 if (!empty($context['results']['#abort']) && array_intersect($context['results']['#abort'], array_merge($dependency_map, [$function]))) {
176 if (function_exists($function)) {
178 $ret['results']['query'] = $function($context['sandbox']);
179 $ret['results']['success'] = TRUE;
181 // @TODO We may want to do different error handling for different
182 // exception types, but for now we'll just log the exception and
183 // return the message for printing.
184 // @see https://www.drupal.org/node/2564311
185 catch (Exception $e) {
186 watchdog_exception('update', $e);
188 $variables = Error::decodeException($e);
189 unset($variables['backtrace']);
190 $ret['#abort'] = ['success' => FALSE, 'query' => t('%type: @message in %function (line %line of %file).', $variables)];
194 if (isset($context['sandbox']['#finished'])) {
195 $context['finished'] = $context['sandbox']['#finished'];
196 unset($context['sandbox']['#finished']);
199 if (!isset($context['results'][$module])) {
200 $context['results'][$module] = [];
202 if (!isset($context['results'][$module][$number])) {
203 $context['results'][$module][$number] = [];
205 $context['results'][$module][$number] = array_merge($context['results'][$module][$number], $ret);
207 if (!empty($ret['#abort'])) {
208 // Record this function in the list of updates that were aborted.
209 $context['results']['#abort'][] = $function;
212 // Record the schema update if it was completed successfully.
213 if ($context['finished'] == 1 && empty($ret['#abort'])) {
214 drupal_set_installed_schema_version($module, $number);
217 $context['message'] = t('Updating @module', ['@module' => $module]);
221 * Executes a single hook_post_update_NAME().
223 * @param string $function
224 * The function name, that should be executed.
225 * @param array $context
226 * The batch context array.
228 function update_invoke_post_update($function, &$context) {
231 // If this update was aborted in a previous step, or has a dependency that was
232 // aborted in a previous step, go no further.
233 if (!empty($context['results']['#abort'])) {
237 list($module, $name) = explode('_post_update_', $function, 2);
238 module_load_include('php', $module, $module . '.post_update');
239 if (function_exists($function)) {
241 $ret['results']['query'] = $function($context['sandbox']);
242 $ret['results']['success'] = TRUE;
244 if (!isset($context['sandbox']['#finished']) || (isset($context['sandbox']['#finished']) && $context['sandbox']['#finished'] >= 1)) {
245 \Drupal::service('update.post_update_registry')->registerInvokedUpdates([$function]);
248 // @TODO We may want to do different error handling for different exception
249 // types, but for now we'll just log the exception and return the message
251 // @see https://www.drupal.org/node/2564311
252 catch (Exception $e) {
253 watchdog_exception('update', $e);
255 $variables = Error::decodeException($e);
256 unset($variables['backtrace']);
259 'query' => t('%type: @message in %function (line %line of %file).', $variables),
264 if (isset($context['sandbox']['#finished'])) {
265 $context['finished'] = $context['sandbox']['#finished'];
266 unset($context['sandbox']['#finished']);
268 if (!isset($context['results'][$module][$name])) {
269 $context['results'][$module][$name] = [];
271 $context['results'][$module][$name] = array_merge($context['results'][$module][$name], $ret);
273 if (!empty($ret['#abort'])) {
274 // Record this function in the list of updates that were aborted.
275 $context['results']['#abort'][] = $function;
278 $context['message'] = t('Post updating @module', ['@module' => $module]);
282 * Returns a list of all the pending database updates.
285 * An associative array keyed by module name which contains all information
286 * about database updates that need to be run, and any updates that are not
287 * going to proceed due to missing requirements. The system module will
288 * always be listed first.
290 * The subarray for each module can contain the following keys:
291 * - start: The starting update that is to be processed. If this does not
292 * exist then do not process any updates for this module as there are
293 * other requirements that need to be resolved.
294 * - warning: Any warnings about why this module can not be updated.
295 * - pending: An array of all the pending updates for the module including
296 * the update number and the description from source code comment for
297 * each update function. This array is keyed by the update number.
299 function update_get_update_list() {
300 // Make sure that the system module is first in the list of updates.
301 $ret = ['system' => []];
303 $modules = drupal_get_installed_schema_version(NULL, FALSE, TRUE);
304 foreach ($modules as $module => $schema_version) {
305 // Skip uninstalled and incompatible modules.
306 if ($schema_version == SCHEMA_UNINSTALLED || update_check_incompatibility($module)) {
309 // Display a requirements error if the user somehow has a schema version
310 // from the previous Drupal major version.
311 if ($schema_version < \Drupal::CORE_MINIMUM_SCHEMA_VERSION) {
312 $ret[$module]['warning'] = '<em>' . $module . '</em> module cannot be updated. Its schema version is ' . $schema_version . ', which is from an earlier major release of Drupal. You will need to <a href="https://www.drupal.org/node/2127611">migrate the data for this module</a> instead.';
315 // Otherwise, get the list of updates defined by this module.
316 $updates = drupal_get_schema_versions($module);
317 if ($updates !== FALSE) {
318 // \Drupal::moduleHandler()->invoke() returns NULL for non-existing hooks,
319 // so if no updates are removed, it will == 0.
320 $last_removed = \Drupal::moduleHandler()->invoke($module, 'update_last_removed');
321 if ($schema_version < $last_removed) {
322 $ret[$module]['warning'] = '<em>' . $module . '</em> module cannot be updated. Its schema version is ' . $schema_version . '. Updates up to and including ' . $last_removed . ' have been removed in this release. In order to update <em>' . $module . '</em> module, you will first <a href="https://www.drupal.org/upgrade">need to upgrade</a> to the last version in which these updates were available.';
326 foreach ($updates as $update) {
327 if ($update == \Drupal::CORE_MINIMUM_SCHEMA_VERSION) {
328 $ret[$module]['warning'] = '<em>' . $module . '</em> module cannot be updated. It contains an update numbered as ' . \Drupal::CORE_MINIMUM_SCHEMA_VERSION . ' which is reserved for the earliest installation of a module in Drupal ' . \Drupal::CORE_COMPATIBILITY . ', before any updates. In order to update <em>' . $module . '</em> module, you will need to install a version of the module with valid updates.';
331 if ($update > $schema_version) {
332 // The description for an update comes from its Doxygen.
333 $func = new ReflectionFunction($module . '_update_' . $update);
334 $description = str_replace(["\n", '*', '/'], '', $func->getDocComment());
335 $ret[$module]['pending'][$update] = "$update - $description";
336 if (!isset($ret[$module]['start'])) {
337 $ret[$module]['start'] = $update;
341 if (!isset($ret[$module]['start']) && isset($ret[$module]['pending'])) {
342 $ret[$module]['start'] = $schema_version;
347 if (empty($ret['system'])) {
348 unset($ret['system']);
354 * Resolves dependencies in a set of module updates, and orders them correctly.
356 * This function receives a list of requested module updates and determines an
357 * appropriate order to run them in such that all update dependencies are met.
358 * Any updates whose dependencies cannot be met are included in the returned
359 * array but have the key 'allowed' set to FALSE; the calling function should
360 * take responsibility for ensuring that these updates are ultimately not
363 * In addition, the returned array also includes detailed information about the
364 * dependency chain for each update, as provided by the depth-first search
365 * algorithm in Drupal\Component\Graph\Graph::searchAndSort().
367 * @param $starting_updates
368 * An array whose keys contain the names of modules with updates to be run
369 * and whose values contain the number of the first requested update for that
373 * An array whose keys are the names of all update functions within the
374 * provided modules that would need to be run in order to fulfill the
375 * request, arranged in the order in which the update functions should be
376 * run. (This includes the provided starting update for each module and all
377 * subsequent updates that are available.) The values are themselves arrays
378 * containing all the keys provided by the
379 * Drupal\Component\Graph\Graph::searchAndSort() algorithm, which encode
380 * detailed information about the dependency chain for this update function
381 * (for example: 'paths', 'reverse_paths', 'weight', and 'component'), as
382 * well as the following additional keys:
383 * - 'allowed': A boolean which is TRUE when the update function's
384 * dependencies are met, and FALSE otherwise. Calling functions should
385 * inspect this value before running the update.
386 * - 'missing_dependencies': An array containing the names of any other
387 * update functions that are required by this one but that are unavailable
388 * to be run. This array will be empty when 'allowed' is TRUE.
389 * - 'module': The name of the module that this update function belongs to.
390 * - 'number': The number of this update function within that module.
392 * @see \Drupal\Component\Graph\Graph::searchAndSort()
394 function update_resolve_dependencies($starting_updates) {
395 // Obtain a dependency graph for the requested update functions.
396 $update_functions = update_get_update_function_list($starting_updates);
397 $graph = update_build_dependency_graph($update_functions);
399 // Perform the depth-first search and sort on the results.
400 $graph_object = new Graph($graph);
401 $graph = $graph_object->searchAndSort();
402 uasort($graph, ['Drupal\Component\Utility\SortArray', 'sortByWeightElement']);
404 foreach ($graph as $function => &$data) {
405 $module = $data['module'];
406 $number = $data['number'];
407 // If the update function is missing and has not yet been performed, mark
408 // it and everything that ultimately depends on it as disallowed.
409 if (update_is_missing($module, $number, $update_functions) && !update_already_performed($module, $number)) {
410 $data['allowed'] = FALSE;
411 foreach (array_keys($data['paths']) as $dependent) {
412 $graph[$dependent]['allowed'] = FALSE;
413 $graph[$dependent]['missing_dependencies'][] = $function;
416 elseif (!isset($data['allowed'])) {
417 $data['allowed'] = TRUE;
418 $data['missing_dependencies'] = [];
420 // Now that we have finished processing this function, remove it from the
421 // graph if it was not part of the original list. This ensures that we
422 // never try to run any updates that were not specifically requested.
423 if (!isset($update_functions[$module][$number])) {
424 unset($graph[$function]);
432 * Returns an organized list of update functions for a set of modules.
434 * @param $starting_updates
435 * An array whose keys contain the names of modules and whose values contain
436 * the number of the first requested update for that module.
439 * An array containing all the update functions that should be run for each
440 * module, including the provided starting update and all subsequent updates
441 * that are available. The keys of the array contain the module names, and
442 * each value is an ordered array of update functions, keyed by the update
445 * @see update_resolve_dependencies()
447 function update_get_update_function_list($starting_updates) {
448 // Go through each module and find all updates that we need (including the
449 // first update that was requested and any updates that run after it).
450 $update_functions = [];
451 foreach ($starting_updates as $module => $version) {
452 $update_functions[$module] = [];
453 $updates = drupal_get_schema_versions($module);
454 if ($updates !== FALSE) {
455 $max_version = max($updates);
456 if ($version <= $max_version) {
457 foreach ($updates as $update) {
458 if ($update >= $version) {
459 $update_functions[$module][$update] = $module . '_update_' . $update;
465 return $update_functions;
469 * Constructs a graph which encodes the dependencies between module updates.
471 * This function returns an associative array which contains a "directed graph"
472 * representation of the dependencies between a provided list of update
473 * functions, as well as any outside update functions that they directly depend
474 * on but that were not in the provided list. The vertices of the graph
475 * represent the update functions themselves, and each edge represents a
476 * requirement that the first update function needs to run before the second.
477 * For example, consider this graph:
479 * system_update_8001 ---> system_update_8002 ---> system_update_8003
481 * Visually, this indicates that system_update_8001() must run before
482 * system_update_8002(), which in turn must run before system_update_8003().
484 * The function takes into account standard dependencies within each module, as
485 * shown above (i.e., the fact that each module's updates must run in numerical
486 * order), but also finds any cross-module dependencies that are defined by
487 * modules which implement hook_update_dependencies(), and builds them into the
490 * @param $update_functions
491 * An organized array of update functions, in the format returned by
492 * update_get_update_function_list().
495 * A multidimensional array representing the dependency graph, suitable for
496 * passing in to Drupal\Component\Graph\Graph::searchAndSort(), but with extra
497 * information about each update function also included. Each array key
498 * contains the name of an update function, including all update functions
499 * from the provided list as well as any outside update functions which they
500 * directly depend on. Each value is an associative array containing the
502 * - 'edges': A representation of any other update functions that immediately
503 * depend on this one. See Drupal\Component\Graph\Graph::searchAndSort() for
504 * more details on the format.
505 * - 'module': The name of the module that this update function belongs to.
506 * - 'number': The number of this update function within that module.
508 * @see \Drupal\Component\Graph\Graph::searchAndSort()
509 * @see update_resolve_dependencies()
511 function update_build_dependency_graph($update_functions) {
512 // Initialize an array that will define a directed graph representing the
513 // dependencies between update functions.
516 // Go through each update function and build an initial list of dependencies.
517 foreach ($update_functions as $module => $functions) {
518 $previous_function = NULL;
519 foreach ($functions as $number => $function) {
520 // Add an edge to the directed graph representing the fact that each
521 // update function in a given module must run after the update that
522 // numerically precedes it.
523 if ($previous_function) {
524 $graph[$previous_function]['edges'][$function] = TRUE;
526 $previous_function = $function;
528 // Define the module and update number associated with this function.
529 $graph[$function]['module'] = $module;
530 $graph[$function]['number'] = $number;
534 // Now add any explicit update dependencies declared by modules.
535 $update_dependencies = update_retrieve_dependencies();
536 foreach ($graph as $function => $data) {
537 if (!empty($update_dependencies[$data['module']][$data['number']])) {
538 foreach ($update_dependencies[$data['module']][$data['number']] as $module => $number) {
539 $dependency = $module . '_update_' . $number;
540 $graph[$dependency]['edges'][$function] = TRUE;
541 $graph[$dependency]['module'] = $module;
542 $graph[$dependency]['number'] = $number;
551 * Determines if a module update is missing or unavailable.
554 * The name of the module.
556 * The number of the update within that module.
557 * @param $update_functions
558 * An organized array of update functions, in the format returned by
559 * update_get_update_function_list(). This should represent all module
560 * updates that are requested to run at the time this function is called.
563 * TRUE if the provided module update is not installed or is not in the
564 * provided list of updates to run; FALSE otherwise.
566 function update_is_missing($module, $number, $update_functions) {
567 return !isset($update_functions[$module][$number]) || !function_exists($update_functions[$module][$number]);
571 * Determines if a module update has already been performed.
574 * The name of the module.
576 * The number of the update within that module.
579 * TRUE if the database schema indicates that the update has already been
580 * performed; FALSE otherwise.
582 function update_already_performed($module, $number) {
583 return $number <= drupal_get_installed_schema_version($module);
587 * Invokes hook_update_dependencies() in all installed modules.
589 * This function is similar to \Drupal::moduleHandler()->invokeAll(), with the
590 * main difference that it does not require that a module be enabled to invoke
591 * its hook, only that it be installed. This allows the update system to
592 * properly perform updates even on modules that are currently disabled.
595 * An array of return values obtained by merging the results of the
596 * hook_update_dependencies() implementations in all installed modules.
598 * @see \Drupal\Core\Extension\ModuleHandlerInterface::invokeAll()
599 * @see hook_update_dependencies()
601 function update_retrieve_dependencies() {
603 // Get a list of installed modules, arranged so that we invoke their hooks in
604 // the same order that \Drupal::moduleHandler()->invokeAll() does.
605 foreach (\Drupal::keyValue('system.schema')->getAll() as $module => $schema) {
606 if ($schema == SCHEMA_UNINSTALLED) {
607 // Nothing to upgrade.
610 $function = $module . '_update_dependencies';
611 // Ensure install file is loaded.
612 module_load_install($module);
613 if (function_exists($function)) {
614 $updated_dependencies = $function();
615 // Each implementation of hook_update_dependencies() returns a
616 // multidimensional, associative array containing some keys that
617 // represent module names (which are strings) and other keys that
618 // represent update function numbers (which are integers). We cannot use
619 // array_merge_recursive() to properly merge these results, since it
620 // treats strings and integers differently. Therefore, we have to
621 // explicitly loop through the expected array structure here and perform
622 // the merge manually.
623 if (isset($updated_dependencies) && is_array($updated_dependencies)) {
624 foreach ($updated_dependencies as $module_name => $module_data) {
625 foreach ($module_data as $update_version => $update_data) {
626 foreach ($update_data as $module_dependency => $update_dependency) {
627 // If there are redundant dependencies declared for the same
628 // update function (so that it is declared to depend on more than
629 // one update from a particular module), record the dependency on
630 // the highest numbered update here, since that automatically
631 // implies the previous ones. For example, if one module's
632 // implementation of hook_update_dependencies() required this
635 // system_update_8002 ---> user_update_8001
637 // but another module's implementation of the hook required this
640 // system_update_8003 ---> user_update_8001
642 // we record the second one, since system_update_8002() is always
643 // guaranteed to run before system_update_8003() anyway (within
644 // an individual module, updates are always run in numerical
646 if (!isset($return[$module_name][$update_version][$module_dependency]) || $update_dependency > $return[$module_name][$update_version][$module_dependency]) {
647 $return[$module_name][$update_version][$module_dependency] = $update_dependency;
660 * Replace permissions during update.
662 * This function can replace one permission to several or even delete an old
665 * @param array $replace
666 * An associative array. The keys are the old permissions the values are lists
667 * of new permissions. If the list is an empty array, the old permission is
670 function update_replace_permissions($replace) {
671 $prefix = 'user.role.';
672 $cut = strlen($prefix);
673 $role_names = \Drupal::service('config.storage')->listAll($prefix);
674 foreach ($role_names as $role_name) {
675 $rid = substr($role_name, $cut);
676 $config = \Drupal::config("user.role.$rid");
677 $permissions = $config->get('permissions') ?: [];
678 foreach ($replace as $old_permission => $new_permissions) {
679 if (($index = array_search($old_permission, $permissions)) !== FALSE) {
680 unset($permissions[$index]);
681 $permissions = array_unique(array_merge($permissions, $new_permissions));
685 ->set('permissions', $permissions)