ConfigEntityUpdater.php

<?php

namespace Drupal\Core\Config\Entity;

use Drupal\Core\DependencyInjection\ContainerInjectionInterface;
use Drupal\Core\Entity\EntityTypeManagerInterface;
use Drupal\Core\StringTranslation\TranslatableMarkup;
use Drupal\Core\Url;
use Drupal\Core\Utility\Error;
use Symfony\Component\DependencyInjection\ContainerInterface;

/**
 * A utility class to make updating configuration entities simple.
 *
 * Use this in a post update function like so:
 * @code
 * // 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');
 * }
 * @endcode
 *
 * The number of entities processed in each batch is determined by the
 * 'entity_update_batch_size' setting.
 *
 * @see default.settings.php
 */
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.
     * @param bool $continue_on_error
     *   Set to TRUE to continue updating if an error has occurred.
     *
     * @see hook_post_update_NAME()
     *
     * @api
     *
     * @return \Drupal\Core\StringTranslation\TranslatableMarkup|null
     *   An error message if $continue_on_error is set to TRUE and an error has
     *   occurred.
     *
     * @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, bool $continue_on_error = FALSE) {
        $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']);
            $sandbox[self::SANDBOX_KEY]['failed_entity_ids'] = [];
        }
        // 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) {
            try {
                if ($continue_on_error) {
                    // If we're continuing on error silence errors from notices that
                    // missing indexes.
                    // @todo consider change this to an error handler that converts such
                    //   notices to exceptions in https://www.drupal.org/node/3309886
                    @$this->doOne($entity, $callback);
                }
                else {
                    $this->doOne($entity, $callback);
                }
            } catch (\Throwable $throwable) {
                if (!$continue_on_error) {
                    throw $throwable;
                }
                $context['%view'] = $entity->id();
                $context['%entity_type'] = $entity_type_id;
                $context += Error::decodeException($throwable);
                \Drupal::logger('update')->error('Unable to update %entity_type %view due to error @message %function (line %line of %file). <pre>@backtrace_string</pre>', $context);
                $sandbox[self::SANDBOX_KEY]['failed_entity_ids'][] = $entity->id();
            }
        }
        $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'];
        if (!empty($sandbox[self::SANDBOX_KEY]['failed_entity_ids'])) {
            $entity_type = $this->entityTypeManager
                ->getDefinition($entity_type_id);
            if (\Drupal::moduleHandler()->moduleExists('dblog')) {
                return new TranslatableMarkup('Updates failed for the entity type %entity_type, for %entity_ids. <a href=":url">Check the logs</a>.', [
                    '%entity_type' => $entity_type->getLabel(),
                    '%entity_ids' => implode(', ', $sandbox[self::SANDBOX_KEY]['failed_entity_ids']),
                    ':url' => Url::fromRoute('dblog.overview')->toString(),
                ]);
            }
            else {
                return new TranslatableMarkup("Updates failed for the entity type %entity_type, for %entity_ids. Check the logs.", [
                    '%entity_type' => $entity_type->getLabel(),
                    '%entity_ids' => implode(', ', $sandbox[self::SANDBOX_KEY]['failed_entity_ids']),
                ]);
            }
        }
    }
    
    /**
     * Apply the callback an entity and save it if the callback makes changes.
     *
     * @param \Drupal\Core\Config\Entity\ConfigEntityInterface $entity
     *   The entity to potentially update.
     * @param callable $callback
     *   The callback to apply.
     */
    protected function doOne(ConfigEntityInterface $entity, callable $callback) {
        if (call_user_func($callback, $entity)) {
            $entity->trustData();
            $entity->save();
        }
    }

}