SqlFieldableEntityTypeListenerTrait.php

<?php

namespace Drupal\Core\Entity\Sql;

use Drupal\Core\Entity\EntityStorageException;
use Drupal\Core\Entity\EntityTypeInterface;
use Drupal\Core\Site\Settings;

/**
 * Helper methods for EntityTypeListenerInterface.
 *
 * @see \Drupal\Core\Entity\EntityTypeListenerInterface
 *
 * @property \Drupal\Core\Entity\EntityTypeManagerInterface entityTypeManager
 * @property \Drupal\Core\Database\Connection database
 *
 * @internal
 */
trait SqlFieldableEntityTypeListenerTrait {

  /**
   * {@inheritdoc}
   */
  public function onFieldableEntityTypeUpdate(EntityTypeInterface $entity_type, EntityTypeInterface $original, array $field_storage_definitions, array $original_field_storage_definitions, array &$sandbox = NULL) {
    /** @var \Drupal\Core\Entity\EntityStorageInterface $original_storage */
    $original_storage = $this->entityTypeManager->createHandlerInstance($original->getStorageClass(), $original);
    $has_data = $original_storage->hasData();

    // If 'progress' is not set, then this will be the first run of the batch.
    if (!isset($sandbox['progress'])) {
      // We cannot support updating the schema of an entity type from
      // revisionable to non-revisionable or translatable to non-translatable
      // because that can lead to unintended data loss.
      // @todo Add support for these conversions in case there is no data loss.
      //   @see https://www.drupal.org/project/drupal/issues/3024727
      $convert_rev_to_non_rev = $original->isRevisionable() && !$entity_type->isRevisionable();
      $convert_mul_to_non_mul = $original->isTranslatable() && !$entity_type->isTranslatable();
      if ($has_data && ($convert_rev_to_non_rev || $convert_mul_to_non_mul)) {
        throw new EntityStorageException('Converting an entity type from revisionable to non-revisionable or from translatable to non-translatable is not supported.');
      }

      // Check that the fields required by a revisionable entity type exist.
      if ($entity_type->isRevisionable() && !isset($field_storage_definitions[$entity_type->getKey('revision')])) {
        throw new EntityStorageException('Missing revision field.');
      }
      if ($entity_type->isRevisionable() && !isset($field_storage_definitions[$entity_type->getRevisionMetadataKey('revision_default')])) {
        throw new EntityStorageException('Missing revision_default field.');
      }

      // Check that the fields required by a translatable entity type exist.
      if ($entity_type->isTranslatable() && !isset($field_storage_definitions[$entity_type->getKey('langcode')])) {
        throw new EntityStorageException('Missing langcode field.');
      }
      if ($entity_type->isTranslatable() && !isset($field_storage_definitions[$entity_type->getKey('default_langcode')])) {
        throw new EntityStorageException('Missing default_langcode field.');
      }

      // Check that the fields required by a revisionable and translatable
      // entity type exist.
      if ($entity_type->isRevisionable() && $entity_type->isTranslatable() && !isset($field_storage_definitions[$entity_type->getKey('revision_translation_affected')])) {
        throw new EntityStorageException('Missing revision_translation_affected field.');
      }

      $this->preUpdateEntityTypeSchema($entity_type, $original, $field_storage_definitions, $original_field_storage_definitions, $sandbox);
    }

    // Copy data from the original storage to the temporary one.
    if ($has_data) {
      $this->copyData($entity_type, $original, $field_storage_definitions, $original_field_storage_definitions, $sandbox);
    }
    else {
      // If there is no existing data, we still need to run the
      // post-schema-update tasks.
      $sandbox['#finished'] = 1;
    }

    // If the data copying has finished successfully, allow the storage schema
    // to do any required cleanup tasks. For example, this process should take
    // care of transforming the temporary storage into the current storage.
    if ($sandbox['#finished'] == 1) {
      $this->postUpdateEntityTypeSchema($entity_type, $original, $field_storage_definitions, $original_field_storage_definitions, $sandbox);
    }
  }

  /**
   * Allows subscribers to prepare their schema before data copying.
   *
   * @param \Drupal\Core\Entity\EntityTypeInterface $entity_type
   *   The updated entity type definition.
   * @param \Drupal\Core\Entity\EntityTypeInterface $original
   *   The original entity type definition.
   * @param \Drupal\Core\Field\FieldStorageDefinitionInterface[] $field_storage_definitions
   *   The updated field storage definitions, including possibly new ones.
   * @param \Drupal\Core\Field\FieldStorageDefinitionInterface[] $original_field_storage_definitions
   *   The original field storage definitions.
   * @param array &$sandbox
   *   (optional) A sandbox array provided by a hook_update_N() implementation
   *   or a Batch API callback. If the entity schema update requires a data
   *   migration, this parameter is mandatory. Defaults to NULL.
   */
  protected function preUpdateEntityTypeSchema(EntityTypeInterface $entity_type, EntityTypeInterface $original, array $field_storage_definitions, array $original_field_storage_definitions, array &$sandbox = NULL) {
  }

  /**
   * Allows subscribers to do any cleanup necessary after data copying.
   *
   * @param \Drupal\Core\Entity\EntityTypeInterface $entity_type
   *   The updated entity type definition.
   * @param \Drupal\Core\Entity\EntityTypeInterface $original
   *   The original entity type definition.
   * @param \Drupal\Core\Field\FieldStorageDefinitionInterface[] $field_storage_definitions
   *   The updated field storage definitions, including possibly new ones.
   * @param \Drupal\Core\Field\FieldStorageDefinitionInterface[] $original_field_storage_definitions
   *   The original field storage definitions.
   * @param array &$sandbox
   *   (optional) A sandbox array provided by a hook_update_N() implementation
   *   or a Batch API callback. If the entity schema update requires a data
   *   migration, this parameter is mandatory. Defaults to NULL.
   */
  protected function postUpdateEntityTypeSchema(EntityTypeInterface $entity_type, EntityTypeInterface $original, array $field_storage_definitions, array $original_field_storage_definitions, array &$sandbox = NULL) {
  }

  /**
   * Copies entity data from the original storage to the temporary one.
   *
   * @param \Drupal\Core\Entity\EntityTypeInterface $entity_type
   *   The updated entity type definition.
   * @param \Drupal\Core\Entity\EntityTypeInterface $original
   *   The original entity type definition.
   * @param \Drupal\Core\Field\FieldStorageDefinitionInterface[] $field_storage_definitions
   *   The updated field storage definitions, including possibly new ones.
   * @param \Drupal\Core\Field\FieldStorageDefinitionInterface[] $original_field_storage_definitions
   *   The original field storage definitions.
   * @param array &$sandbox
   *   The sandbox array from a hook_update_N() implementation.
   */
  protected function copyData(EntityTypeInterface $entity_type, EntityTypeInterface $original, array $field_storage_definitions, array $original_field_storage_definitions, array &$sandbox) {
    /** @var \Drupal\Core\Entity\ContentEntityTypeInterface $entity_type */
    $id_key = $entity_type->getKey('id');
    $revision_id_key = $entity_type->getKey('revision');
    $revision_default_key = $entity_type->getRevisionMetadataKey('revision_default');
    $langcode_key = $entity_type->getKey('langcode');
    $default_langcode_key = $entity_type->getKey('default_langcode');
    $revision_translation_affected_key = $entity_type->getKey('revision_translation_affected');

    // If 'progress' is not set, then this will be the first run of the batch.
    if (!isset($sandbox['progress'])) {
      $sandbox['progress'] = 0;
      $sandbox['current_id'] = -1;
    }

    // If the original entity type is revisionable, we need to copy all the
    // revisions.
    $load_revisions = $original->isRevisionable();
    if ($load_revisions) {
      $table_name = $original->getRevisionTable();
      $identifier_field = $revision_id_key;
    }
    else {
      $table_name = $original->getBaseTable();
      $identifier_field = $id_key;
    }

    // Get the next entity identifiers to migrate.
    // @todo Use an entity query when it is able to use the last installed
    //   entity type and field storage definitions.
    // @see https://www.drupal.org/project/drupal/issues/2554235
    $step_size = Settings::get('entity_update_batch_size', 50);
    $entity_identifiers = $this->database->select($table_name, 't')
      ->condition("t.$identifier_field", $sandbox['current_id'], '>')
      ->fields('t', [$identifier_field])
      ->orderBy($identifier_field, 'ASC')
      ->range(0, $step_size)
      ->execute()
      ->fetchCol();

    /** @var \Drupal\Core\Entity\ContentEntityInterface[] $entities */
    $entities = $load_revisions ? $this->storage->loadMultipleRevisions($entity_identifiers) : $this->storage->loadMultiple($entity_identifiers);

    /** @var \Drupal\Core\Entity\Sql\SqlContentEntityStorage $temporary_storage */
    $temporary_storage = $this->entityTypeManager->createHandlerInstance($entity_type->getStorageClass(), $entity_type);
    $temporary_storage->setEntityType($entity_type);
    $temporary_storage->setFieldStorageDefinitions($field_storage_definitions);
    $temporary_storage->setTableMapping($sandbox['temporary_table_mapping']);

    foreach ($entities as $identifier => $entity) {
      try {
        if (!$original->isRevisionable() && $entity_type->isRevisionable()) {
          // Set the revision ID to be same as the entity ID.
          $entity->set($revision_id_key, $entity->id());

          // We had no revisions so far, so the existing data belongs to the
          // default revision now.
          $entity->set($revision_default_key, TRUE);
        }

        // Set the 'langcode' and 'default_langcode' values as needed.
        if (!$original->isTranslatable() && $entity_type->isTranslatable()) {
          if ($entity->get($langcode_key)->isEmpty()) {
            $entity->set($langcode_key, \Drupal::languageManager()->getDefaultLanguage()->getId());
          }

          $entity->set($default_langcode_key, TRUE);
        }

        // Set the 'revision_translation_affected' field to TRUE to match the
        // return value of the case when the field does not exist.
        if ((!$original->isRevisionable() || !$original->isTranslatable()) && $entity_type->isRevisionable() && $entity_type->isTranslatable()) {
          $entity->set($revision_translation_affected_key, TRUE);
        }

        // Finally, save the entity in the temporary storage.
        $temporary_storage->restore($entity);
      }
      catch (\Exception $e) {
        $this->handleEntityTypeSchemaUpdateExceptionOnDataCopy($entity_type, $original, $sandbox);

        // Re-throw the original exception with a helpful message.
        $error_revision_id = $load_revisions ? ", revision ID: {$entity->getLoadedRevisionId()}" : '';
        throw new EntityStorageException("The entity update process failed while processing the entity type {$entity_type->id()}, ID: {$entity->id()}$error_revision_id.", $e->getCode(), $e);
      }

      $sandbox['progress']++;
      $sandbox['current_id'] = $identifier;
    }

    // Reset the cache in order to free memory as we progress.
    \Drupal::service('entity.memory_cache')->deleteAll();

    // Get an updated count of entities that still need to migrated to the new
    // storage.
    $missing = $this->database->select($table_name, 't')
      ->condition("t.$identifier_field", $sandbox['current_id'], '>')
      ->orderBy($identifier_field, 'ASC')
      ->countQuery()
      ->execute()
      ->fetchField();
    $sandbox['#finished'] = $missing ? $sandbox['progress'] / ($sandbox['progress'] + (int) $missing) : 1;
  }

  /**
   * Handles the case when an error occurs during the data copying step.
   *
   * @param \Drupal\Core\Entity\EntityTypeInterface $entity_type
   *   The updated entity type definition.
   * @param \Drupal\Core\Entity\EntityTypeInterface $original
   *   The original entity type definition.
   * @param array &$sandbox
   *   The sandbox array from a hook_update_N() implementation.
   */
  protected function handleEntityTypeSchemaUpdateExceptionOnDataCopy(EntityTypeInterface $entity_type, EntityTypeInterface $original, array &$sandbox) {
  }

}