Chris@0: <?php
Chris@0: 
Chris@0: /**
Chris@0:  * @file
Chris@0:  * Provides support for field data purge after mass deletion.
Chris@0:  */
Chris@0: 
Chris@14: use Drupal\Core\Field\FieldDefinitionInterface;
Chris@0: use Drupal\Core\Field\FieldException;
Chris@14: use Drupal\Core\Field\FieldStorageDefinitionInterface;
Chris@0: 
Chris@0: /**
Chris@0:  * @defgroup field_purge Field API bulk data deletion
Chris@0:  * @{
Chris@0:  * Cleans up after Field API bulk deletion operations.
Chris@0:  *
Chris@0:  * Field API provides functions for deleting data attached to individual
Chris@0:  * entities as well as deleting entire fields or field storages in a single
Chris@0:  * operation.
Chris@0:  *
Chris@0:  * When a single entity is deleted, the Entity storage performs the
Chris@0:  * following operations:
Chris@0:  * - Invoking the method \Drupal\Core\Field\FieldItemListInterface::delete() for
Chris@0:  *   each field on the entity. A file field type might use this method to delete
Chris@0:  *   uploaded files from the filesystem.
Chris@0:  * - Removing the data from storage.
Chris@0:  * - Invoking the global hook_entity_delete() for all modules that implement it.
Chris@0:  *   Each hook implementation receives the entity being deleted and can operate
Chris@0:  *   on whichever subset of the entity's bundle's fields it chooses to.
Chris@0:  *
Chris@0:  * Similar operations are performed on deletion of a single entity revision.
Chris@0:  *
Chris@0:  * When a bundle, field or field storage is deleted, it is not practical to
Chris@0:  * perform those operations immediately on every affected entity in a single
Chris@0:  * page request; there could be thousands or millions of them. Instead, the
Chris@0:  * appropriate field data items, fields, and/or field storages are marked as
Chris@0:  * deleted so that subsequent load or query operations will not return them.
Chris@0:  * Later, a separate process cleans up, or "purges", the marked-as-deleted data
Chris@0:  * by going through the three-step process described above and, finally,
Chris@0:  * removing deleted field storage and field records.
Chris@0:  *
Chris@0:  * Purging field data is made somewhat tricky by the fact that, while
Chris@0:  * $entity->delete() has a complete entity to pass to the various deletion
Chris@0:  * steps, the Field API purge process only has the field data it has previously
Chris@0:  * stored. It cannot reconstruct complete original entities to pass to the
Chris@0:  * deletion operations. It is even possible that the original entity to which
Chris@0:  * some Field API data was attached has been itself deleted before the field
Chris@0:  * purge operation takes place.
Chris@0:  *
Chris@0:  * Field API resolves this problem by using stub entities during purge
Chris@0:  * operations, containing only the information from the original entity that
Chris@0:  * Field API knows about: entity type, ID, revision ID, and bundle. It also
Chris@0:  * contains the field data for whichever field is currently being purged.
Chris@0:  *
Chris@0:  * See @link field Field API @endlink for information about the other parts of
Chris@0:  * the Field API.
Chris@0:  */
Chris@0: 
Chris@0: /**
Chris@0:  * Purges a batch of deleted Field API data, field storages, or fields.
Chris@0:  *
Chris@0:  * This function will purge deleted field data in batches. The batch size
Chris@0:  * is defined as an argument to the function, and once each batch is finished,
Chris@0:  * it continues with the next batch until all have completed. If a deleted field
Chris@0:  * with no remaining data records is found, the field itself will
Chris@0:  * be purged. If a deleted field storage with no remaining fields is found, the
Chris@0:  * field storage itself will be purged.
Chris@0:  *
Chris@14:  * @param int $batch_size
Chris@0:  *   The maximum number of field data records to purge before returning.
Chris@14:  * @param string $field_storage_unique_id
Chris@14:  *   (optional) Limit the purge to a specific field storage. Defaults to NULL.
Chris@0:  */
Chris@14: function field_purge_batch($batch_size, $field_storage_unique_id = NULL) {
Chris@14:   /** @var \Drupal\Core\Field\DeletedFieldsRepositoryInterface $deleted_fields_repository */
Chris@14:   $deleted_fields_repository = \Drupal::service('entity_field.deleted_fields_repository');
Chris@14: 
Chris@14:   $fields = $deleted_fields_repository->getFieldDefinitions($field_storage_unique_id);
Chris@0: 
Chris@0:   $info = \Drupal::entityManager()->getDefinitions();
Chris@0:   foreach ($fields as $field) {
Chris@0:     $entity_type = $field->getTargetEntityTypeId();
Chris@0: 
Chris@0:     // We cannot purge anything if the entity type is unknown (e.g. the
Chris@0:     // providing module was uninstalled).
Chris@0:     // @todo Revisit after https://www.drupal.org/node/2080823.
Chris@0:     if (!isset($info[$entity_type])) {
Chris@14:       \Drupal::logger('field')->warning("Cannot remove field @field_name because the entity type is unknown: %entity_type", ['@field_name' => $field->getName(), '%entity_type' => $entity_type]);
Chris@0:       continue;
Chris@0:     }
Chris@0: 
Chris@0:     $count_purged = \Drupal::entityManager()->getStorage($entity_type)->purgeFieldData($field, $batch_size);
Chris@0:     if ($count_purged < $batch_size || $count_purged == 0) {
Chris@0:       // No field data remains for the field, so we can remove it.
Chris@0:       field_purge_field($field);
Chris@0:     }
Chris@0:     $batch_size -= $count_purged;
Chris@0:     // Only delete up to the maximum number of records.
Chris@0:     if ($batch_size == 0) {
Chris@0:       break;
Chris@0:     }
Chris@0:   }
Chris@0: 
Chris@0:   // Retrieve all deleted field storages. Any that have no fields can be purged.
Chris@14:   foreach ($deleted_fields_repository->getFieldStorageDefinitions() as $field_storage) {
Chris@14:     if ($field_storage_unique_id && $field_storage->getUniqueStorageIdentifier() != $field_storage_unique_id) {
Chris@0:       // If a specific UUID is provided, only purge the corresponding field.
Chris@0:       continue;
Chris@0:     }
Chris@0: 
Chris@0:     // We cannot purge anything if the entity type is unknown (e.g. the
Chris@0:     // providing module was uninstalled).
Chris@0:     // @todo Revisit after https://www.drupal.org/node/2080823.
Chris@0:     if (!isset($info[$field_storage->getTargetEntityTypeId()])) {
Chris@0:       continue;
Chris@0:     }
Chris@0: 
Chris@14:     $fields = $deleted_fields_repository->getFieldDefinitions($field_storage->getUniqueStorageIdentifier());
Chris@0:     if (empty($fields)) {
Chris@0:       field_purge_field_storage($field_storage);
Chris@0:     }
Chris@0:   }
Chris@0: }
Chris@0: 
Chris@0: /**
Chris@0:  * Purges a field record from the database.
Chris@0:  *
Chris@0:  * This function assumes all data for the field has already been purged and
Chris@0:  * should only be called by field_purge_batch().
Chris@0:  *
Chris@14:  * @param \Drupal\Core\Field\FieldDefinitionInterface $field
Chris@14:  *   The field to purge.
Chris@0:  */
Chris@14: function field_purge_field(FieldDefinitionInterface $field) {
Chris@14:   /** @var \Drupal\Core\Field\DeletedFieldsRepositoryInterface $deleted_fields_repository */
Chris@14:   $deleted_fields_repository = \Drupal::service('entity_field.deleted_fields_repository');
Chris@14:   $deleted_fields_repository->removeFieldDefinition($field);
Chris@0: 
Chris@0:   // Invoke external hooks after the cache is cleared for API consistency.
Chris@0:   \Drupal::moduleHandler()->invokeAll('field_purge_field', [$field]);
Chris@0: }
Chris@0: 
Chris@0: /**
Chris@0:  * Purges a field record from the database.
Chris@0:  *
Chris@0:  * This function assumes all fields for the field storage has already been
Chris@0:  * purged, and should only be called by field_purge_batch().
Chris@0:  *
Chris@14:  * @param \Drupal\Core\Field\FieldStorageDefinitionInterface $field_storage
Chris@0:  *   The field storage to purge.
Chris@0:  *
Chris@14:  * @throws \Drupal\Core\Field\FieldException
Chris@0:  */
Chris@14: function field_purge_field_storage(FieldStorageDefinitionInterface $field_storage) {
Chris@14:   /** @var \Drupal\Core\Field\DeletedFieldsRepositoryInterface $deleted_fields_repository */
Chris@14:   $deleted_fields_repository = \Drupal::service('entity_field.deleted_fields_repository');
Chris@14: 
Chris@14:   $fields = $deleted_fields_repository->getFieldDefinitions($field_storage->getUniqueStorageIdentifier());
Chris@0:   if (count($fields) > 0) {
Chris@0:     throw new FieldException(t('Attempt to purge a field storage @field_name that still has fields.', ['@field_name' => $field_storage->getName()]));
Chris@0:   }
Chris@0: 
Chris@14:   $deleted_fields_repository->removeFieldStorageDefinition($field_storage);
Chris@0: 
Chris@0:   // Notify the storage layer.
Chris@0:   \Drupal::entityManager()->getStorage($field_storage->getTargetEntityTypeId())->finalizePurge($field_storage);
Chris@0: 
Chris@0:   // Invoke external hooks after the cache is cleared for API consistency.
Chris@0:   \Drupal::moduleHandler()->invokeAll('field_purge_field_storage', [$field_storage]);
Chris@0: }
Chris@0: 
Chris@0: /**
Chris@0:  * @} End of "defgroup field_purge".
Chris@0:  */