class ConfigEntityUpdater

Same name in other branches
  1. 9 core/lib/Drupal/Core/Config/Entity/ConfigEntityUpdater.php \Drupal\Core\Config\Entity\ConfigEntityUpdater
  2. 10 core/lib/Drupal/Core/Config/Entity/ConfigEntityUpdater.php \Drupal\Core\Config\Entity\ConfigEntityUpdater
  3. 11.x core/lib/Drupal/Core/Config/Entity/ConfigEntityUpdater.php \Drupal\Core\Config\Entity\ConfigEntityUpdater

A utility class to make updating configuration entities simple.

Use this in a post update function like so:

// Ensure Taxonomy module installed before trying to update vocabularies.
if (\Drupal::moduleHandler()->moduleExists('taxonomy')) {
    // Update the dependencies of all Vocabulary configuration entities.
    \Drupal::classResolver(ConfigEntityUpdater::class)->update($sandbox, 'taxonomy_vocabulary');
}

The number of entities processed in each batch is determined by the 'entity_update_batch_size' setting.

Hierarchy

Expanded class hierarchy of ConfigEntityUpdater

See also

default.settings.php

12 files declare their use of ConfigEntityUpdater
action.post_update.php in core/modules/action/action.post_update.php
Post update functions for Action module.
block_content.post_update.php in core/modules/block_content/block_content.post_update.php
Post update functions for Custom Block.
ConfigEntityUpdaterTest.php in core/tests/Drupal/KernelTests/Core/Config/Entity/ConfigEntityUpdaterTest.php
content_moderation.post_update.php in core/modules/content_moderation/content_moderation.post_update.php
Post update functions for the Content Moderation module.
image.post_update.php in core/modules/image/image.post_update.php
Post-update functions for Image.

... See full list

File

core/lib/Drupal/Core/Config/Entity/ConfigEntityUpdater.php, line 26

Namespace

Drupal\Core\Config\Entity
View source
class ConfigEntityUpdater implements ContainerInjectionInterface {
    
    /**
     * The key used to store information in the update sandbox.
     */
    const SANDBOX_KEY = 'config_entity_updater';
    
    /**
     * The entity type manager.
     *
     * @var \Drupal\Core\Entity\EntityTypeManagerInterface
     */
    protected $entityTypeManager;
    
    /**
     * The number of entities to process in each batch.
     * @var int
     */
    protected $batchSize;
    
    /**
     * ConfigEntityUpdater constructor.
     *
     * @param \Drupal\Core\Entity\EntityTypeManagerInterface $entity_type_manager
     *   The entity type manager.
     * @param int $batch_size
     *   The number of entities to process in each batch.
     */
    public function __construct(EntityTypeManagerInterface $entity_type_manager, $batch_size) {
        $this->entityTypeManager = $entity_type_manager;
        $this->batchSize = $batch_size;
    }
    
    /**
     * {@inheritdoc}
     */
    public static function create(ContainerInterface $container) {
        return new static($container->get('entity_type.manager'), $container->get('settings')
            ->get('entity_update_batch_size', 50));
    }
    
    /**
     * Updates configuration entities as part of a Drupal update.
     *
     * @param array $sandbox
     *   Stores information for batch updates.
     * @param string $entity_type_id
     *   The configuration entity type ID. For example, 'view' or 'vocabulary'.
     *   The calling code should ensure that the entity type exists beforehand
     *   (i.e., by checking that the entity type is defined or that the module
     *   that provides it is installed).
     * @param callable $callback
     *   (optional) A callback to determine if a configuration entity should be
     *   saved. The callback will be passed each entity of the provided type that
     *   exists. The callback should not save an entity itself. Return TRUE to
     *   save an entity. The callback can make changes to an entity. Note that all
     *   changes should comply with schema as an entity's data will not be
     *   validated against schema on save to avoid unexpected errors. If a
     *   callback is not provided, the default behavior is to update the
     *   dependencies if required.
     *
     * @see hook_post_update_NAME()
     *
     * @api
     *
     * @throws \InvalidArgumentException
     *   Thrown when the provided entity type ID is not a configuration entity
     *   type.
     * @throws \RuntimeException
     *   Thrown when used twice in the same update function for different entity
     *   types. This method should only be called once per update function.
     */
    public function update(array &$sandbox, $entity_type_id, callable $callback = NULL) {
        $storage = $this->entityTypeManager
            ->getStorage($entity_type_id);
        if (isset($sandbox[self::SANDBOX_KEY]) && $sandbox[self::SANDBOX_KEY]['entity_type'] !== $entity_type_id) {
            throw new \RuntimeException('Updating multiple entity types in the same update function is not supported');
        }
        if (!isset($sandbox[self::SANDBOX_KEY])) {
            $entity_type = $this->entityTypeManager
                ->getDefinition($entity_type_id);
            if (!$entity_type instanceof ConfigEntityTypeInterface) {
                throw new \InvalidArgumentException("The provided entity type ID '{$entity_type_id}' is not a configuration entity type");
            }
            $sandbox[self::SANDBOX_KEY]['entity_type'] = $entity_type_id;
            $sandbox[self::SANDBOX_KEY]['entities'] = $storage->getQuery()
                ->accessCheck(FALSE)
                ->execute();
            $sandbox[self::SANDBOX_KEY]['count'] = count($sandbox[self::SANDBOX_KEY]['entities']);
        }
        // The default behavior is to fix dependencies.
        if ($callback === NULL) {
            $callback = function ($entity) {
                
                /** @var \Drupal\Core\Config\Entity\ConfigEntityInterface $entity */
                $original_dependencies = $entity->getDependencies();
                return $original_dependencies !== $entity->calculateDependencies()
                    ->getDependencies();
            };
        }
        
        /** @var \Drupal\Core\Config\Entity\ConfigEntityInterface $entity */
        $entities = $storage->loadMultiple(array_splice($sandbox[self::SANDBOX_KEY]['entities'], 0, $this->batchSize));
        foreach ($entities as $entity) {
            if (call_user_func($callback, $entity)) {
                $entity->trustData();
                $entity->save();
            }
        }
        $sandbox['#finished'] = empty($sandbox[self::SANDBOX_KEY]['entities']) ? 1 : ($sandbox[self::SANDBOX_KEY]['count'] - count($sandbox[self::SANDBOX_KEY]['entities'])) / $sandbox[self::SANDBOX_KEY]['count'];
    }

}

Members

Title Sort descending Modifiers Object type Summary Overriden Title
ConfigEntityUpdater::$batchSize protected property The number of entities to process in each batch.
ConfigEntityUpdater::$entityTypeManager protected property The entity type manager.
ConfigEntityUpdater::create public static function Instantiates a new instance of this class. Overrides ContainerInjectionInterface::create
ConfigEntityUpdater::SANDBOX_KEY constant The key used to store information in the update sandbox.
ConfigEntityUpdater::update public function Updates configuration entities as part of a Drupal update.
ConfigEntityUpdater::__construct public function ConfigEntityUpdater constructor.

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.