field.purge.inc 7.2 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\FieldException;
9 10
use Drupal\field\Entity\FieldStorageConfig;
use Drupal\field\FieldStorageConfigInterface;
11
use Drupal\field\FieldConfigInterface;
12

13
/**
14 15
 * @defgroup field_purge Field API bulk data deletion
 * @{
16
 * Cleans up after Field API bulk deletion operations.
17 18
 *
 * Field API provides functions for deleting data attached to individual
19
 * entities as well as deleting entire fields or field storages in a single
20 21
 * operation.
 *
22
 * When a single entity is deleted, the Entity storage performs the
23
 * following operations:
24
 * - Invoking the FieldItemListInterface delete() method for each field on the
25 26 27 28 29 30
 *   entity. A file field type might use this method to delete uploaded files
 *   from the filesystem.
 * - 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.
31
 *
32
 * Similar operations are performed on deletion of a single entity revision.
33
 *
34
 * When a bundle, field or field storage is deleted, it is not practical to
35 36
 * perform those operations immediately on every affected entity in a single
 * page request; there could be thousands or millions of them. Instead, the
37 38 39 40 41
 * 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.
42 43
 *
 * Purging field data is made somewhat tricky by the fact that, while
44 45
 * $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
46
 * stored. It cannot reconstruct complete original entities to pass to the
47 48 49
 * 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.
50
 *
51 52 53
 * 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
54
 * contains the field data for whichever field is currently being purged.
55
 *
56 57
 * See @link field Field API @endlink for information about the other parts of
 * the Field API.
58 59 60
 */

/**
61
 * Purges a batch of deleted Field API data, field storages, or fields.
62
 *
63 64 65
 * 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
66 67 68
 * 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.
69 70 71
 *
 * @param $batch_size
 *   The maximum number of field data records to purge before returning.
72 73
 * @param string $field_storage_uuid
 *   (optional) Limit the purge to a specific field storage.
74
 */
75 76 77 78 79 80 81
function field_purge_batch($batch_size, $field_storage_uuid = NULL) {
  $properties = array(
    'deleted' => TRUE,
    'include_deleted' => TRUE,
  );
  if ($field_storage_uuid) {
    $properties['field_storage_uuid'] = $field_storage_uuid;
82
  }
83
  $fields = entity_load_multiple_by_properties('field_config', $properties);
84

85
  $info = \Drupal::entityManager()->getDefinitions();
86
  foreach ($fields as $field) {
87
    $entity_type = $field->getTargetEntityTypeId();
88

89 90
    // We cannot purge anything if the entity type is unknown (e.g. the
    // providing module was uninstalled).
91
    // @todo Revisit after https://www.drupal.org/node/2080823.
92 93 94 95
    if (!isset($info[$entity_type])) {
      continue;
    }

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

108
  // Retrieve all deleted field storages. Any that have no fields can be purged.
109 110 111 112
  $deleted_storages = \Drupal::state()->get('field.storage.deleted') ?: array();
  foreach ($deleted_storages as $field_storage) {
    $field_storage = new FieldStorageConfig($field_storage);
    if ($field_storage_uuid && $field_storage->uuid() != $field_storage_uuid) {
113 114 115
      // If a specific UUID is provided, only purge the corresponding field.
      continue;
    }
116 117 118

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

124 125
    $fields = entity_load_multiple_by_properties('field_config', array('field_storage_uuid' => $field_storage->uuid(), 'include_deleted' => TRUE));
    if (empty($fields)) {
126
      field_purge_field_storage($field_storage);
127 128 129 130 131
    }
  }
}

/**
132
 * Purges a field record from the database.
133
 *
134
 * This function assumes all data for the field has already been purged and
135 136
 * should only be called by field_purge_batch().
 *
137 138
 * @param $field
 *   The field record to purge.
139
 */
140
function field_purge_field(FieldConfigInterface $field) {
141
  $state = \Drupal::state();
142 143 144
  $deleted_fields = $state->get('field.field.deleted');
  unset($deleted_fields[$field->uuid()]);
  $state->set('field.field.deleted', $deleted_fields);
145

146
  // Invoke external hooks after the cache is cleared for API consistency.
147
  \Drupal::moduleHandler()->invokeAll('field_purge_field', array($field));
148 149 150
}

/**
151
 * Purges a field record from the database.
152
 *
153 154
 * This function assumes all fields for the field storage has already been
 * purged, and should only be called by field_purge_batch().
155
 *
156 157
 * @param \Drupal\field\FieldStorageConfigInterface $field_storage
 *   The field storage to purge.
158 159
 *
 * @throws Drupal\field\FieldException
160
 */
161
function field_purge_field_storage(FieldStorageConfigInterface $field_storage) {
162 163 164
  $fields = entity_load_multiple_by_properties('field_config', array('field_storage_uuid' => $field_storage->uuid(), 'include_deleted' => TRUE));
  if (count($fields) > 0) {
    throw new FieldException(t('Attempt to purge a field storage @field_name that still has fields.', array('@field_name' => $field_storage->getName())));
165 166
  }

167
  $state = \Drupal::state();
168 169 170
  $deleted_storages = $state->get('field.storage.deleted');
  unset($deleted_storages[$field_storage->uuid()]);
  $state->set('field.storage.deleted', $deleted_storages);
171

172
  // Notify the storage layer.
173
  \Drupal::entityManager()->getStorage($field_storage->getTargetEntityTypeId())->finalizePurge($field_storage);
174 175

  // Invoke external hooks after the cache is cleared for API consistency.
176
  \Drupal::moduleHandler()->invokeAll('field_purge_field_storage', array($field_storage));
177 178 179 180 181
}

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