Change record status: 
Project: 
Introduced in branch: 
8.x
Description: 

Field API's field and field instance definition structures have been migrated to field_storage_config and field_config entity types leveraging the Configuration system, and can be deployed across site instances by the Configuration system "import" feature.

Summary

  • Field storage definitions become classed ConfigEntity objects (Drupal\field\Entity\FieldStorageConfig) - entity type: field_storage_config
  • Field instance definitions become classed ConfigEntity objects, (Drupal\field\Entity\FieldConfig) - entity type: field_config.
  • They can be created and updated through the regular Entity API:
    $field_storage = FieldStorageConfig::create(array(...));
    $field_storage->save();
    $field_storage->delete();
  • Like other ConfigEntity objects, they are stored in YAML files in the configuration folder, and can be deployed across site instances by the Configuration system "import" feature.
  • Deleted fields and instances pending data purging are preserved separately, in the "state" store ('field.field.deleted' and 'field.instance.deleted' keys).
  • The {field_config} && {field_config_instance} tables are deprecated, but are preserved in installations upgraded from earlier versions of Drupal to allow contrib modules to migrate their data.

  • Wherever the code refers to the $field['field_name'], use $field->id().
  • The instance config entities contain a field_name property which refers to the field

API changes

  • field_read_field(), field_read_fields(), field_create_field(), field_update_field(), field_delete_field() are replaced by the regular entity CRUD API.
  • field_read_instance(), field_read_instances(), field_create_instance(), field_update_instance() and field_instance_delete() are replaced by the regular entity CRUD API.
  • See also : hook_field_CRUD_field() and hook_field_CRUD_field_instance() hooks are replaced by hook_entity_CRUD()
  • Field storage and instance properties are accessed as object properties.
  • Created \Drupal\field\FieldStorageConfigInterface and \Drupal\field\FieldConfigInterface to define config field storages and their instances
  • The FieldConfig objects have a getFieldStorageDefinition() method to retrieve their associated FieldStorageConfig.

Examples

<?php
// Drupal 7
$field_definition = array(
 
'field_name' => 'field_description',
 
'type' => 'text',
);
field_create_field($field_definition);
$instance_definition = array(
 
'field_name' => 'field_description',
 
'entity_type' => 'taxonomy_term',
 
'bundle' => 'tags',
 
'label' => 'Custom tag description',
);
field_create_instance($instance_definition);

// Deleting field.
field_delete_field('field_name');

// Deleting instance.
$instance = field_info_instance($entity_type, $field_name, $bundle_name);
field_delete_instance($instance);
?>
<?php
// Drupal 8
$field_storage = FieldStorageConfig::create(array(
 
'name' => 'field_description',
 
'entity_type' => 'taxonomy_term',
 
'type' => 'text',
));
$field_storage->save();

$field = FieldConfig::create(array(
 
'field_name' => 'field_description',
 
'entity_type' => 'taxonomy_term',
 
'bundle' => 'tags',
 
'label' => 'Custom tag description',
));
$field->save();

// Updating field.
$field_storage->cardinality = 2;
$field_storage->save();

// Deleting field storage.
FieldStorageConfig::loadByName('entity_type', 'field_name')->delete();

// Deleting field.
FieldConfig::loadByName('entity_type', 'bundle', 'field_name')->delete();
?>
Impacts: 
Module developers
Updates Done (doc team, etc.)
Online documentation: 
Not done
Theming guide: 
Not done
Module developer documentation: 
Not done
Examples project: 
Not done
Coder Review: 
Not done
Coder Upgrade: 
Not done
Other: 
Other updates done