Same name in other branches

1. 9 core/lib/Drupal/Core/Extension/module.api.php \hook_post_update_NAME()
2. 10 core/lib/Drupal/Core/Extension/module.api.php \hook_post_update_NAME()
3. 11.x core/lib/Drupal/Core/Extension/module.api.php \hook_post_update_NAME()

Executes an update which is intended to update data, like entities.

These implementations have to be placed in a MODULE.post_update.php file.

These updates are executed after all hook_update_N() implementations. At this stage Drupal is already fully repaired so you can use any API as you wish.

NAME can be arbitrary machine names. In contrast to hook_update_N() the alphanumeric naming of functions in the file is the only thing which ensures the execution order of those functions. If update order is mandatory, you should add numerical prefix to NAME or make it completely numerical.

Drupal also ensures to not execute the same hook_post_update_NAME() function twice.

Batch updates

If running your update all at once could possibly cause PHP to time out, use the $sandbox parameter to indicate that the Batch API should be used for your update. In this case, your update function acts as an implementation of callback_batch_operation(), and $sandbox acts as the batch context parameter. In your function, read the state information from the previous run from $sandbox (or initialize), run a chunk of updates, save the state in $sandbox, and set $sandbox['#finished'] to a value between 0 and 1 to indicate the percent completed, or 1 if it is finished (you need to do this explicitly in each pass).

See the Batch operations topic for more information on how to use the Batch API.

Parameters

array $sandbox: Stores information for batch updates. See above for more information.

Return value

string|null Optionally, hook_post_update_NAME() hooks may return a translated string that will be displayed to the user after the update has completed. If no message is returned, no message will be presented to the user.

Throws

\Drupal\Core\Utility\UpdateException|PDOException In case of error, update hooks should throw an instance of \Drupal\Core\Utility\UpdateException with a meaningful message for the user. If a database query fails for whatever reason, it will throw a PDOException.

See also

hook_update_N()

hook_removed_post_updates()

Related topics

129 functions implement hook_post_update_NAME()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

action_post_update_move_plugins in core/modules/action/action.post_update.php

Moves action plugins to core.

action_post_update_remove_settings in core/modules/action/action.post_update.php

Removes action settings.

block_content_post_update_add_views_reusable_filter in core/modules/block_content/block_content.post_update.php

Adds a 'reusable' filter to all Custom Block views.

block_post_update_disabled_region_update in core/modules/block/block.post_update.php

Disable blocks that are placed into the "disabled" region.

block_post_update_disable_blocks_with_missing_contexts in core/modules/block/block.post_update.php

Disable all blocks with missing context IDs in block_update_8001().

... See full list

File

core/lib/Drupal/Core/Extension/module.api.php, line 746

Code

function hook_post_update_NAME(&$sandbox) {
    // Example of updating some content.
    $node = \Drupal\node\Entity\Node::load(123);
    $node->setTitle('foo');
    $node->save();
    $result = t('Node %nid saved', [
        '%nid' => $node->id(),
    ]);
    // Example of disabling blocks with missing condition contexts. Note: The
    // block itself is in a state which is valid at that point.
    // @see block_update_8001()
    // @see block_post_update_disable_blocks_with_missing_contexts()
    $block_update_8001 = \Drupal::keyValue('update_backup')->get('block_update_8001', []);
    $block_ids = array_keys($block_update_8001);
    $block_storage = \Drupal::entityTypeManager()->getStorage('block');
    $blocks = $block_storage->loadMultiple($block_ids);
    
    /** @var $blocks \Drupal\block\BlockInterface[] */
    foreach ($blocks as $block) {
        // This block has had conditions removed due to an inability to resolve
        // contexts in block_update_8001() so disable it.
        // Disable currently enabled blocks.
        if ($block_update_8001[$block->id()]['status']) {
            $block->setStatus(FALSE);
            $block->save();
        }
    }
    return $result;
}

---