1 field.crud.inc field_update_instance($instance)

Updates an instance of a field.

Parameters

$instance: An associative array representing an instance structure. The following required array elements specify which field instance is being updated:

  • 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.

The other array elements represent properties of the instance, and all properties must be specified or their default values will be used (except internal-use properties, which are assigned automatically). To avoid losing the previously stored properties of the instance when making a change, first load the instance with field_info_instance(), then override the values you want to override, and finally save using this function. Example:

  // Fetch an instance info array.
  $instance_info = field_info_instance($entity_type, $field_name, $bundle_name);
  // Change a single property in the instance definition.
  $instance_info['definition']['required'] = TRUE;
  // Write the changed definition back.
  field_update_instance($instance_info['definition']);

Throws

FieldException

See also

field_info_instance()

field_create_instance()

Related topics

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

File

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

Code

function field_update_instance($instance) {
  // Check that the field instance exists (even if it is inactive, since we
  // want to be able to replace inactive widgets with new ones).
  $prior_instance = field_read_instance($instance['entity_type'], $instance['field_name'], $instance['bundle'], array('include_inactive' => TRUE));
  if (empty($prior_instance)) {
    throw new FieldException(t('The field instance "@label" of field "@field" cannot be saved because an instance of this field on the bundle "@bundle" does not exist.', array('@label' => $instance['label'], '@field' => $instance['field_name'], '@bundle' => $instance['bundle'])));
  }

  // Populate defaults.
  $field = field_read_field($instance['field_name']);
  $instance += $prior_instance;
  $instance += field_defaults_instance();
  $instance['settings'] += $prior_instance['settings'];
  $instance['settings'] += field_info_instance_settings($field['type']);

  // Validate the fully populated field.
  field_validate_instance($instance, TRUE);

  _field_write_instance($instance, TRUE);

  // Clear caches.
  field_cache_clear();

  module_invoke_all('field_update_instance', $instance, $prior_instance);
  token_cache_clear();
}