field.purge.inc 7.45 KB
Newer Older
1 2
<?php

3 4
/**
 * @file
5
 * Provides support for field data purge after mass deletion.
6 7
 */

8
use Drupal\Core\Field\FieldDefinitionInterface;
9
use Drupal\Core\Field\FieldException;
10
use Drupal\Core\Field\FieldStorageDefinitionInterface;
11

12
/**
13 14
 * @defgroup field_purge Field API bulk data deletion
 * @{
15
 * Cleans up after Field API bulk deletion operations.
16 17
 *
 * Field API provides functions for deleting data attached to individual
18
 * entities as well as deleting entire fields or field storages in a single
19 20
 * operation.
 *
21
 * When a single entity is deleted, the Entity storage performs the
22
 * following operations:
23 24 25
 * - Invoking the method \Drupal\Core\Field\FieldItemListInterface::delete() for
 *   each field on the entity. A file field type might use this method to delete
 *   uploaded files from the filesystem.
26 27 28 29
 * - Removing the data from storage.
 * - Invoking the global hook_entity_delete() for all modules that implement it.
 *   Each hook implementation receives the entity being deleted and can operate
 *   on whichever subset of the entity's bundle's fields it chooses to.
30
 *
31
 * Similar operations are performed on deletion of a single entity revision.
32
 *
33
 * When a bundle, field or field storage is deleted, it is not practical to
34 35
 * perform those operations immediately on every affected entity in a single
 * page request; there could be thousands or millions of them. Instead, the
36 37 38 39 40
 * appropriate field data items, fields, and/or field storages are marked as
 * deleted so that subsequent load or query operations will not return them.
 * Later, a separate process cleans up, or "purges", the marked-as-deleted data
 * by going through the three-step process described above and, finally,
 * removing deleted field storage and field records.
41 42
 *
 * Purging field data is made somewhat tricky by the fact that, while
43 44
 * $entity->delete() has a complete entity to pass to the various deletion
 * steps, the Field API purge process only has the field data it has previously
45
 * stored. It cannot reconstruct complete original entities to pass to the
46 47 48
 * deletion operations. It is even possible that the original entity to which
 * some Field API data was attached has been itself deleted before the field
 * purge operation takes place.
49
 *
50 51 52
 * Field API resolves this problem by using stub entities during purge
 * operations, containing only the information from the original entity that
 * Field API knows about: entity type, ID, revision ID, and bundle. It also
53
 * contains the field data for whichever field is currently being purged.
54
 *
55 56
 * See @link field Field API @endlink for information about the other parts of
 * the Field API.
57 58 59
 */

/**
60
 * Purges a batch of deleted Field API data, field storages, or fields.
61
 *
62 63 64
 * This function will purge deleted field data in batches. The batch size
 * is defined as an argument to the function, and once each batch is finished,
 * it continues with the next batch until all have completed. If a deleted field
65 66 67
 * with no remaining data records is found, the field itself will
 * be purged. If a deleted field storage with no remaining fields is found, the
 * field storage itself will be purged.
68
 *
69
 * @param int $batch_size
70
 *   The maximum number of field data records to purge before returning.
71 72
 * @param string $field_storage_unique_id
 *   (optional) Limit the purge to a specific field storage. Defaults to NULL.
73
 */
74 75 76 77 78
function field_purge_batch($batch_size, $field_storage_unique_id = NULL) {
  /** @var \Drupal\Core\Field\DeletedFieldsRepositoryInterface $deleted_fields_repository */
  $deleted_fields_repository = \Drupal::service('entity_field.deleted_fields_repository');

  $fields = $deleted_fields_repository->getFieldDefinitions($field_storage_unique_id);
79

80
  $info = \Drupal::entityManager()->getDefinitions();
81
  foreach ($fields as $field) {
82
    $entity_type = $field->getTargetEntityTypeId();
83

84 85
    // We cannot purge anything if the entity type is unknown (e.g. the
    // providing module was uninstalled).
86
    // @todo Revisit after https://www.drupal.org/node/2080823.
87
    if (!isset($info[$entity_type])) {
88
      \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]);
89 90 91
      continue;
    }

92
    $count_purged = \Drupal::entityManager()->getStorage($entity_type)->purgeFieldData($field, $batch_size);
93
    if ($count_purged < $batch_size || $count_purged == 0) {
94 95
      // No field data remains for the field, so we can remove it.
      field_purge_field($field);
96
    }
97 98 99 100 101
    $batch_size -= $count_purged;
    // Only delete up to the maximum number of records.
    if ($batch_size == 0) {
      break;
    }
102 103
  }

104
  // Retrieve all deleted field storages. Any that have no fields can be purged.
105 106
  foreach ($deleted_fields_repository->getFieldStorageDefinitions() as $field_storage) {
    if ($field_storage_unique_id && $field_storage->getUniqueStorageIdentifier() != $field_storage_unique_id) {
107 108 109
      // If a specific UUID is provided, only purge the corresponding field.
      continue;
    }
110 111 112

    // We cannot purge anything if the entity type is unknown (e.g. the
    // providing module was uninstalled).
113
    // @todo Revisit after https://www.drupal.org/node/2080823.
114
    if (!isset($info[$field_storage->getTargetEntityTypeId()])) {
115 116 117
      continue;
    }

118
    $fields = $deleted_fields_repository->getFieldDefinitions($field_storage->getUniqueStorageIdentifier());
119
    if (empty($fields)) {
120
      field_purge_field_storage($field_storage);
121 122 123 124 125
    }
  }
}

/**
126
 * Purges a field record from the database.
127
 *
128
 * This function assumes all data for the field has already been purged and
129 130
 * should only be called by field_purge_batch().
 *
131 132
 * @param \Drupal\Core\Field\FieldDefinitionInterface $field
 *   The field to purge.
133
 */
134 135 136 137
function field_purge_field(FieldDefinitionInterface $field) {
  /** @var \Drupal\Core\Field\DeletedFieldsRepositoryInterface $deleted_fields_repository */
  $deleted_fields_repository = \Drupal::service('entity_field.deleted_fields_repository');
  $deleted_fields_repository->removeFieldDefinition($field);
138

139
  // Invoke external hooks after the cache is cleared for API consistency.
140
  \Drupal::moduleHandler()->invokeAll('field_purge_field', [$field]);
141 142 143
}

/**
144
 * Purges a field record from the database.
145
 *
146 147
 * This function assumes all fields for the field storage has already been
 * purged, and should only be called by field_purge_batch().
148
 *
149
 * @param \Drupal\Core\Field\FieldStorageDefinitionInterface $field_storage
150
 *   The field storage to purge.
151
 *
152
 * @throws \Drupal\Core\Field\FieldException
153
 */
154 155 156 157 158
function field_purge_field_storage(FieldStorageDefinitionInterface $field_storage) {
  /** @var \Drupal\Core\Field\DeletedFieldsRepositoryInterface $deleted_fields_repository */
  $deleted_fields_repository = \Drupal::service('entity_field.deleted_fields_repository');

  $fields = $deleted_fields_repository->getFieldDefinitions($field_storage->getUniqueStorageIdentifier());
159
  if (count($fields) > 0) {
160
    throw new FieldException(t('Attempt to purge a field storage @field_name that still has fields.', ['@field_name' => $field_storage->getName()]));
161 162
  }

163
  $deleted_fields_repository->removeFieldStorageDefinition($field_storage);
164

165
  // Notify the storage layer.
166
  \Drupal::entityManager()->getStorage($field_storage->getTargetEntityTypeId())->finalizePurge($field_storage);
167 168

  // Invoke external hooks after the cache is cleared for API consistency.
169
  \Drupal::moduleHandler()->invokeAll('field_purge_field_storage', [$field_storage]);
170 171 172 173 174
}

/**
 * @} End of "defgroup field_purge".
 */