7.x field.crud.inc field_update_instance($instance)

Updates an instance of a field.


$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['required'] = TRUE;

// Write the changed definition back.



See also



Related topics

22 calls to field_update_instance()
FieldAttachOtherTestCase::testFieldAttachPrepareViewMultiple in modules/field/tests/field.test
Tests the 'multiple entity' behavior of field_attach_prepare_view().
FieldAttachOtherTestCase::testFieldAttachView in modules/field/tests/field.test
Test field_attach_view() and field_attach_prepare_view().
FieldAttachStorageTestCase::testFieldAttachSaveLoad in modules/field/tests/field.test
Check field values insert, update and load.
FieldAttachStorageTestCase::testFieldAttachSaveMissingDataDefaultValue in modules/field/tests/field.test
Test insert with missing or NULL fields, with default value.
FieldInstanceCrudTestCase::testUpdateFieldInstance in modules/field/tests/field.test
Test the update of a field instance.

... See full list


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


function field_update_instance($instance) {

  // Check that the specified field exists.
  $field = field_read_field($instance['field_name']);
  if (empty($field)) {
    throw new FieldException(t('Attempt to update an instance of a nonexistent field @field.', array(
      '@field' => $instance['field_name'],

  // 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("Attempt to update an instance of field @field on bundle @bundle that doesn't exist.", array(
      '@field' => $instance['field_name'],
      '@bundle' => $instance['bundle'],
  $instance['id'] = $prior_instance['id'];
  $instance['field_id'] = $prior_instance['field_id'];
  _field_write_instance($instance, TRUE);

  // Clear caches.
  module_invoke_all('field_update_instance', $instance, $prior_instance);


cconrad’s picture

This doesn't look right for Drupal 7.24.

field_update_instance takes an instance array as its parameter. Thus, $instance_info['definition'] in the last line of the code example should probably just read $instance_info.

jienckebd’s picture

You're right. The example code doesn't work. Here's a working version:

$instance_info = field_info_instance($entity_type, $field_name, $bundle);
$instance_info['required'] = FALSE;
heddn’s picture