1 field.crud.inc field_create_field($field)

Creates a field.

This function does not bind the field to any bundle; use field_create_instance() for that.

Parameters

$field: A field definition array. The field_name and type properties are required. 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 carefully, for it might seriously affect the site's performance.
  • settings: each omitted setting is given the default value defined in hook_field_info().
  • storage:
    • type: the storage backend specified in the 'field_storage_default' system variable.
    • settings: each omitted setting is given the default value specified in hook_field_storage_info().

Return value

The $field array with the id property filled in.:

Throws

FieldException

See: Field API data structures.

Related topics

Field CRUD API Create, update, and delete Field API fields, bundles, and instances.

File

core/modules/field/field.crud.inc, line 82
Field CRUD API, handling field and field instance creation and deletion.

Code

function field_create_field($field) {
  // Populate defaults.
  $field += field_defaults_field();
  $field['settings'] += field_info_field_settings($field['type']);

  // Validate the fully populated field.
  field_validate_field($field);

  // 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'])));
  }

  $field['module'] = $field_type['module'];
  $field['active'] = 1;

  // Provide default storage.
  $field['storage'] += array(
    'type' => '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;

  // Fields have a large amount of data that is generated on load, so trim down
  // the entire structure to just that which is not replaced on load.
  $field_data = array_intersect_key($field, field_defaults_field());
  if (isset($field_data['storage']['details'])) {
    unset($field_data['storage']['details']);
  }

  // Store the field in config.
  $config = config('field.field.' . $field['field_name']);
  $config->setData($field_data);
  $config->save();

  // Collect storage information.
  $schema = field_retrieve_schema($field);
  $field['columns'] = $schema['columns'];
  $field['foreign keys'] = $schema['foreign keys'];
  $field['indexes'] = $schema['indexes'];

  try {
    // Invoke hook_field_storage_create_field after
    // backdrop_write_record() sets the field id.
    module_invoke($storage_type['module'], 'field_storage_create_field', $field);
  }
  catch (Exception $e) {
    // Delete the config if the field storage could not be created.
    $config->delete();
    throw $e;
  }

  // Clear caches
  field_cache_clear();

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

  return $field;
}