field_create_instance

  1. drupal
    1. 8
    2. 7
Versions
7 – 8 field_create_instance($instance)

Creates an instance of a field, binding it to a bundle.

@throw FieldException

See: Field API data structures.

Parameters

$instance A field instance definition array. The field_name, entity_type and bundle properties are required. Other properties, if omitted, will be given the following default values:

  • label: the field name
  • description: empty string
  • required: FALSE
  • default_value_function: empty string
  • settings: each omitted setting is given the default value specified in hook_field_info().
  • widget:
  • display: Settings for the 'default' view mode will be added if not present, and each view mode in the definition will be completed with the following default values:

    View modes not present in the definition are left empty, and the field will not be displayed in this mode.

Return value

The $instance array with the id property filled in.

Related topics

▾ 65 functions call field_create_instance()

AJAXMultiFormTestCase::setUp in modules/simpletest/tests/ajax.test
Generates a random database prefix, runs the install scripts on the prefixed database and enable the specified modules. After installation many caches are flushed and the internal browser is setup so that the page requests will run on the new prefix.…
EntityFieldQueryTestCase::setUp in modules/simpletest/tests/entity_query.test
Generates a random database prefix, runs the install scripts on the prefixed database and enable the specified modules. After installation many caches are flushed and the internal browser is setup so that the page requests will run on the new prefix.…
FieldAttachOtherTestCase::testFieldAttachCache in modules/field/tests/field.test
Test field cache.
FieldAttachOtherTestCase::testFieldAttachPrepareViewMultiple in modules/field/tests/field.test
Tests the 'multiple entity' behavior of field_attach_prepare_view().
FieldAttachStorageTestCase::testFieldAttachCreateRenameBundle in modules/field/tests/field.test
Test field_attach_create_bundle() and field_attach_rename_bundle().
FieldAttachStorageTestCase::testFieldAttachDeleteBundle in modules/field/tests/field.test
Test field_attach_delete_bundle().
FieldAttachStorageTestCase::testFieldAttachLoadMultiple in modules/field/tests/field.test
Test the 'multiple' load feature.
FieldAttachStorageTestCase::testFieldAttachSaveLoadDifferentStorage in modules/field/tests/field.test
Test saving and loading fields using different storage backends.
FieldAttachStorageTestCase::testFieldStorageDetailsAlter in modules/field/tests/field.test
Test storage details alteration.
FieldAttachTestCase::setUp in modules/field/tests/field.test
Set the default field storage backend for fields created during tests.
FieldBulkDeleteTestCase::setUp in modules/field/tests/field.test
Set the default field storage backend for fields created during tests.
FieldCrudTestCase::testDeleteField in modules/field/tests/field.test
Test the deletion of a field.
FieldCrudTestCase::testUpdateField in modules/field/tests/field.test
Test updating a field.
FieldDisplayAPITestCase::setUp in modules/field/tests/field.test
Set the default field storage backend for fields created during tests.
FieldFormTestCase::testFieldFormAccess in modules/field/tests/field.test
Tests fields with no 'edit' access.
FieldFormTestCase::testFieldFormJSAddMore in modules/field/tests/field.test
FieldFormTestCase::testFieldFormMultipleWidget in modules/field/tests/field.test
Tests widgets handling multiple values.
FieldFormTestCase::testFieldFormSingle in modules/field/tests/field.test
FieldFormTestCase::testFieldFormSingleRequired in modules/field/tests/field.test
FieldFormTestCase::testFieldFormUnlimited in modules/field/tests/field.test
FieldFormTestCase::testNestedFieldForm in modules/field/tests/field.test
Tests Field API form integration within a subform.
FieldInfoTestCase::testFieldInfo in modules/field/tests/field.test
Test that field types and field definitions are correcly cached.
FieldInfoTestCase::testInstanceDisabledEntityType in modules/field/tests/field.test
Test that instances on disabled entity types are filtered out.
FieldInfoTestCase::testInstancePrepare in modules/field/tests/field.test
Test that cached instance definitions are ready for current runtime context.
FieldInstanceCrudTestCase::testCreateFieldInstance in modules/field/tests/field.test
Test the creation of a field instance.
FieldInstanceCrudTestCase::testDeleteFieldInstance in modules/field/tests/field.test
Test the deletion of a field instance.
FieldInstanceCrudTestCase::testReadFieldInstance in modules/field/tests/field.test
Test reading back an instance definition.
FieldInstanceCrudTestCase::testUpdateFieldInstance in modules/field/tests/field.test
Test the update of a field instance.
FieldSqlStorageTestCase::setUp in modules/field/modules/field_sql_storage/field_sql_storage.test
FieldSqlStorageTestCase::testFieldUpdateIndexesWithData in modules/field/modules/field_sql_storage/field_sql_storage.test
Test adding and removing indexes while data is present.
FieldSqlStorageTestCase::testUpdateFieldSchemaWithData in modules/field/modules/field_sql_storage/field_sql_storage.test
Test trying to update a field with data.
FieldTranslationsTestCase::setUp in modules/field/tests/field.test
Set the default field storage backend for fields created during tests.
FieldTranslationsTestCase::testFieldDisplayLanguage in modules/field/tests/field.test
Tests display language logic for translatable fields.
FieldUIManageFieldsTestCase::testDefaultValue in modules/field_ui/field_ui.test
Tests that default value is correctly validated and saved.
FieldUIManageFieldsTestCase::testHiddenFields in modules/field_ui/field_ui.test
Test that Field UI respects the 'no_ui' option in hook_field_info().
field_ui_field_overview_form_submit in modules/field_ui/field_ui.admin.inc
Submit handler for the field overview form.
FileFieldTestCase::attachFileField in modules/file/tests/file.test
Attach a file field to an entity.
FormsArbitraryRebuildTestCase::setUp in modules/simpletest/tests/form.test
Generates a random database prefix, runs the install scripts on the prefixed database and enable the specified modules. After installation many caches are flushed and the internal browser is setup so that the page requests will run on the new prefix.…
FormsRebuildTestCase::testPreserveFormActionAfterAJAX in modules/simpletest/tests/form.test
Tests that a form's action is retained after an Ajax submission.
forum_enable in modules/forum/forum.install
Implements hook_enable().
ImageFieldTestCase::createImageField in modules/image/image.test
Create a new image field.
ListFieldTestCase::setUp in modules/field/modules/list/tests/list.test
Set the default field storage backend for fields created during tests.
ListFieldTestCase::testUpdateAllowedValues in modules/field/modules/list/tests/list.test
Test that allowed values can be updated.
ListFieldUITestCase::createListField in modules/field/modules/list/tests/list.test
Helper function to create list field of a given type.
node_add_body_field in modules/node/node.module
Add default body field to a node type.
node_example_install in examples/node_example/node_example.install
Implements hook_install().
NumberFieldTestCase::testNumberDecimalField in modules/field/modules/number/number.test
Test number_decimal field.
OptionsWidgetsTestCase::testCheckBoxes in modules/field/modules/options/options.test
Tests the 'options_buttons' widget (multiple select).
OptionsWidgetsTestCase::testOnOffCheckbox in modules/field/modules/options/options.test
Tests the 'options_onoff' widget.
OptionsWidgetsTestCase::testRadioButtons in modules/field/modules/options/options.test
Tests the 'options_buttons' widget (single select).
OptionsWidgetsTestCase::testSelectListMultiple in modules/field/modules/options/options.test
Tests the 'options_select' widget (multiple select).
OptionsWidgetsTestCase::testSelectListSingle in modules/field/modules/options/options.test
Tests the 'options_select' widget (single select).
RdfRdfaMarkupTestCase::testAttributesInMarkupFile in modules/rdf/rdf.test
Ensure that file fields have the correct resource as the object in RDFa when displayed as a teaser.
standard_install in profiles/standard/standard.install
Implements hook_install().
TaxonomyTermFieldTestCase::setUp in modules/taxonomy/taxonomy.test
Generates a random database prefix, runs the install scripts on the prefixed database and enable the specified modules. After installation many caches are flushed and the internal browser is setup so that the page requests will run on the new prefix.…
TaxonomyTermTestCase::setUp in modules/taxonomy/taxonomy.test
Generates a random database prefix, runs the install scripts on the prefixed database and enable the specified modules. After installation many caches are flushed and the internal browser is setup so that the page requests will run on the new prefix.…
TaxonomyTermTestCase::testNodeTermCreationAndDeletion in modules/taxonomy/taxonomy.test
Test term creation with a free-tagging vocabulary from the node form.
TaxonomyTokenReplaceTestCase::setUp in modules/taxonomy/taxonomy.test
Generates a random database prefix, runs the install scripts on the prefixed database and enable the specified modules. After installation many caches are flushed and the internal browser is setup so that the page requests will run on the new prefix.…
TaxonomyVocabularyUnitTest::testTaxonomyVocabularyChangeMachineName in modules/taxonomy/taxonomy.test
Tests that machine name changes are properly reflected.
TaxonomyVocabularyUnitTest::testUninstallReinstall in modules/taxonomy/taxonomy.test
Test uninstall and reinstall of the taxonomy module.
TextFieldTestCase::testTextFieldValidation in modules/field/modules/text/text.test
Test text field validation.
TextFieldTestCase::_testTextfieldWidgets in modules/field/modules/text/text.test
Helper function for testTextfieldWidgets().
TextFieldTestCase::_testTextfieldWidgetsFormatted in modules/field/modules/text/text.test
Helper function for testTextfieldWidgetsFormatted().
UserRegistrationTestCase::testRegistrationWithUserFields in modules/user/user.test
Tests Field API fields on user registration forms.
_comment_body_field_create in modules/comment/comment.module
Creates a comment_body field instance for a given node type.

Code

modules/field/field.crud.inc, line 450

<?php
function field_create_instance($instance) {
  $field = field_read_field($instance['field_name']);
  if (empty($field)) {
    throw new FieldException(t("Attempt to create an instance of a field @field_name that doesn't exist or is currently inactive.", array('@field_name' => $instance['field_name'])));
  }
  // Check that the required properties exists.
  if (empty($instance['entity_type'])) {
    throw new FieldException(t('Attempt to create an instance of field @field_name without an entity type.', array('@field_name' => $instance['field_name'])));
  }
  if (empty($instance['bundle'])) {
    throw new FieldException(t('Attempt to create an instance of field @field_name without a bundle.', array('@field_name' => $instance['field_name'])));
  }
  // Check that the field can be attached to this entity type.
  if (!empty($field['entity_types']) && !in_array($instance['entity_type'], $field['entity_types'])) {
    throw new FieldException(t('Attempt to create an instance of field @field_name on forbidden entity type @entity_type.', array('@field_name' => $instance['field_name'], '@entity_type' => $instance['entity_type'])));
  }

  // Set the field id.
  $instance['field_id'] = $field['id'];

  // Note that we do *not* prevent creating a field on non-existing bundles,
  // because that would break the 'Body as field' upgrade for contrib
  // node types.

  // TODO: Check that the widget type is known and can handle the field type ?
  // TODO: Check that the formatters are known and can handle the field type ?
  // TODO: Check that the display view modes are known for the entity type ?
  // Those checks should probably happen in _field_write_instance() ?
  // Problem : this would mean that a UI module cannot update an instance with a disabled formatter.

  // Ensure the field instance is unique within the bundle.
  // We only check for instances of active fields, since adding an instance of
  // a disabled field is not supported.
  $prior_instance = field_read_instance($instance['entity_type'], $instance['field_name'], $instance['bundle']);
  if (!empty($prior_instance)) {
    $message = t('Attempt to create an instance of field @field_name on bundle @bundle that already has an instance of that field.', array('@field_name' => $instance['field_name'], '@bundle' => $instance['bundle']));
    throw new FieldException($message);
  }

  _field_write_instance($instance);

  // Clear caches
  field_cache_clear();

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

  return $instance;
}
?>