field.crud.inc 39 KB
Newer Older
1 2
<?php

3 4
/**
 * @file
5
 * Field CRUD API, handling field and field instance creation and deletion.
6 7
 */

8 9
use Drupal\field\FieldException;

10 11 12
/**
 * @defgroup field_crud Field CRUD API
 * @{
13
 * Creates, updates, and deletes Field API fields, bundles, and instances.
14
 *
15 16
 * Modules use this API, often in hook_install(), to create custom data
 * structures. UI modules will use it to create a user interface.
17
 *
18
 * The Field CRUD API uses @link field Field API data structures @endlink.
19
 *
20 21
 * See @link field Field API @endlink for information about the other parts of
 * the Field API.
22 23 24
 */

/**
25
 * Creates a field.
26 27 28
 *
 * This function does not bind the field to any bundle; use
 * field_create_instance() for that.
29 30
 *
 * @param $field
31
 *   A field definition array. The field_name and type properties are required.
32 33 34 35 36 37 38 39 40
 *   Other properties, if omitted, will be given the following default values:
 *   - cardinality: 1
 *   - locked: FALSE
 *   - indexes: the field-type indexes, specified by the field type's
 *     hook_field_schema(). The indexes specified in $field are added
 *     to those default indexes. It is possible to override the
 *     definition of a field-type index by providing an index with the
 *     same name, or to remove it by redefining it as an empty array
 *     of columns. Overriding field-type indexes should be done
41
 *     carefully, for it might seriously affect the site's performance.
42 43
 *   - settings: each omitted setting is given the default value defined in
 *     hook_field_info().
44
 *   - storage:
45
 *     - type: the storage backend specified in the 'field_storage_default'
46 47 48
 *       system variable.
 *     - settings: each omitted setting is given the default value specified in
 *       hook_field_storage_info().
49
 *
50
 * @return
51
 *   The $field array with the id property filled in.
52
 *
53
 * @throws Drupal\field\FieldException
54
 *
55
 * See: @link field Field API data structures @endlink.
56 57 58 59 60 61
 */
function field_create_field($field) {
  // Field name is required.
  if (empty($field['field_name'])) {
    throw new FieldException('Attempt to create an unnamed field.');
  }
62 63 64 65
  // Field type is required.
  if (empty($field['type'])) {
    throw new FieldException('Attempt to create a field with no type.');
  }
66
  // Field name cannot contain invalid characters.
67 68
  if (!preg_match('/^[_a-z]+[_a-z0-9]*$/', $field['field_name'])) {
    throw new FieldException('Attempt to create a field with invalid characters. Only lowercase alphanumeric characters and underscores are allowed, and only lowercase letters and underscore are allowed as the first character');
69 70
  }

71 72 73 74 75 76 77
  // Field name cannot be longer than 32 characters. We use drupal_strlen()
  // because the DB layer assumes that column widths are given in characters,
  // not bytes.
  if (drupal_strlen($field['field_name']) > 32) {
    throw new FieldException(t('Attempt to create a field with a name longer than 32 characters: %name',
      array('%name' => $field['field_name'])));
  }
78

79 80 81
  // Ensure the field name is unique over active and disabled fields.
  // We do not care about deleted fields.
  $prior_field = field_read_field($field['field_name'], array('include_inactive' => TRUE));
82
  if (!empty($prior_field)) {
83 84 85 86
    $message = $prior_field['active']?
      t('Attempt to create field name %name which already exists and is active.', array('%name' => $field['field_name'])):
      t('Attempt to create field name %name which already exists, although it is inactive.', array('%name' => $field['field_name']));
    throw new FieldException($message);
87 88
  }

89
  // Disallow reserved field names. This can't prevent all field name
90
  // collisions with existing entity properties, but some is better
91
  // than none.
92
  foreach (entity_get_info() as $type => $info) {
93
    if (in_array($field['field_name'], $info['entity_keys'])) {
94 95 96 97
      throw new FieldException(t('Attempt to create field name %name which is reserved by entity type %type.', array('%name' => $field['field_name'], '%type' => $type)));
    }
  }

98
  $field += array(
99
    'entity_types' => array(),
100
    'cardinality' => 1,
101
    'translatable' => FALSE,
102 103
    'locked' => FALSE,
    'settings' => array(),
104 105
    'storage' => array(),
    'deleted' => 0,
106
  );
107

108 109 110 111 112
  // Check that the field type is known.
  $field_type = field_info_field_types($field['type']);
  if (!$field_type) {
    throw new FieldException(t('Attempt to create a field of unknown type %type.', array('%type' => $field['type'])));
  }
113 114 115
  // Create all per-field-type properties (needed here as long as we have
  // settings that impact column definitions).
  $field['settings'] += field_info_field_settings($field['type']);
116
  $field['module'] = $field_type['module'];
117
  $field['active'] = 1;
118

119 120 121 122 123 124 125 126 127 128 129 130 131 132
  // Provide default storage.
  $field['storage'] += array(
    'type' => variable_get('field_storage_default', 'field_sql_storage'),
    'settings' => array(),
  );
  // Check that the storage type is known.
  $storage_type = field_info_storage_types($field['storage']['type']);
  if (!$storage_type) {
    throw new FieldException(t('Attempt to create a field with unknown storage type %type.', array('%type' => $field['storage']['type'])));
  }
  // Provide default storage settings.
  $field['storage']['settings'] += field_info_storage_settings($field['storage']['type']);
  $field['storage']['module'] = $storage_type['module'];
  $field['storage']['active'] = 1;
133
  // Collect storage information.
134
  module_load_install($field['module']);
135
  $schema = (array) module_invoke($field['module'], 'field_schema', $field);
136
  $schema += array('columns' => array(), 'indexes' => array(), 'foreign keys' => array());
137 138
  // 'columns' are hardcoded in the field type.
  $field['columns'] = $schema['columns'];
139 140 141
  if (array_intersect(array_keys($field['columns']), field_reserved_columns())) {
    throw new FieldException(t('Illegal field type columns.'));
  }
142 143
  // 'foreign keys' are hardcoded in the field type.
  $field['foreign keys'] = $schema['foreign keys'];
144 145 146 147 148 149 150 151 152 153 154
  // 'indexes' can be both hardcoded in the field type, and specified in the
  // incoming $field definition.
  $field += array(
    'indexes' => array(),
  );
  $field['indexes'] += $schema['indexes'];

  // The serialized 'data' column contains everything from $field that does not
  // have its own column and is not automatically populated when the field is
  // read.
  $data = $field;
155
  unset($data['columns'], $data['field_name'], $data['type'], $data['active'], $data['module'], $data['storage_type'], $data['storage_active'], $data['storage_module'], $data['locked'], $data['cardinality'], $data['deleted']);
156 157 158
  // Additionally, do not save the 'bundles' property populated by
  // field_info_field().
  unset($data['bundles']);
159

160 161 162 163 164 165 166 167 168 169 170
  $record = array(
    'field_name' => $field['field_name'],
    'type' => $field['type'],
    'module' => $field['module'],
    'active' => $field['active'],
    'storage_type' => $field['storage']['type'],
    'storage_module' => $field['storage']['module'],
    'storage_active' => $field['storage']['active'],
    'locked' => $field['locked'],
    'data' => $data,
    'cardinality' => $field['cardinality'],
171
    'translatable' => $field['translatable'],
172 173
    'deleted' => $field['deleted'],
  );
174

175 176 177
  // Store the field and get the id back.
  drupal_write_record('field_config', $record);
  $field['id'] = $record['id'];
178

179 180
  // Invoke hook_field_storage_create_field after the field is
  // complete (e.g. it has its id).
181
  try {
182 183 184
    // Invoke hook_field_storage_create_field after
    // drupal_write_record() sets the field id.
    module_invoke($storage_type['module'], 'field_storage_create_field', $field);
185 186 187 188 189 190 191 192 193
  }
  catch (Exception $e) {
    // If storage creation failed, remove the field_config record before
    // rethrowing the exception.
    db_delete('field_config')
      ->condition('id', $field['id'])
      ->execute();
    throw $e;
  }
194

195 196
  // Clear caches
  field_cache_clear(TRUE);
197

198 199
  // Invoke external hooks after the cache is cleared for API consistency.
  module_invoke_all('field_create_field', $field);
200

201
  return $field;
202 203
}

204 205
/**
 * Updates a field.
206 207 208 209 210 211 212 213 214 215 216 217 218 219
 *
 * Any module may forbid any update for any reason. For example, the
 * field's storage module might forbid an update if it would change
 * the storage schema while data for the field exists. A field type
 * module might forbid an update if it would change existing data's
 * semantics, or if there are external dependencies on field settings
 * that cannot be updated.
 *
 * @param $field
 *   A field structure. $field['field_name'] must provided; it
 *   identifies the field that will be updated to match this
 *   structure. Any other properties of the field that are not
 *   specified in $field will be left unchanged, so it is not
 *   necessary to pass in a fully populated $field structure.
220 221 222
 *
 * @throws Drupal\field\FieldException
 *
223 224 225 226 227 228 229 230 231
 * @see field_create_field()
 */
function field_update_field($field) {
  // Check that the specified field exists.
  $prior_field = field_read_field($field['field_name']);
  if (empty($prior_field)) {
    throw new FieldException('Attempt to update a non-existent field.');
  }

232
  // Use the prior field values for anything not specifically set by the new
233 234 235 236
  // field to be sure that all values are set.
  $field += $prior_field;
  $field['settings'] += $prior_field['settings'];

237
  // Some updates are always disallowed.
238 239 240
  if ($field['type'] != $prior_field['type']) {
    throw new FieldException("Cannot change an existing field's type.");
  }
241 242
  if ($field['entity_types'] != $prior_field['entity_types']) {
    throw new FieldException("Cannot change an existing field's entity_types property.");
243
  }
244 245 246
  if ($field['storage']['type'] != $prior_field['storage']['type']) {
    throw new FieldException("Cannot change an existing field's storage type.");
  }
247 248 249

  // Collect the new storage information, since what is in
  // $prior_field may no longer be right.
250
  module_load_install($field['module']);
251 252 253 254 255 256 257 258 259 260 261
  $schema = (array) module_invoke($field['module'], 'field_schema', $field);
  $schema += array('columns' => array(), 'indexes' => array());
  // 'columns' are hardcoded in the field type.
  $field['columns'] = $schema['columns'];
  // 'indexes' can be both hardcoded in the field type, and specified in the
  // incoming $field definition.
  $field += array(
    'indexes' => array(),
  );
  $field['indexes'] += $schema['indexes'];

262
  $has_data = field_has_data($field);
263 264 265 266 267 268 269 270 271

  // See if any module forbids the update by throwing an exception.
  foreach (module_implements('field_update_forbid') as $module) {
    $function = $module . '_field_update_forbid';
    $function($field, $prior_field, $has_data);
  }

  // Tell the storage engine to update the field. Do this before
  // saving the new definition since it still might fail.
272 273
  $storage_type = field_info_storage_types($field['storage']['type']);
  module_invoke($storage_type['module'], 'field_storage_update_field', $field, $prior_field, $has_data);
274 275 276 277 278 279 280 281 282

  // Save the new field definition. @todo: refactor with
  // field_create_field.

  // The serialized 'data' column contains everything from $field that does not
  // have its own column and is not automatically populated when the field is
  // read.
  $data = $field;
  unset($data['columns'], $data['field_name'], $data['type'], $data['locked'], $data['module'], $data['cardinality'], $data['active'], $data['deleted']);
283 284 285 286
  // Additionally, do not save the 'bundles' property populated by
  // field_info_field().
  unset($data['bundles']);

287 288 289 290 291 292 293 294
  $field['data'] = $data;

  // Store the field and create the id.
  $primary_key = array('id');
  drupal_write_record('field_config', $field, $primary_key);

  // Clear caches
  field_cache_clear(TRUE);
295

296
  // Invoke external hooks after the cache is cleared for API consistency.
297
  module_invoke_all('field_update_field', $field, $prior_field, $has_data);
298 299
}

300
/**
301 302 303
 * Reads a single field record directly from the database.
 *
 * Generally, you should use the field_info_field() instead.
304
 *
305 306
 * This function will not return deleted fields. Use field_read_fields() instead
 * for this purpose.
307
 *
308 309 310
 * @param $field_name
 *   The field name to read.
 * @param array $include_additional
311 312 313 314
 *   The default behavior of this function is to not return a field that is
 *   inactive. Setting $include_additional['include_inactive'] to TRUE will
 *   override this behavior.
 *
315
 * @return
316
 *   A field definition array, or FALSE.
317 318 319 320 321 322 323
 */
function field_read_field($field_name, $include_additional = array()) {
  $fields = field_read_fields(array('field_name' => $field_name), $include_additional);
  return $fields ? current($fields) : FALSE;
}

/**
324
 * Reads in fields that match an array of conditions.
325 326
 *
 * @param array $params
327 328 329 330 331
 *   An array of conditions to match against. Keys are columns from the
 *   'field_config' table, values are conditions to match. Additionally,
 *   conditions on the 'entity_type' and 'bundle' columns from the
 *   'field_config_instance' table are supported (select fields having an
 *   instance on a given bundle).
332
 * @param array $include_additional
333 334
 *   The default behavior of this function is to not return fields that are
 *   inactive or have been deleted. Setting
335
 *   $include_additional['include_inactive'] or
336 337
 *   $include_additional['include_deleted'] to TRUE will override this behavior.
 *
338
 * @return
339
 *   An array of fields matching $params. If
340 341
 *   $include_additional['include_deleted'] is TRUE, the array is keyed by
 *   field ID, otherwise it is keyed by field name.
342 343 344 345 346 347 348
 */
function field_read_fields($params = array(), $include_additional = array()) {
  $query = db_select('field_config', 'fc', array('fetch' => PDO::FETCH_ASSOC));
  $query->fields('fc');

  // Turn the conditions into a query.
  foreach ($params as $key => $value) {
349 350 351 352 353 354 355 356
    // Allow filtering on the 'entity_type' and 'bundle' columns of the
    // field_config_instance table.
    if ($key == 'entity_type' || $key == 'bundle') {
      if (empty($fci_join)) {
        $fci_join = $query->join('field_config_instance', 'fci', 'fc.id = fci.field_id');
      }
      $key = 'fci.' . $key;
    }
357 358 359
    else {
      $key = 'fc.' . $key;
    }
360

361 362
    $query->condition($key, $value);
  }
363

364
  if (!isset($include_additional['include_inactive']) || !$include_additional['include_inactive']) {
365 366 367
    $query
      ->condition('fc.active', 1)
      ->condition('fc.storage_active', 1);
368
  }
369 370
  $include_deleted = (isset($include_additional['include_deleted']) && $include_additional['include_deleted']);
  if (!$include_deleted) {
371 372 373 374 375
    $query->condition('fc.deleted', 0);
  }

  $fields = array();
  $results = $query->execute();
376 377 378 379 380 381 382 383 384 385 386 387 388 389
  foreach ($results as $record) {
    $field = unserialize($record['data']);
    $field['id'] = $record['id'];
    $field['field_name'] = $record['field_name'];
    $field['type'] = $record['type'];
    $field['module'] = $record['module'];
    $field['active'] = $record['active'];
    $field['storage']['type'] = $record['storage_type'];
    $field['storage']['module'] = $record['storage_module'];
    $field['storage']['active'] = $record['storage_active'];
    $field['locked'] = $record['locked'];
    $field['cardinality'] = $record['cardinality'];
    $field['translatable'] = $record['translatable'];
    $field['deleted'] = $record['deleted'];
390 391 392

    module_invoke_all('field_read_field', $field);

393
    // Populate storage information.
394
    module_load_install($field['module']);
395 396 397
    $schema = (array) module_invoke($field['module'], 'field_schema', $field);
    $schema += array('columns' => array(), 'indexes' => array());
    $field['columns'] = $schema['columns'];
398

399 400 401 402 403
    $field_name = $field['field_name'];
    if ($include_deleted) {
      $field_name = $field['id'];
    }
    $fields[$field_name] = $field;
404 405 406 407 408
  }
  return $fields;
}

/**
409
 * Marks a field and its instances and data for deletion.
410 411 412 413 414
 *
 * @param $field_name
 *   The field name to delete.
 */
function field_delete_field($field_name) {
415 416 417
  // Delete all non-deleted instances.
  $field = field_info_field($field_name);
  if (isset($field['bundles'])) {
418
    foreach ($field['bundles'] as $entity_type => $bundles) {
419
      foreach ($bundles as $bundle) {
420
        $instance = field_info_instance($entity_type, $field_name, $bundle);
421
        field_delete_instance($instance, FALSE);
422
      }
423 424 425
    }
  }

426 427
  // Mark field data for deletion.
  module_invoke($field['storage']['module'], 'field_storage_delete_field', $field);
428 429 430

  // Mark the field for deletion.
  db_update('field_config')
431 432 433
    ->fields(array('deleted' => 1))
    ->condition('field_name', $field_name)
    ->execute();
434

435 436
  // Clear the cache.
  field_cache_clear(TRUE);
437 438

  module_invoke_all('field_delete_field', $field);
439 440 441 442 443 444
}

/**
 * Creates an instance of a field, binding it to a bundle.
 *
 * @param $instance
445
 *   A field instance definition array. The field_name, entity_type and
446 447
 *   bundle properties are required. Other properties, if omitted,
 *   will be given the following default values:
448 449 450 451 452 453 454 455 456 457 458
 *   - label: the field name
 *   - description: empty string
 *   - required: FALSE
 *   - default_value_function: empty string
 *   - settings: each omitted setting is given the default value specified in
 *     hook_field_info().
 *   - widget:
 *     - type: the default widget specified in hook_field_info().
 *     - settings: each omitted setting is given the default value specified in
 *       hook_field_widget_info().
 *   - display:
459 460 461
 *     Settings for the 'default' view mode will be added if not present, and
 *     each view mode in the definition will be completed with the following
 *     default values:
462 463 464 465
 *     - label: 'above'
 *     - type: the default formatter specified in hook_field_info().
 *     - settings: each omitted setting is given the default value specified in
 *       hook_field_formatter_info().
466 467 468
 *     View modes not present in the definition are left empty, and the field
 *     will not be displayed in this mode.
 *
469
 * @return
470
 *   The $instance array with the id property filled in.
471
 *
472
 * @throws Drupal\field\FieldException
473
 *
474
 * See: @link field Field API data structures @endlink.
475
 */
476
function field_create_instance(&$instance) {
477 478
  $field = field_read_field($instance['field_name']);
  if (empty($field)) {
479
    throw new FieldException(t("Attempt to create an instance of a field @field_name that doesn't exist or is currently inactive.", array('@field_name' => $instance['field_name'])));
480
  }
481
  // Check that the required properties exists.
482
  if (empty($instance['entity_type'])) {
483
    throw new FieldException(t('Attempt to create an instance of field @field_name without an entity type.', array('@field_name' => $instance['field_name'])));
484 485 486 487
  }
  if (empty($instance['bundle'])) {
    throw new FieldException(t('Attempt to create an instance of field @field_name without a bundle.', array('@field_name' => $instance['field_name'])));
  }
488
  // Check that the field can be attached to this entity type.
489
  if (!empty($field['entity_types']) && !in_array($instance['entity_type'], $field['entity_types'])) {
490
    throw new FieldException(t('Attempt to create an instance of field @field_name on forbidden entity type @entity_type.', array('@field_name' => $instance['field_name'], '@entity_type' => $instance['entity_type'])));
491
  }
492

493 494 495
  // Set the field id.
  $instance['field_id'] = $field['id'];

496 497 498
  // Note that we do *not* prevent creating a field on non-existing bundles,
  // because that would break the 'Body as field' upgrade for contrib
  // node types.
499 500 501

  // TODO: Check that the widget type is known and can handle the field type ?
  // TODO: Check that the formatters are known and can handle the field type ?
502
  // TODO: Check that the display view modes are known for the entity type ?
503 504 505
  // Those checks should probably happen in _field_write_instance() ?
  // Problem : this would mean that a UI module cannot update an instance with a disabled formatter.

506 507 508
  // Ensure the field instance is unique within the bundle.
  // We only check for instances of active fields, since adding an instance of
  // a disabled field is not supported.
509
  $prior_instance = field_read_instance($instance['entity_type'], $instance['field_name'], $instance['bundle']);
510
  if (!empty($prior_instance)) {
511
    $message = t('Attempt to create an instance of field @field_name on bundle @bundle that already has an instance of that field.', array('@field_name' => $instance['field_name'], '@bundle' => $instance['bundle']));
512
    throw new FieldException($message);
513 514 515 516 517 518
  }

  _field_write_instance($instance);

  // Clear caches
  field_cache_clear();
519 520 521 522

  // Invoke external hooks after the cache is cleared for API consistency.
  module_invoke_all('field_create_instance', $instance);

523
  return $instance;
524 525
}

526 527
/**
 * Updates an instance of a field.
528 529
 *
 * @param $instance
530 531
 *   An associative array representing an instance structure. The required keys
 *   and values are:
532 533 534
 *   - entity_type: The type of the entity the field is attached to.
 *   - bundle: The bundle this field belongs to.
 *   - field_name: The name of an existing field.
535
 *   Read-only ID properties are assigned automatically. Any other properties
536 537
 *   properties specified in $instance overwrite the existing values for
 *   the instance.
538
 *
539
 * @throws Drupal\field\FieldException
540
 *
541 542 543 544 545 546
 * @see field_create_instance()
 */
function field_update_instance($instance) {
  // Check that the specified field exists.
  $field = field_read_field($instance['field_name']);
  if (empty($field)) {
547
    throw new FieldException(t('Attempt to update an instance of a nonexistent field @field.', array('@field' => $instance['field_name'])));
548 549 550 551
  }

  // Check that the field instance exists (even if it is inactive, since we
  // want to be able to replace inactive widgets with new ones).
552
  $prior_instance = field_read_instance($instance['entity_type'], $instance['field_name'], $instance['bundle'], array('include_inactive' => TRUE));
553
  if (empty($prior_instance)) {
554
    throw new FieldException(t("Attempt to update an instance of field @field on bundle @bundle that doesn't exist.", array('@field' => $instance['field_name'], '@bundle' => $instance['bundle'])));
555 556
  }

557 558 559
  $instance['id'] = $prior_instance['id'];
  $instance['field_id'] = $prior_instance['field_id'];

560 561 562 563
  _field_write_instance($instance, TRUE);

  // Clear caches.
  field_cache_clear();
564 565

  module_invoke_all('field_update_instance', $instance, $prior_instance);
566 567 568
}

/**
569
 * Stores an instance record in the field configuration database.
570 571 572 573 574 575
 *
 * @param $instance
 *   An instance structure.
 * @param $update
 *   Whether this is a new or existing instance.
 */
576
function _field_write_instance(&$instance, $update = FALSE) {
577 578 579
  $field = field_read_field($instance['field_name']);
  $field_type = field_info_field_types($field['type']);

580 581 582 583 584 585 586 587
  // Temporary workaround to allow incoming $instance as arrays or classed
  // objects.
  // @todo remove once the external APIs have been converted to use
  // FieldInstance objects.
  if (is_object($instance) && get_class($instance) == 'Drupal\field\FieldInstance') {
    $instance = $instance->getArray();
  }

588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607
  // Set defaults.
  $instance += array(
    'settings' => array(),
    'display' => array(),
    'widget' => array(),
    'required' => FALSE,
    'label' => $instance['field_name'],
    'description' => '',
    'deleted' => 0,
  );

  // Set default instance settings.
  $instance['settings'] += field_info_instance_settings($field['type']);

  // Set default widget and settings.
  $instance['widget'] += array(
    // TODO: what if no 'default_widget' specified ?
    'type' => $field_type['default_widget'],
    'settings' => array(),
  );
608 609
  // If no weight specified, make sure the field sinks at the bottom.
  if (!isset($instance['widget']['weight'])) {
610
    $max_weight = field_info_max_weight($instance['entity_type'], $instance['bundle'], 'form');
611
    $instance['widget']['weight'] = isset($max_weight) ? $max_weight + 1 : 0;
612
  }
613 614
  // Check widget module.
  $widget_type = field_info_widget_types($instance['widget']['type']);
615
  $instance['widget']['module'] = $widget_type['module'];
616 617
  $instance['widget']['settings'] += field_info_widget_settings($instance['widget']['type']);

618 619
  // Make sure there are at least display settings for the 'default' view mode,
  // and fill in defaults for each view mode specified in the definition.
620
  $instance['display'] += array(
621
    'default' => array(),
622
  );
623
  foreach ($instance['display'] as $view_mode => $display) {
624
    $display += array(
625
      'label' => 'above',
626
      'type' => isset($field_type['default_formatter']) ? $field_type['default_formatter'] : 'hidden',
627 628
      'settings' => array(),
    );
629 630 631 632 633 634 635
    if ($display['type'] != 'hidden') {
      $formatter_type = field_info_formatter_types($display['type']);
      $display['module'] = $formatter_type['module'];
      $display['settings'] += field_info_formatter_settings($display['type']);
    }
    // If no weight specified, make sure the field sinks at the bottom.
    if (!isset($display['weight'])) {
636
      $max_weight = field_info_max_weight($instance['entity_type'], $instance['bundle'], $view_mode);
637
      $display['weight'] = isset($max_weight) ? $max_weight + 1 : 0;
638 639
    }
    $instance['display'][$view_mode] = $display;
640 641
  }

642 643 644
  // The serialized 'data' column contains everything from $instance that does
  // not have its own column and is not automatically populated when the
  // instance is read.
645
  $data = $instance;
646
  unset($data['id'], $data['field_id'], $data['field_name'], $data['entity_type'], $data['bundle'], $data['deleted']);
647 648

  $record = array(
649
    'field_id' => $instance['field_id'],
650
    'field_name' => $instance['field_name'],
651
    'entity_type' => $instance['entity_type'],
652 653 654 655 656 657
    'bundle' => $instance['bundle'],
    'data' => $data,
    'deleted' => $instance['deleted'],
  );
  // We need to tell drupal_update_record() the primary keys to trigger an
  // update.
658 659
  if ($update) {
    $record['id'] = $instance['id'];
660
    drupal_write_record('field_config_instance', $record, array('id'));
661 662
  }
  else {
663 664
    drupal_write_record('field_config_instance', $record);
    $instance['id'] = $record['id'];
665
  }
666 667 668
}

/**
669
 * Reads a single instance record from the database.
670
 *
671 672 673
 * Generally, you should use field_info_instance() instead, as it provides
 * caching and allows other modules the opportunity to append additional
 * formatters, widgets, and other information.
674
 *
675
 * @param $entity_type
676
 *   The type of entity to which the field is bound.
677 678 679 680 681
 * @param $field_name
 *   The field name to read.
 * @param $bundle
 *   The bundle to which the field is bound.
 * @param array $include_additional
682 683
 *   The default behavior of this function is to not return an instance that has
 *   been deleted, or whose field is inactive. Setting
684
 *   $include_additional['include_inactive'] or
685 686
 *   $include_additional['include_deleted'] to TRUE will override this behavior.
 *
687 688 689
 * @return
 *   An instance structure, or FALSE.
 */
690
function field_read_instance($entity_type, $field_name, $bundle, $include_additional = array()) {
691
  $instances = field_read_instances(array('entity_type' => $entity_type, 'field_name' => $field_name, 'bundle' => $bundle), $include_additional);
692 693 694 695
  return $instances ? current($instances) : FALSE;
}

/**
696
 * Reads in field instances that match an array of conditions.
697 698
 *
 * @param $param
699 700 701
 *   An array of properties to use in selecting a field instance. Valid keys
 *   include any column of the field_config_instance table. If NULL, all
 *   instances will be returned.
702
 * @param $include_additional
703 704 705 706 707
 *   The default behavior of this function is to not return field instances that
 *   have been marked deleted, or whose field is inactive. Setting
 *   $include_additional['include_inactive'] or
 *   $include_additional['include_deleted'] to TRUE will override this behavior.
 *
708 709 710 711
 * @return
 *   An array of instances matching the arguments.
 */
function field_read_instances($params = array(), $include_additional = array()) {
712 713 714
  $include_inactive = isset($include_additional['include_inactive']) && $include_additional['include_inactive'];
  $include_deleted = isset($include_additional['include_deleted']) && $include_additional['include_deleted'];

715
  $query = db_select('field_config_instance', 'fci', array('fetch' => PDO::FETCH_ASSOC));
716
  $query->join('field_config', 'fc', 'fc.id = fci.field_id');
717 718 719 720 721 722
  $query->fields('fci');

  // Turn the conditions into a query.
  foreach ($params as $key => $value) {
    $query->condition('fci.' . $key, $value);
  }
723
  if (!$include_inactive) {
724 725
    $query
      ->condition('fc.active', 1)
726
      ->condition('fc.storage_active', 1);
727
  }
728
  if (!$include_deleted) {
729 730 731 732 733 734 735 736
    $query->condition('fc.deleted', 0);
    $query->condition('fci.deleted', 0);
  }

  $instances = array();
  $results = $query->execute();

  foreach ($results as $record) {
737
    // Filter out instances on unknown entity types (for instance because the
738
    // module exposing them was disabled).
739
    $entity_info = entity_get_info($record['entity_type']);
740 741 742 743 744
    if ($include_inactive || $entity_info) {
      $instance = unserialize($record['data']);
      $instance['id'] = $record['id'];
      $instance['field_id'] = $record['field_id'];
      $instance['field_name'] = $record['field_name'];
745
      $instance['entity_type'] = $record['entity_type'];
746 747 748 749 750 751
      $instance['bundle'] = $record['bundle'];
      $instance['deleted'] = $record['deleted'];

      module_invoke_all('field_read_instance', $instance);
      $instances[] = $instance;
    }
752 753 754 755 756
  }
  return $instances;
}

/**
757
 * Marks a field instance and its data for deletion.
758
 *
759 760
 * @param $instance
 *   An instance structure.
761 762
 * @param $field_cleanup
 *   If TRUE, the field will be deleted as well if its last instance is being
763
 *   deleted. If FALSE, it is the caller's responsibility to handle the case of
764
 *   fields left without instances. Defaults to TRUE.
765
 */
766
function field_delete_instance($instance, $field_cleanup = TRUE) {
767 768 769
  // Mark the field instance for deletion.
  db_update('field_config_instance')
    ->fields(array('deleted' => 1))
770
    ->condition('field_name', $instance['field_name'])
771
    ->condition('entity_type', $instance['entity_type'])
772
    ->condition('bundle', $instance['bundle'])
773 774
    ->execute();

775 776 777
  // Clear the cache.
  field_cache_clear();

778
  // Mark instance data for deletion.
779
  $field = field_info_field($instance['field_name']);
780 781
  module_invoke($field['storage']['module'], 'field_storage_delete_instance', $instance);

782
  // Let modules react to the deletion of the instance.
783
  module_invoke_all('field_delete_instance', $instance);
784 785 786 787 788

  // Delete the field itself if we just deleted its last instance.
  if ($field_cleanup && count($field['bundles']) == 0) {
    field_delete_field($field['field_name']);
  }
789 790 791 792
}

/**
 * @} End of "defgroup field_crud".
793
 */
794

795
/**
796 797
 * @defgroup field_purge Field API bulk data deletion
 * @{
798
 * Cleans up after Field API bulk deletion operations.
799 800
 *
 * Field API provides functions for deleting data attached to individual
801
 * entities as well as deleting entire fields or field instances in a single
802 803
 * operation.
 *
804
 * Deleting field data items for an entity with field_attach_delete() involves
805 806
 * three separate operations:
 * - Invoking the Field Type API hook_field_delete() for each field on the
807 808 809 810 811 812
 *   entity. The hook for each field type receives the entity and the specific
 *   field being deleted. A file field module might use this hook to delete
 *   uploaded files from the filesystem.
 * - Invoking the Field Storage API hook_field_storage_delete() to remove data
 *   from the primary field storage. The hook implementation receives the entity
 *   being deleted and deletes data for all of the entity's bundle's fields.
813
 * - Invoking the global Field Attach API hook_field_attach_delete() for all
814 815 816
 *   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.
817
 *
818 819
 * These hooks are invoked immediately when field_attach_delete() is called.
 * Similar operations are performed for field_attach_delete_revision().
820 821
 *
 * When a field, bundle, or field instance is deleted, it is not practical to
822
 * invoke these hooks immediately on every affected entity in a single page
823 824 825 826
 * request; there could be thousands or millions of them. Instead, the
 * appropriate field data items, instances, and/or fields 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
827 828
 * through the three-step process described above and, finally, removing deleted
 * field and instance records.
829 830
 *
 * Purging field data is made somewhat tricky by the fact that, while
831
 * field_attach_delete() has a complete entity to pass to the various deletion
832
 * hooks, the Field API purge process only has the field data it has previously
833 834
 * stored. It cannot reconstruct complete original entities to pass to the
 * deletion hooks. It is even possible that the original entity to which some
835 836 837
 * Field API data was attached has been itself deleted before the field purge
 * operation takes place.
 *
838 839
 * Field API resolves this problem by using "pseudo-entities" during purge
 * operations. A pseudo-entity contains only the information from the original
840 841 842 843 844 845
 * entity that Field API knows about: entity type, ID, revision ID, and bundle.
 * It also contains the field data for whichever field instance is currently
 * being purged. For example, suppose that the node type 'story' used to contain
 * a field called 'subtitle' but the field was deleted. If node 37 was a story
 * with a subtitle, the pseudo-entity passed to the purge hooks would look
 * something like this:
846 847
 *
 * @code
848
 *   $entity = stdClass Object(
849 850 851 852 853 854 855 856 857 858
 *     [nid] => 37,
 *     [vid] => 37,
 *     [type] => 'story',
 *     [subtitle] => array(
 *       [0] => array(
 *         'value' => 'subtitle text',
 *       ),
 *     ),
 *   );
 * @endcode
859
 *
860 861
 * See @link field Field API @endlink for information about the other parts of
 * the Field API.
862 863 864
 */

/**
865
 * Purges a batch of deleted Field API data, instances, or fields.
866
 *
867 868 869 870 871 872
 * 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
 * instance with no remaining data records is found, the instance itself will
 * be purged. If a deleted field with no remaining field instances is found, the
 * field itself will be purged.
873 874 875 876 877 878 879 880
 *
 * @param $batch_size
 *   The maximum number of field data records to purge before returning.
 */
function field_purge_batch($batch_size) {
  // Retrieve all deleted field instances. We cannot use field_info_instances()
  // because that function does not return deleted instances.
  $instances = field_read_instances(array('deleted' => 1), array('include_deleted' => 1));
881 882
  $factory = drupal_container()->get('entity.query');
  $info = entity_get_info();
883
  foreach ($instances as $instance) {
884 885 886 887 888
    $entity_type = $instance['entity_type'];
    $ids = (object) array(
      'entity_type' => $entity_type,
      'bundle' => $instance['bundle'],
    );
889
    // field_purge_data() will need the field array.
890
    $field = field_info_field_by_id($instance['field_id']);
891
    // Retrieve some entities.
892 893
    $results = $factory->get($entity_type)
      ->condition('id:' . $field['id'] . '.deleted', 1)
894
      ->condition($info[$entity_type]['entity_keys']['bundle'], $ids->bundle)
895 896
      ->range(0, $batch_size)
      ->execute();
897

898
    if ($results) {
899 900 901 902 903 904 905 906 907 908 909 910 911
      $entities = array();
      foreach ($results as $revision_id => $entity_id) {
        // This might not be the revision id if the entity type does not support
        // revisions but _field_create_entity_from_ids() checks that and
        // disregards this value so there is no harm setting it.
        $ids->revision_id = $revision_id;
        $ids->entity_id = $entity_id;
        $entities[$entity_id] = _field_create_entity_from_ids($ids);
      }
      field_attach_load($entity_type, $entities, FIELD_LOAD_CURRENT, array('field_id' => $field['id'], 'deleted' => 1));
      foreach ($entities as $entity) {
        // Purge the data for the entity.
        field_purge_data($entity_type, $entity, $field, $instance);
912 913 914 915 916 917 918 919
      }
    }
    else {
      // No field data remains for the instance, so we can remove it.
      field_purge_instance($instance);
    }
  }

920
  // Retrieve all deleted fields. Any that have no instances can be purged.
921 922
  $fields = field_read_fields(array('deleted' => 1), array('include_deleted' => 1));
  foreach ($fields as $field) {
923 924
    $instances = field_read_instances(array('field_id' => $field['id']), array('include_deleted' => 1));
    if (empty($instances)) {
925 926 927 928 929 930
      field_purge_field($field);
    }
  }
}

/**
931
 * Purges the field data for a single field on a single pseudo-entity.
932
 *
933 934
 * This is basically the same as field_attach_delete() except it only applies to
 * a single field. The entity itself is not being deleted, and it is quite
935 936
 * possible that other field data will remain attached to it.
 *
937 938 939
 * @param $entity_type
 *   The type of $entity; e.g. 'node' or 'user'.
 * @param $entity
940
 *   The pseudo-entity whose field data is being purged.
941 942 943 944 945
 * @param $field
 *   The (possibly deleted) field whose data is being purged.
 * @param $instance
 *   The deleted field instance whose data is being purged.
 */
946
function field_purge_data($entity_type, $entity, $field, $instance) {
947 948 949
  // Each field type's hook_field_delete() only expects to operate on a single
  // field at a time, so we can use it as-is for purging.
  $options = array('field_id' => $instance['field_id'], 'deleted' => TRUE);
950
  _field_invoke('delete', $entity_type, $entity, $dummy, $dummy, $options);
951 952

  // Tell the field storage system to purge the data.
953
  module_invoke($field['storage']['module'], 'field_storage_purge', $entity_type, $entity, $field, $instance);
954 955 956 957

  // Let other modules act on purging the data.
  foreach (module_implements('field_attach_purge') as $module) {
    $function = $module . '_field_attach_purge';
958
    $function($entity_type, $entity, $field, $instance);
959 960 961 962
  }
}

/**
963
 * Purges a field instance record from the database.
964
 *
965
 * This function assumes all data for the instance has already been purged and
966 967 968 969 970 971 972 973 974 975 976
 * should only be called by field_purge_batch().
 *
 * @param $instance
 *   The instance record to purge.
 */
function field_purge_instance($instance) {
  db_delete('field_config_instance')
    ->condition('id', $instance['id'])
    ->execute();

  // Notify the storage engine.
977 978
  $field = field_info_field_by_id($instance['field_id']);
  module_invoke($field['storage']['module'], 'field_storage_purge_instance', $instance);
979 980

  // Clear the cache.
981
  field_info_cache_clear();
982 983 984 985 986 987

  // Invoke external hooks after the cache is cleared for API consistency.
  module_invoke_all('field_purge_instance', $instance);
}

/**
988
 * Purges a field record from the database.
989 990 991 992 993 994 995 996 997 998
 *
 * This function assumes all instances for the field has already been purged,
 * and should only be called by field_purge_batch().
 *
 * @param $field
 *   The field record to purge.
 */
function field_purge_field($field) {
  $instances = field_read_instances(array('field_id' => $field['id']), array('include_deleted' => 1));
  if (count($instances) > 0) {
999
    throw new FieldException(t('Attempt to purge a field @field_name that still has instances.', array('@field_name' => $field['field_name'])));
1000 1001 1002 1003 1004 1005 1006
  }

  db_delete('field_config')
    ->condition('id', $field['id'])
    ->execute();

  // Notify the storage engine.
1007
  module_invoke($field['storage']['module'], 'field_storage_purge_field', $field);
1008 1009

  // Clear the cache.
1010
  field_info_cache_clear();
1011 1012 1013 1014 1015 1016 1017 1018

  // Invoke external hooks after the cache is cleared for API consistency.
  module_invoke_all('field_purge_field', $field);
}

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