Club Drupal

<?php

/**

 * @file

 * Field attach API, allowing entities (nodes, users, ...) to be 'fieldable'.

 */

/**

 * Exception thrown by field_attach_validate() on field validation errors.

 */

class FieldValidationException extends FieldException {

  var $errors;

 /**

  * Constructor for FieldValidationException.

  *

  * @param $errors

  *   An array of field validation errors, keyed by field name and

  *   delta that contains two keys:

  *   - 'error': A machine-readable error code string, prefixed by

  *     the field module name. A field widget may use this code to decide

  *     how to report the error.

  *   - 'message': A human-readable error message such as to be

  *     passed to form_error() for the appropriate form element.

  */

  function __construct($errors) {

    $this->errors = $errors;

    parent::__construct(t('Field validation errors'));

  }

}

/**

 * @defgroup field_storage Field Storage API

 * @{

 * Implement a storage engine for Field API data.

 *

 * The Field Attach API uses the Field Storage API to perform all "database

 * access". Each Field Storage API hook function defines a primitive database

 * operation such as read, write, or delete. The default field storage module,

 * field_sql_storage.module, uses the local SQL database to implement these

 * operations, but alternative field storage backends can choose to represent

 * the data in SQL differently or use a completely different storage mechanism

 * such as a cloud-based database.

 *

 * Each field defines which storage backend it uses. The Drupal system variable

 * 'field_storage_default' identifies the storage backend used by default.

 *

 * See @link field Field API @endlink for information about the other parts of

 * the Field API.

 */

/**

 * Argument for an update operation.

 *

 * This is used in hook_field_storage_write when updating an

 * existing entity.

 */

define('FIELD_STORAGE_UPDATE', 'update');

/**

 * Argument for an insert operation.

 *

 * This is used in hook_field_storage_write when inserting a new entity.

 */

define('FIELD_STORAGE_INSERT', 'insert');

/**

 * @} End of "defgroup field_storage".

 */

/**

 * @defgroup field_attach Field Attach API

 * @{

 * Operate on Field API data attached to Drupal entities.

 *

 * Field Attach API functions load, store, display, generate Field API

 * structures, and perform a variety of other functions for field data attached

 * to individual entities.

 *

 * Field Attach API functions generally take $entity_type and $entity arguments

 * along with additional function-specific arguments. $entity_type is the type

 * of the fieldable entity, such as 'node' or 'user', and $entity is the entity

 * itself.

 *

 * hook_entity_info() is the central place for entity types to define if and

 * how Field API should operate on their entity objects. Notably, the

 * 'fieldable' property needs to be set to TRUE.

 *

 * The Field Attach API uses the concept of bundles: the set of fields for a

 * given entity is defined on a per-bundle basis. The collection of bundles for

 * an entity type is defined its hook_entity_info() implementation. For

 * instance, node_entity_info() exposes each node type as its own bundle. This

 * means that the set of fields of a node is determined by the node type. The

 * Field API reads the bundle name for a given entity from a particular

 * property of the entity object, and hook_entity_info() defines which property

 * to use. For instance, node_entity_info() specifies:

 * @code $info['entity keys']['bundle'] = 'type'@endcode

 * This indicates that for a particular node object, the bundle name can be

 * found in $node->type. This property can be omitted if the entity type only

 * exposes a single bundle (all entities of this type have the same collection

 * of fields). This is the case for the 'user' entity type.

 *

 * Most Field Attach API functions define a corresponding hook function that

 * allows any module to act on Field Attach operations for any entity after the

 * operation is complete, and access or modify all the field, form, or display

 * data for that entity and operation. For example, field_attach_view() invokes

 * hook_field_attach_view_alter(). These all-module hooks are distinct from

 * those of the Field Types API, such as hook_field_load(), that are only

 * invoked for the module that defines a specific field type.

 *

 * field_attach_load(), field_attach_insert(), and field_attach_update() also

 * define pre-operation hooks, e.g. hook_field_attach_pre_load(). These hooks

 * run before the corresponding Field Storage API and Field Type API

 * operations. They allow modules to define additional storage locations (e.g.

 * denormalizing, mirroring) for field data on a per-field basis. They also

 * allow modules to take over field storage completely by instructing other

 * implementations of the same hook and the Field Storage API itself not to

 * operate on specified fields.

 *

 * The pre-operation hooks do not make the Field Storage API irrelevant. The

 * Field Storage API is essentially the "fallback mechanism" for any fields

 * that aren't being intercepted explicitly by pre-operation hooks.

 *

 * @link field_language Field Language API @endlink provides information about

 * the structure of field objects.

 *

 * See @link field Field API @endlink for information about the other parts of

 * the Field API.

 */

/**

 * Invoke a field hook.

 *

 * @param $op

 *   Possible operations include:

 *   - form

 *   - validate

 *   - presave

 *   - insert

 *   - update

 *   - delete

 *   - delete revision

 *   - view

 *   - prepare translation

 * @param $entity_type

 *   The type of $entity; e.g. 'node' or 'user'.

 * @param $entity

 *   The fully formed $entity_type entity.

 * @param $a

 *   - The $form in the 'form' operation.

 *   - The value of $view_mode in the 'view' operation.

 *   - Otherwise NULL.

 * @param $b

 *   - The $form_state in the 'submit' operation.

 *   - Otherwise NULL.

 * @param $options

 *   An associative array of additional options, with the following keys:

 *  - 'field_name': The name of the field whose operation should be

 *    invoked. By default, the operation is invoked on all the fields

 *    in the entity's bundle. NOTE: This option is not compatible with

 *    the 'deleted' option; the 'field_id' option should be used

 *    instead.

 *  - 'field_id': The id of the field whose operation should be

 *    invoked. By default, the operation is invoked on all the fields

 *    in the entity's' bundles.

 *  - 'default': A boolean value, specifying which implementation of

 *    the operation should be invoked.

 *    - if FALSE (default), the field types implementation of the operation

 *      will be invoked (hook_field_[op])

 *    - If TRUE, the default field implementation of the field operation

 *      will be invoked (field_default_[op])

 *    Internal use only. Do not explicitely set to TRUE, but use

 *    _field_invoke_default() instead.

 *  - 'deleted': If TRUE, the function will operate on deleted fields

 *    as well as non-deleted fields. If unset or FALSE, only

 *    non-deleted fields are operated on.

 *  - 'language': A language code or an array of language codes keyed by field

 *    name. It will be used to narrow down to a single value the available

 *    languages to act on.

 */

function _field_invoke($op, $entity_type, $entity, &$a = NULL, &$b = NULL, $options = array()) {

  // Merge default options.

  $default_options = array(

    'default' => FALSE,

    'deleted' => FALSE,

    'language' => NULL,

  );

  $options += $default_options;

  // Determine the list of instances to iterate on.

  list(, , $bundle) = entity_extract_ids($entity_type, $entity);

  $instances = _field_invoke_get_instances($entity_type, $bundle, $options);

  // Iterate through the instances and collect results.

  $return = array();

  foreach ($instances as $instance) {

    // field_info_field() is not available for deleted fields, so use

    // field_info_field_by_id().

    $field = field_info_field_by_id($instance['field_id']);

    $field_name = $field['field_name'];

    $function = $options['default'] ? 'field_default_' . $op : $field['module'] . '_field_' . $op;

    if (function_exists($function)) {

      // Determine the list of languages to iterate on.

      $available_languages = field_available_languages($entity_type, $field);

      $languages = _field_language_suggestion($available_languages, $options['language'], $field_name);

      foreach ($languages as $langcode) {

        $items = isset($entity->{$field_name}[$langcode]) ? $entity->{$field_name}[$langcode] : array();

        $result = $function($entity_type, $entity, $field, $instance, $langcode, $items, $a, $b);

        if (isset($result)) {

          // For hooks with array results, we merge results together.

          // For hooks with scalar results, we collect results in an array.

          if (is_array($result)) {

            $return = array_merge($return, $result);

          }

          else {

            $return[] = $result;

          }

        }

        // Populate $items back in the field values, but avoid replacing missing

        // fields with an empty array (those are not equivalent on update).

        if ($items !== array() || isset($entity->{$field_name}[$langcode])) {

          $entity->{$field_name}[$langcode] = $items;

        }

      }

    }

  }

  return $return;

}

/**

 * Invoke a field hook across fields on multiple entities.

 *

 * @param $op

 *   Possible operations include:

 *   - load

 *   - prepare_view

 *   For all other operations, use _field_invoke() / field_invoke_default()

 *   instead.

 * @param $entity_type

 *   The type of $entity; e.g. 'node' or 'user'.

 * @param $entities

 *   An array of entities, keyed by entity id.

 * @param $a

 *   - The $age parameter in the 'load' operation.

 *   - Otherwise NULL.

 * @param $b

 *   Currently always NULL.

 * @param $options

 *   An associative array of additional options, with the following keys:

 *  - 'field_name': The name of the field whose operation should be

 *    invoked. By default, the operation is invoked on all the fields

 *    in the entity's bundle. NOTE: This option is not compatible with

 *    the 'deleted' option; the 'field_id' option should be used instead.

 *  - 'field_id': The id of the field whose operation should be

 *    invoked. By default, the operation is invoked on all the fields

 *    in the entity's' bundles.

 *  - 'default': A boolean value, specifying which implementation of

 *    the operation should be invoked.

 *    - if FALSE (default), the field types implementation of the operation

 *      will be invoked (hook_field_[op])

 *    - If TRUE, the default field implementation of the field operation

 *      will be invoked (field_default_[op])

 *    Internal use only. Do not explicitely set to TRUE, but use

 *    _field_invoke_multiple_default() instead.

 *  - 'deleted': If TRUE, the function will operate on deleted fields

 *    as well as non-deleted fields. If unset or FALSE, only

 *    non-deleted fields are operated on.

 *  - 'language': A language code or an array of arrays of language codes keyed

 *    by entity id and field name. It will be used to narrow down to a single

 *    value the available languages to act on.

 *

 * @return

 *   An array of returned values keyed by entity id.

 */

function _field_invoke_multiple($op, $entity_type, $entities, &$a = NULL, &$b = NULL, $options = array()) {

  // Merge default options.

  $default_options = array(

    'default' => FALSE,

    'deleted' => FALSE,

    'language' => NULL,

  );

  $options += $default_options;

  $fields = array();

  $grouped_instances = array();

  $grouped_entities = array();

  $grouped_items = array();

  $return = array();

  // Go through the entities and collect the fields on which the hook should be

  // invoked.

  //

  // We group fields by id, not by name, because this function can operate on

  // deleted fields which may have non-unique names. However, entities can only

  // contain data for a single field for each name, even if that field

  // is deleted, so we reference field data via the

  // $entity->$field_name property.

  foreach ($entities as $entity) {

    // Determine the list of instances to iterate on.

    list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);

    $instances = _field_invoke_get_instances($entity_type, $bundle, $options);

    foreach ($instances as $instance) {

      $field_id = $instance['field_id'];

      $field_name = $instance['field_name'];

      $field = field_info_field_by_id($field_id);

      $function = $options['default'] ? 'field_default_' . $op : $field['module'] . '_field_' . $op;

      if (function_exists($function)) {

        // Add the field to the list of fields to invoke the hook on.

        if (!isset($fields[$field_id])) {

          $fields[$field_id] = $field;

        }

        // Extract the field values into a separate variable, easily accessed

        // by hook implementations.

        // Unless a language suggestion is provided we iterate on all the

        // available languages.

        $available_languages = field_available_languages($entity_type, $field);

        $language = is_array($options['language']) && !empty($options['language'][$id]) ? $options['language'][$id] : $options['language'];

        $languages = _field_language_suggestion($available_languages, $language, $field_name);

        foreach ($languages as $langcode) {

          $grouped_items[$field_id][$langcode][$id] = isset($entity->{$field_name}[$langcode]) ? $entity->{$field_name}[$langcode] : array();

          // Group the instances and entities corresponding to the current

          // field.

          $grouped_instances[$field_id][$langcode][$id] = $instance;

          $grouped_entities[$field_id][$langcode][$id] = $entities[$id];

        }

      }

    }

    // Initialize the return value for each entity.

    $return[$id] = array();

  }

  // For each field, invoke the field hook and collect results.

  foreach ($fields as $field_id => $field) {

    $field_name = $field['field_name'];

    $function = $options['default'] ? 'field_default_' . $op : $field['module'] . '_field_' . $op;

    // Iterate over all the field translations.

    foreach ($grouped_items[$field_id] as $langcode => &$items) {

      $entities = $grouped_entities[$field_id][$langcode];

      $instances = $grouped_instances[$field_id][$langcode];

      $results = $function($entity_type, $entities, $field, $instances, $langcode, $items, $a, $b);

      if (isset($results)) {

        // Collect results by entity.

        // For hooks with array results, we merge results together.

        // For hooks with scalar results, we collect results in an array.

        foreach ($results as $id => $result) {

          if (is_array($result)) {

            $return[$id] = array_merge($return[$id], $result);

          }

          else {

            $return[$id][] = $result;

          }

        }

      }

    }

    // Populate field values back in the entities, but avoid replacing missing

    // fields with an empty array (those are not equivalent on update).

    foreach ($grouped_entities[$field_id] as $langcode => $entities) {

      foreach ($entities as $id => $entity) {

        if ($grouped_items[$field_id][$langcode][$id] !== array() || isset($entity->{$field_name}[$langcode])) {

          $entity->{$field_name}[$langcode] = $grouped_items[$field_id][$langcode][$id];

        }

      }

    }

  }

  return $return;

}

/**

 * Invoke field.module's version of a field hook.

 *

 * This function invokes the field_default_[op]() function.

 * Use _field_invoke() to invoke the field type implementation,

 * hook_field_[op]().

 *

 * @see _field_invoke()

 */

function _field_invoke_default($op, $entity_type, $entity, &$a = NULL, &$b = NULL, $options = array()) {

  $options['default'] = TRUE;

  return _field_invoke($op, $entity_type, $entity, $a, $b, $options);

}

/**

 * Invoke field.module's version of a field hook on multiple entities.

 *

 * This function invokes the field_default_[op]() function.

 * Use _field_invoke_multiple() to invoke the field type implementation,

 * hook_field_[op]().

 *

 * @see _field_invoke_multiple()

 */

function _field_invoke_multiple_default($op, $entity_type, $entities, &$a = NULL, &$b = NULL, $options = array()) {

  $options['default'] = TRUE;

  return _field_invoke_multiple($op, $entity_type, $entities, $a, $b, $options);

}

/**

 * Helper for _field_invoke(): retrieves a list of instances to operate on.

 *

 * @param $entity_type

 *   The entity type.

 * @param $bundle

 *   The bundle name.

 * @param $options

 *   An associative array of options, as provided to _field_invoke(). Only the

 *   following keys are considered :

 *   - deleted

 *   - field_name

 *   - field_id

 *   See _field_invoke() for details.

 *

 * @return

 *   The array of selected instance definitions.

 */

function _field_invoke_get_instances($entity_type, $bundle, $options) {

  if ($options['deleted']) {

    // Deleted fields are not included in field_info_instances(), and need to

    // be fetched from the database with field_read_instances().

    $params = array('entity_type' => $entity_type, 'bundle' => $bundle);

    if (isset($options['field_id'])) {

      // Single-field mode by field id: field_read_instances() does the filtering.

      // Single-field mode by field name is not compatible with the 'deleted'

      // option.

      $params['field_id'] = $options['field_id'];

    }

    $instances = field_read_instances($params, array('include_deleted' => TRUE));

  }

  elseif (isset($options['field_name'])) {

    // Single-field mode by field name: field_info_instance() does the

    // filtering.

    $instances = array(field_info_instance($entity_type, $options['field_name'], $bundle));

  }

  else {

    $instances = field_info_instances($entity_type, $bundle);

    if (isset($options['field_id'])) {

      // Single-field mode by field id: we need to loop on each instance to

      // find the right one.

      foreach ($instances as $instance) {

        if ($instance['field_id'] == $options['field_id']) {

          $instances = array($instance);

          break;

        }

      }

    }

  }

  return $instances;

}

/**

 * Add form elements for all fields for an entity to a form structure.

 *

 * The form elements for the entity's fields are added by reference as direct

 * children in the $form parameter. This parameter can be a full form structure

 * (most common case for entity edit forms), or a sub-element of a larger form.

 *

 * By default, submitted field values appear at the top-level of

 * $form_state['values']. A different location within $form_state['values'] can

 * be specified by setting the '#parents' property on the incoming $form

 * parameter. Because of name clashes, two instances of the same field cannot

 * appear within the same $form element, or within the same '#parents' space.

 *

 * For each call to field_attach_form(), field values are processed by calling

 * field_attach_form_validate() and field_attach_submit() on the same $form

 * element.

 *

 * Sample resulting structure in $form:

 * @code

 *   '#parents' => The location of field values in $form_state['values'],

 *   '#entity_type' => The name of the entity type,

 *   '#bundle' => The name of the bundle,

 *   // One sub-array per field appearing in the entity, keyed by field name.

 *   // The structure of the array differs slightly depending on whether the

 *   // widget is 'single-value' (provides the input for one field value,

 *   // most common case), and will therefore be repeated as many times as

 *   // needed, or 'multiple-values' (one single widget allows the input of

 *   // several values, e.g checkboxes, select box...).

 *   // The sub-array is nested into a $langcode key where $langcode has the

 *   // same value of the $langcode parameter above.

 *   // The '#language' key holds the same value of $langcode and it is used

 *   // to access the field sub-array when $langcode is unknown.

 *   'field_foo' => array(

 *     '#tree' => TRUE,

 *     '#field_name' => The name of the field,

 *     '#language' => $langcode,

 *     $langcode => array(

 *       '#field_name' => The name of the field,

 *       '#language' => $langcode,

 *       '#field_parents' => The 'parents' space for the field in the form,

 *          equal to the #parents property of the $form parameter received by

 *          field_attach_form(),

 *       '#required' => Whether or not the field is required,

 *       '#title' => The label of the field instance,

 *       '#description' => The description text for the field instance,

 *

 *       // Only for 'single' widgets:

 *       '#theme' => 'field_multiple_value_form',

 *       '#cardinality' => The field cardinality,

 *       // One sub-array per copy of the widget, keyed by delta.

 *       0 => array(

 *         '#entity_type' => The name of the entity type,

 *         '#bundle' => The name of the bundle,

 *         '#field_name' => The name of the field,

 *         '#field_parents' => The 'parents' space for the field in the form,

 *            equal to the #parents property of the $form parameter received by

 *            field_attach_form(),

 *         '#title' => The title to be displayed by the widget,

 *         '#default_value' => The field value for delta 0,

 *         '#required' => Whether the widget should be marked required,

 *         '#delta' => 0,

 *         '#columns' => The array of field columns,

 *         // The remaining elements in the sub-array depend on the widget.

 *         '#type' => The type of the widget,

 *         ...

 *       ),

 *       1 => array(

 *         ...

 *       ),

 *

 *       // Only for multiple widgets:

 *       '#entity_type' => The name of the entity type,

 *       '#bundle' => $instance['bundle'],

 *       '#columns'  => array_keys($field['columns']),

 *       // The remaining elements in the sub-array depend on the widget.

 *       '#type' => The type of the widget,

 *       ...

 *     ),

 *     ...

 *   ),

 * )

 * @endcode

 *

 * Additionally, some processing data is placed in $form_state, and can be

 * accessed by field_form_get_state() and field_form_set_state().

 *

 * @param $entity_type

 *   The type of $entity; e.g. 'node' or 'user'.

 * @param $entity

 *   The entity for which to load form elements, used to initialize

 *   default form values.

 * @param $form

 *   The form structure to fill in. This can be a full form structure, or a

 *   sub-element of a larger form. The #parents property can be set to control

 *   the location of submitted field values within $form_state['values']. If

 *   not specified, $form['#parents'] is set to an empty array, placing field

 *   values at the top-level of $form_state['values'].

 * @param $form_state

 *   An associative array containing the current state of the form.

 * @param $langcode

 *   The language the field values are going to be entered, if no language

 *   is provided the default site language will be used.

 * @param array $options

 *   An associative array of additional options. See _field_invoke() for

 *   details.

 *

 * @see field_form_get_state()

 * @see field_form_set_state()

 */

function field_attach_form($entity_type, $entity, &$form, &$form_state, $langcode = NULL, $options = array()) {

  // Validate $options since this is a new parameter added after Drupal 7 was

  // released.

  $options = is_array($options) ? $options : array();

  // Set #parents to 'top-level' by default.

  $form += array('#parents' => array());

  // If no language is provided use the default site language.

  $options['language'] = field_valid_language($langcode);

  $form += (array) _field_invoke_default('form', $entity_type, $entity, $form, $form_state, $options);

  // Add custom weight handling.

  list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);

  $form['#pre_render'][] = '_field_extra_fields_pre_render';

  $form['#entity_type'] = $entity_type;

  $form['#bundle'] = $bundle;

  // Let other modules make changes to the form.

  // Avoid module_invoke_all() to let parameters be taken by reference.

  foreach (module_implements('field_attach_form') as $module) {

    $function = $module . '_field_attach_form';

    $function($entity_type, $entity, $form, $form_state, $langcode);

  }

}

/**

 * Loads fields for the current revisions of a group of entities.

 *

 * Loads all fields for each entity object in a group of a single entity type.

 * The loaded field values are added directly to the entity objects.

 *

 * field_attach_load() is automatically called by the default entity controller

 * class, and thus, in most cases, doesn't need to be explicitly called by the

 * entity type module.

 *

 * @param $entity_type

 *   The type of $entity; e.g., 'node' or 'user'.

 * @param $entities

 *   An array of entities for which to load fields, keyed by entity ID.

 *   Each entity needs to have its 'bundle', 'id' and (if applicable)

 *   'revision' keys filled in. The function adds the loaded field data

 *   directly in the entity objects of the $entities array.

 * @param $age

 *   FIELD_LOAD_CURRENT to load the most recent revision for all

 *   fields, or FIELD_LOAD_REVISION to load the version indicated by

 *   each entity. Defaults to FIELD_LOAD_CURRENT; use

 *   field_attach_load_revision() instead of passing FIELD_LOAD_REVISION.

 * @param $options

 *   An associative array of additional options, with the following keys:

 *   - 'field_id': The field ID that should be loaded, instead of

 *     loading all fields, for each entity. Note that returned entities

 *     may contain data for other fields, for example if they are read

 *     from a cache.

 *   - 'deleted': If TRUE, the function will operate on deleted fields

 *     as well as non-deleted fields. If unset or FALSE, only

 *     non-deleted fields are operated on.

 */

function field_attach_load($entity_type, $entities, $age = FIELD_LOAD_CURRENT, $options = array()) {

  $load_current = $age == FIELD_LOAD_CURRENT;

  // Merge default options.

  $default_options = array(

    'deleted' => FALSE,

  );

  $options += $default_options;

  $info = entity_get_info($entity_type);

  // Only the most current revision of non-deleted fields for cacheable entity

  // types can be cached.

  $cache_read = $load_current && $info['field cache'] && empty($options['deleted']);

  // In addition, do not write to the cache when loading a single field.

  $cache_write = $cache_read && !isset($options['field_id']);

  if (empty($entities)) {

    return;

  }

  // Assume all entities will need to be queried. Entities found in the cache

  // will be removed from the list.

  $queried_entities = $entities;

  // Fetch available entities from cache, if applicable.

  if ($cache_read) {

    // Build the list of cache entries to retrieve.

    $cids = array();

    foreach ($entities as $id => $entity) {

      $cids[] = "field:$entity_type:$id";

    }

    $cache = cache_get_multiple($cids, 'cache_field');

    // Put the cached field values back into the entities and remove them from

    // the list of entities to query.

    foreach ($entities as $id => $entity) {

      $cid = "field:$entity_type:$id";

      if (isset($cache[$cid])) {

        unset($queried_entities[$id]);

        foreach ($cache[$cid]->data as $field_name => $values) {

          $entity->$field_name = $values;

        }

      }

    }

  }

  // Fetch other entities from their storage location.

  if ($queried_entities) {

    // The invoke order is:

    // - hook_field_storage_pre_load()

    // - storage backend's hook_field_storage_load()

    // - field-type module's hook_field_load()

    // - hook_field_attach_load()

    // Invoke hook_field_storage_pre_load(): let any module load field

    // data before the storage engine, accumulating along the way.

    $skip_fields = array();

    foreach (module_implements('field_storage_pre_load') as $module) {

      $function = $module . '_field_storage_pre_load';

      $function($entity_type, $queried_entities, $age, $skip_fields, $options);

    }

    $instances = array();

    // Collect the storage backends used by the remaining fields in the entities.

    $storages = array();

    foreach ($queried_entities as $entity) {

      list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);

      $instances = _field_invoke_get_instances($entity_type, $bundle, $options);

      foreach ($instances as $instance) {

        $field_name = $instance['field_name'];

        $field_id = $instance['field_id'];

        // Make sure all fields are present at least as empty arrays.

        if (!isset($queried_entities[$id]->{$field_name})) {

          $queried_entities[$id]->{$field_name} = array();

        }

        // Collect the storage backend if the field has not been loaded yet.

        if (!isset($skip_fields[$field_id])) {

          $field = field_info_field_by_id($field_id);

          $storages[$field['storage']['type']][$field_id][] = $load_current ? $id : $vid;

        }

      }

    }

    // Invoke hook_field_storage_load() on the relevant storage backends.

    foreach ($storages as $storage => $fields) {

      $storage_info = field_info_storage_types($storage);

      module_invoke($storage_info['module'], 'field_storage_load', $entity_type, $queried_entities, $age, $fields, $options);

    }

    // Invoke field-type module's hook_field_load().

    $null = NULL;

    _field_invoke_multiple('load', $entity_type, $queried_entities, $age, $null, $options);

    // Invoke hook_field_attach_load(): let other modules act on loading the

    // entity.

    module_invoke_all('field_attach_load', $entity_type, $queried_entities, $age, $options);

    // Build cache data.

    if ($cache_write) {

      foreach ($queried_entities as $id => $entity) {

        $data = array();

        list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);

        $instances = field_info_instances($entity_type, $bundle);

        foreach ($instances as $instance) {

          $data[$instance['field_name']] = $queried_entities[$id]->{$instance['field_name']};

        }

        $cid = "field:$entity_type:$id";

        cache_set($cid, $data, 'cache_field');

      }

    }

  }

}

/**

 * Load all fields for previous versions of a group of entities.

 *

 * Loading different versions of the same entities is not supported, and should

 * be done by separate calls to the function.

 *

 * field_attach_load_revision() is automatically called by the default entity

 * controller class, and thus, in most cases, doesn't need to be explicitly

 * called by the entity type module.

 *

 * @param $entity_type

 *   The type of $entity; e.g. 'node' or 'user'.

 * @param $entities

 *   An array of entities for which to load fields, keyed by entity ID. Each

 *   entity needs to have its 'bundle', 'id' and (if applicable) 'revision'

 *   keys filled. The function adds the loaded field data directly in the

 *   entity objects of the $entities array.

 * @param $options

 *   An associative array of additional options. See field_attach_load() for

 *   details.

 */

function field_attach_load_revision($entity_type, $entities, $options = array()) {

  return field_attach_load($entity_type, $entities, FIELD_LOAD_REVISION, $options);

}

/**

 * Perform field validation against the field data in an entity.

 *

 * This function does not perform field widget validation on form

 * submissions. It is intended to be called during API save

 * operations. Use field_attach_form_validate() to validate form

 * submissions.

 *

 * @param $entity_type

 *   The type of $entity; e.g. 'node' or 'user'.

 * @param $entity

 *   The entity with fields to validate.

 * @throws FieldValidationException

 *   If validation errors are found, a FieldValidationException is thrown. The

 *   'errors' property contains the array of errors, keyed by field name,

 *   language and delta.

 * @param array $options

 *   An associative array of additional options. See _field_invoke() for

 *   details.

 */

function field_attach_validate($entity_type, $entity, $options = array()) {

  // Validate $options since this is a new parameter added after Drupal 7 was

  // released.

  $options = is_array($options) ? $options : array();

  $errors = array();

  // Check generic, field-type-agnostic errors first.

  $null = NULL;

  _field_invoke_default('validate', $entity_type, $entity, $errors, $null, $options);

  // Check field-type specific errors.

  _field_invoke('validate', $entity_type, $entity, $errors, $null, $options);

  // Let other modules validate the entity.

  // Avoid module_invoke_all() to let $errors be taken by reference.

  foreach (module_implements('field_attach_validate') as $module) {

    $function = $module . '_field_attach_validate';

    $function($entity_type, $entity, $errors);

  }

  if ($errors) {

    throw new FieldValidationException($errors);

  }

}

/**

 * Perform field validation against form-submitted field values.

 *

 * There are two levels of validation for fields in forms: widget

 * validation, and field validation.

 * - Widget validation steps are specific to a given widget's own form

 *   structure and UI metaphors. They are executed through FAPI's

 *   #element_validate property during normal form validation.

 * - Field validation steps are common to a given field type, independently of

 *   the specific widget being used in a given form. They are defined in the

 *   field type's implementation of hook_field_validate().

 *

 * This function performs field validation in the context of a form

 * submission. It converts field validation errors into form errors

 * on the correct form elements. Fieldable entity types should call

 * this function during their own form validation function.

 *

 * @param $entity_type

 *   The type of $entity; e.g. 'node' or 'user'.

 * @param $entity

 *   The entity being submitted. The 'bundle', 'id' and (if applicable)

 *   'revision' keys should be present. The actual field values will be read

 *   from $form_state['values'].

 * @param $form

 *   The form structure where field elements are attached to. This might be a

 *   full form structure, or a sub-element of a larger form.

 * @param $form_state

 *   An associative array containing the current state of the form.

 * @param array $options

 *   An associative array of additional options. See _field_invoke() for

 *   details.

 */

function field_attach_form_validate($entity_type, $entity, $form, &$form_state, $options = array()) {

  // Validate $options since this is a new parameter added after Drupal 7 was

  // released.

  $options = is_array($options) ? $options : array();

  // Extract field values from submitted values.

  _field_invoke_default('extract_form_values', $entity_type, $entity, $form, $form_state);

  // Perform field_level validation.

  try {

    field_attach_validate($entity_type, $entity, $options);

  }

  catch (FieldValidationException $e) {

    // Pass field-level validation errors back to widgets for accurate error

    // flagging.

    foreach ($e->errors as $field_name => $field_errors) {

      foreach ($field_errors as $langcode => $errors) {

        $field_state = field_form_get_state($form['#parents'], $field_name, $langcode, $form_state);

        $field_state['errors'] = $errors;

        field_form_set_state($form['#parents'], $field_name, $langcode, $form_state, $field_state);

      }

    }

    _field_invoke_default('form_errors', $entity_type, $entity, $form, $form_state, $options);

  }

}

/**

 * Perform necessary operations on field data submitted by a form.

 *

 * Currently, this accounts for drag-and-drop reordering of

 * field values, and filtering of empty values.

 *

 * @param $entity_type

 *   The type of $entity; e.g. 'node' or 'user'.

 * @param $entity

 *   The entity being submitted. The 'bundle', 'id' and (if applicable)

 *   'revision' keys should be present. The actual field values will be read

 *   from $form_state['values'].

 * @param $form

 *   The form structure where field elements are attached to. This might be a

 *   full form structure, or a sub-element of a larger form.

 * @param $form_state

 *   An associative array containing the current state of the form.

 * @param array $options

 *   An associative array of additional options. See _field_invoke() for

 *   details.

 */

function field_attach_submit($entity_type, $entity, $form, &$form_state, $options = array()) {

  // Validate $options since this is a new parameter added after Drupal 7 was

  // released.

  $options = is_array($options) ? $options : array();

  // Extract field values from submitted values.

  _field_invoke_default('extract_form_values', $entity_type, $entity, $form, $form_state, $options);

  _field_invoke_default('submit', $entity_type, $entity, $form, $form_state, $options);

  // Let other modules act on submitting the entity.

  // Avoid module_invoke_all() to let $form_state be taken by reference.

  foreach (module_implements('field_attach_submit') as $module) {

    $function = $module . '_field_attach_submit';

    $function($entity_type, $entity, $form, $form_state);

  }

}

/**

 * Perform necessary operations just before fields data get saved.

 *

 * We take no specific action here, we just give other

 * modules the opportunity to act.

 *

 * @param $entity_type

 *   The type of $entity; e.g. 'node' or 'user'.

 * @param $entity

 *   The entity with fields to process.

 */

function field_attach_presave($entity_type, $entity) {

  _field_invoke('presave', $entity_type, $entity);

  // Let other modules act on presaving the entity.

  module_invoke_all('field_attach_presave', $entity_type, $entity);

}

/**

 * Save field data for a new entity.

 *

 * The passed-in entity must already contain its id and (if applicable)

 * revision id attributes.

 * Default values (if any) will be saved for fields not present in the

 * $entity.

 *

 * @param $entity_type

 *   The type of $entity; e.g. 'node' or 'user'.

 * @param $entity

 *   The entity with fields to save.

 * @return

 *   Default values (if any) will be added to the $entity parameter for fields

 *   it leaves unspecified.

 */

function field_attach_insert($entity_type, $entity) {

  _field_invoke_default('insert', $entity_type, $entity);

  _field_invoke('insert', $entity_type, $entity);

  list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);

  // Let any module insert field data before the storage engine, accumulating

  // saved fields along the way.

  $skip_fields = array();

  foreach (module_implements('field_storage_pre_insert') as $module) {

    $function = $module . '_field_storage_pre_insert';

    $function($entity_type, $entity, $skip_fields);

  }

  // Collect the storage backends used by the remaining fields in the entities.

  $storages = array();

  foreach (field_info_instances($entity_type, $bundle) as $instance) {

    $field = field_info_field_by_id($instance['field_id']);

    $field_id = $field['id'];

    $field_name = $field['field_name'];

    if (!empty($entity->$field_name)) {

      // Collect the storage backend if the field has not been written yet.

      if (!isset($skip_fields[$field_id])) {

        $storages[$field['storage']['type']][$field_id] = $field_id;

      }

    }

  }

  // Field storage backends save any remaining unsaved fields.

  foreach ($storages as $storage => $fields) {

    $storage_info = field_info_storage_types($storage);

    module_invoke($storage_info['module'], 'field_storage_write', $entity_type, $entity, FIELD_STORAGE_INSERT, $fields);

  }

  // Let other modules act on inserting the entity.

  module_invoke_all('field_attach_insert', $entity_type, $entity);

  $entity_info = entity_get_info($entity_type);

}

/**

 * Save field data for an existing entity.

 *

 * When calling this function outside an entity save operation be sure to

 * clear caches for the entity:

 * @code

 * entity_get_controller($entity_type)->resetCache(array($entity_id))

 * @endcode

 *

 * @param $entity_type

 *   The type of $entity; e.g. 'node' or 'user'.

 * @param $entity

 *   The entity with fields to save.

 */

function field_attach_update($entity_type, $entity) {

  _field_invoke('update', $entity_type, $entity);

  list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);

  // Let any module update field data before the storage engine, accumulating

  // saved fields along the way.

  $skip_fields = array();

  foreach (module_implements('field_storage_pre_update') as $module) {

    $function = $module . '_field_storage_pre_update';

    $function($entity_type, $entity, $skip_fields);

  }

  // Collect the storage backends used by the remaining fields in the entities.

  $storages = array();

  foreach (field_info_instances($entity_type, $bundle) as $instance) {

    $field = field_info_field_by_id($instance['field_id']);

    $field_id = $field['id'];

    $field_name = $field['field_name'];

    // Leave the field untouched if $entity comes with no $field_name property,

    // but empty the field if it comes as a NULL value or an empty array.

    // Function property_exists() is slower, so we catch the more frequent

    // cases where it's an empty array with the faster isset().

    if (isset($entity->$field_name) || property_exists($entity, $field_name)) {

      // Collect the storage backend if the field has not been written yet.

      if (!isset($skip_fields[$field_id])) {

        $storages[$field['storage']['type']][$field_id] = $field_id;

      }

    }

  }

  // Field storage backends save any remaining unsaved fields.

  foreach ($storages as $storage => $fields) {

    $storage_info = field_info_storage_types($storage);

    module_invoke($storage_info['module'], 'field_storage_write', $entity_type, $entity, FIELD_STORAGE_UPDATE, $fields);

  }

  // Let other modules act on updating the entity.

  module_invoke_all('field_attach_update', $entity_type, $entity);

  $entity_info = entity_get_info($entity_type);

  if ($entity_info['field cache']) {

    cache_clear_all("field:$entity_type:$id", 'cache_field');

  }

}

/**

 * Delete field data for an existing entity. This deletes all

 * revisions of field data for the entity.

 *

 * @param $entity_type

 *   The type of $entity; e.g. 'node' or 'user'.

 * @param $entity

 *   The entity whose field data to delete.

 */

function field_attach_delete($entity_type, $entity) {

  _field_invoke('delete', $entity_type, $entity);

  list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);

  // Collect the storage backends used by the fields in the entities.

  $storages = array();

  foreach (field_info_instances($entity_type, $bundle) as $instance) {

    $field = field_info_field_by_id($instance['field_id']);

    $field_id = $field['id'];

    $storages[$field['storage']['type']][$field_id] = $field_id;

  }

  // Field storage backends delete their data.

  foreach ($storages as $storage => $fields) {

    $storage_info = field_info_storage_types($storage);

    module_invoke($storage_info['module'], 'field_storage_delete', $entity_type, $entity, $fields);

  }

  // Let other modules act on deleting the entity.

  module_invoke_all('field_attach_delete', $entity_type, $entity);

  $entity_info = entity_get_info($entity_type);

  if ($entity_info['field cache']) {

    cache_clear_all("field:$entity_type:$id", 'cache_field');

  }

}

/**

 * Delete field data for a single revision of an existing entity. The

 * passed entity must have a revision id attribute.

 *

 * @param $entity_type

 *   The type of $entity; e.g. 'node' or 'user'.

 * @param $entity

 *   The entity with fields to save.

 */

function field_attach_delete_revision($entity_type, $entity) {

  _field_invoke('delete_revision', $entity_type, $entity);

  list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);

  // Collect the storage backends used by the fields in the entities.

  $storages = array();

  foreach (field_info_instances($entity_type, $bundle) as $instance) {

    $field = field_info_field_by_id($instance['field_id']);

    $field_id = $field['id'];

    $storages[$field['storage']['type']][$field_id] = $field_id;

  }

  // Field storage backends delete their data.

  foreach ($storages as $storage => $fields) {

    $storage_info = field_info_storage_types($storage);

    module_invoke($storage_info['module'], 'field_storage_delete_revision', $entity_type, $entity, $fields);

  }

  // Let other modules act on deleting the revision.

  module_invoke_all('field_attach_delete_revision', $entity_type, $entity);

}

/**

 * Prepare field data prior to display.

 *

 * This function lets field types and formatters load additional data

 * needed for display that is not automatically loaded during

 * field_attach_load(). It accepts an array of entities to allow query

 * optimisation when displaying lists of entities.

 *

 * field_attach_prepare_view() and field_attach_view() are two halves

 * of the same operation. It is safe to call

 * field_attach_prepare_view() multiple times on the same entity

 * before calling field_attach_view() on it, but calling any Field

 * API operation on an entity between passing that entity to these two

 * functions may yield incorrect results.

 *

 * @param $entity_type

 *   The type of $entities; e.g. 'node' or 'user'.

 * @param $entities

 *   An array of entities, keyed by entity id.

 * @param $view_mode