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

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

Summary

  • Field definitions become classed ConfigEntity objects (Drupal\field\Entity\FieldConfig) - entity type: field_config
  • Field instance definitions become classed ConfigEntity objects, (Drupal\field\Entity\FieldInstanceConfig) - entity type: field_instance_config.
  • They can be created and updated through the regular Entity API:
    $field = entity_create('field_config', array(...));
    $field->save();
    $field->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_uuid 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 and instance properties are accessed as object properties.
  • Created \Drupal\field\FieldConfigInterface and \Drupal\field\FieldInstanceConfigInterface to define config fields and their instances
  • The FieldInstanceConfig objects have a getField() method to retrieve their associated FieldConfig.

Working with field / instance definitions in upgrades

  • New helper functions for creating a field and/or instance have been added, replacing the 7000 series: _update_8003_field_create_field() and _update_8003_field_create_instance()
  • _update_7000_field_read_fields() has been removed and not replaced. You can use config_get_storage_names_with_prefix('field.field'); to get all configuration entities for fields
  • _update_7000_field_delete_field(), _update_7000_field_delete_instance have also been removed and not as there is no use case so far.

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 = entity_load('field_instance_config', 'instance');
field_delete_instance($instance);
?>

<?php
// Drupal 8
$field = entity_create('field_config', array(
 
'name' => 'field_description',
 
'entity_type' => 'taxonomy_term',
 
'type' => 'text',
));
$field->save();
$field_instance = entity_create('field_instance_config', array(
 
'field_name' => 'field_description',
 
'entity_type' => 'taxonomy_term',
 
'bundle' => 'tags',
 
'label' => 'Custom tag description',
));
$field_instance->save();
// Updating field.
$field->cardinality = 2;
$field->save();
// Deleting field.
entity_load('field_config', 'field_name')->delete();
// Deleting instance.
entity_load('field_instance_config', 'field_instance_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