www.aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Entity/Schema/EntityStorageSchemaInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Entity\Schema;
   4
   5 use Drupal\Core\Entity\EntityTypeInterface;
   6 use Drupal\Core\Entity\EntityTypeListenerInterface;
   7
   8 /**
   9  * Defines the interface for entity storage schema handler classes.
  10  *
  11  * An entity type's storage schema handler is responsible for creating the
  12  * storage backend's schema that the entity type's storage handler needs for
  13  * storing its entities. For example, if the storage handler is for a SQL
  14  * backend, then the storage schema handler is responsible for creating the
  15  * needed tables. During the application lifetime, an entity type's definition
  16  * can change in a way that requires changes to the storage schema, so this
  17  * interface defines methods for that as well.
  18  *
  19  * @see \Drupal\Core\Entity\EntityStorageInterface
  20  */
  21 interface EntityStorageSchemaInterface extends EntityTypeListenerInterface {
  22
  23   /**
  24    * Checks if the changes to the entity type requires storage schema changes.
  25    *
  26    * @param \Drupal\Core\Entity\EntityTypeInterface $entity_type
  27    *   The updated entity type definition.
  28    * @param \Drupal\Core\Entity\EntityTypeInterface $original
  29    *   The original entity type definition.
  30    *
  31    * @return bool
  32    *   TRUE if storage schema changes are required, FALSE otherwise.
  33    */
  34   public function requiresEntityStorageSchemaChanges(EntityTypeInterface $entity_type, EntityTypeInterface $original);
  35
  36   /**
  37    * Checks if existing data would be lost if the schema changes were applied.
  38    *
  39    * If there are no schema changes needed, then no data needs to be migrated,
  40    * but it is not the responsibility of this function to recheck what
  41    * requiresEntityStorageSchemaChanges() checks. Rather, the meaning of what
  42    * this function returns when requiresEntityStorageSchemaChanges() returns
  43    * FALSE is undefined. Callers are expected to only call this function when
  44    * requiresEntityStorageSchemaChanges() is TRUE.
  45    *
  46    * This function can return FALSE if any of these conditions apply:
  47    * - There are no existing entities for the entity type.
  48    * - There are existing entities, but the schema changes can be applied
  49    *   without losing their data (e.g., if the schema changes can be performed
  50    *   by altering tables rather than dropping and recreating them).
  51    * - The only entity data that would be lost are ones that are not valid for
  52    *   the new definition (e.g., if changing an entity type from revisionable
  53    *   to non-revisionable, then it's okay to drop data for the non-default
  54    *   revision).
  55    *
  56    * When this function returns FALSE, site administrators will be unable to
  57    * perform an automated update, and will instead need to perform a site
  58    * migration or invoke some custom update process.
  59    *
  60    * @param \Drupal\Core\Entity\EntityTypeInterface $entity_type
  61    *   The updated entity type definition.
  62    * @param \Drupal\Core\Entity\EntityTypeInterface $original
  63    *   The original entity type definition.
  64    *
  65    * @return bool
  66    *   TRUE if data migration is required, FALSE otherwise.
  67    *
  68    * @see self::requiresEntityStorageSchemaChanges()
  69    */
  70   public function requiresEntityDataMigration(EntityTypeInterface $entity_type, EntityTypeInterface $original);
  71
  72 }