Skip to content
Snippets Groups Projects
Select Git revision
  • 62c93ff8d418876d24f5d0031327b7b93cfde23f
  • 11.x default protected
  • 10.6.x protected
  • 10.5.x protected
  • 11.2.x protected
  • 11.1.x protected
  • 10.4.x protected
  • 11.0.x protected
  • 10.3.x protected
  • 7.x protected
  • 10.2.x protected
  • 10.1.x protected
  • 9.5.x protected
  • 10.0.x protected
  • 9.4.x protected
  • 9.3.x protected
  • 9.2.x protected
  • 9.1.x protected
  • 8.9.x protected
  • 9.0.x protected
  • 8.8.x protected
  • 10.5.1 protected
  • 11.2.2 protected
  • 11.2.1 protected
  • 11.2.0 protected
  • 10.5.0 protected
  • 11.2.0-rc2 protected
  • 10.5.0-rc1 protected
  • 11.2.0-rc1 protected
  • 10.4.8 protected
  • 11.1.8 protected
  • 10.5.0-beta1 protected
  • 11.2.0-beta1 protected
  • 11.2.0-alpha1 protected
  • 10.4.7 protected
  • 11.1.7 protected
  • 10.4.6 protected
  • 11.1.6 protected
  • 10.3.14 protected
  • 10.4.5 protected
  • 11.0.13 protected
41 results

field.attach.inc

Blame
  • webchick's avatar
    Issue #1253820 by yched, zserno, tim.plunkett, xjm, effulgentsia, plach: Fixed...
    Angie Byron authored
    Issue #1253820 by yched, zserno, tim.plunkett, xjm, effulgentsia, plach: Fixed It's impossible to submit no value for a field that has a default value.
    62c93ff8
    History
    Code owners
    Assign users and groups as approvers for specific file changes. Learn more.
    field.attach.inc 63.11 KiB
    <?php
    
    /**
     * @file
     * Field attach API, allowing entities (nodes, users, ...) to be 'fieldable'.
     */
    
    use Drupal\field\FieldValidationException;
    use Drupal\Core\Entity\EntityInterface;
    use Drupal\entity\Plugin\Core\Entity\EntityDisplay;
    
    /**
     * @defgroup field_storage Field Storage API
     * @{
     * Implements 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.
     */
    const FIELD_STORAGE_UPDATE = 'update';
    
    /**
     * Argument for an insert operation.
     *
     * This is used in hook_field_storage_write when inserting a new entity.
     */
    const FIELD_STORAGE_INSERT = 'insert';
    
    /**
     * @} End of "defgroup field_storage".
     */
    
    /**
     * @defgroup field_attach Field Attach API
     * @{
     * Operates 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.
     *
     * An entity plugin's annotation is how entity types 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 added to the entity definition with
     * hook_entity_info_alter(). For instance, node_entity_info_alter() 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_alter() defines which
     * property to use. For instance, node_entity_info_alter() 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.
     */
    
    /**
     * Invokes a method on all the fields of a given entity.
     *
     * @todo Remove _field_invoke() and friends when field types and formatters are
     * turned into plugins.
     *
     * @param string $method
     *   The name of the method to invoke.
     * @param callable $target_function
     *   A function that receives an $instance object and returns the object on
     *   which the method should be invoked.
     * @param Drupal\Core\Entity\EntityInterface $entity
     *   The fully formed $entity_type entity.
     * @param mixed $a
     *   (optional) A parameter for the invoked method. Defaults to NULL.
     * @param mixed $b
     *   (optional) A parameter for the invoked method. Defaults to NULL.
     * @param array $options
     *   (optional) 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.
     *   - 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.
     *   - langcode: 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.
     *
     * @return array
     *   An array of returned values.
     */
    function field_invoke_method($method, $target_function, EntityInterface $entity, &$a = NULL, &$b = NULL, array $options = array()) {
      // Merge default options.
      $default_options = array(
        'deleted' => FALSE,
        'langcode' => NULL,
      );
      $options += $default_options;
    
      $entity_type = $entity->entityType();
      // Determine the list of instances to iterate on.
      $instances = _field_invoke_get_instances($entity_type, $entity->bundle(), $options);
    
      // Iterate through the instances and collect results.
      $return = array();
      foreach ($instances as $instance) {
    
        // Let the function determine the target object on which the method should be
        // called.
        $target = call_user_func($target_function, $instance);
    
        if (method_exists($target, $method)) {
          $field = field_info_field_by_id($instance['field_id']);
          $field_name = $field['field_name'];
    
          // Determine the list of languages to iterate on.
          $available_langcodes = field_available_languages($entity_type, $field);
          $langcodes = _field_language_suggestion($available_langcodes, $options['langcode'], $field_name);
    
          foreach ($langcodes as $langcode) {
            $items = isset($entity->{$field_name}[$langcode]) ? $entity->{$field_name}[$langcode] : array();
    
            $result = $target->$method($entity, $langcode, $items, $a, $b);
    
            if (isset($result)) {
              // For methods with array results, we merge results together.
              // For methods 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;
    }
    
    /**
     * Invokes a method across fields on multiple entities.
     *
     * @param string $method
     *   The name of the method to invoke.
     * @param callable $target_function
     *   A function that receives an $instance object and returns the object on
     *   which the method should be invoked.
     * @param array $entities
     *   An array of entities, keyed by entity ID.
     * @param mixed $a
     *   (optional) A parameter for the invoked method. Defaults to NULL.
     * @param mixed $b
     *   (optional) A parameter for the invoked method. Defaults to NULL.
     * @param $options
     *   (optional) 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.
     *   - 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.
     *   - langcode: 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.
     *
     * @return array
     *   An array of returned values keyed by entity ID.
     *
     * @see field_invoke_method()
     */
    function field_invoke_method_multiple($method, $target_function, array $entities, &$a = NULL, &$b = NULL, array $options = array()) {
      // Merge default options.
      $default_options = array(
        'deleted' => FALSE,
        'langcode' => NULL,
      );
      $options += $default_options;
    
      $instances = array();
      $grouped_entities = array();
      $grouped_items = array();
      $grouped_targets = array();
      $return = array();
    
      // Go through the entities and collect the instances on which the method
      // should be called.
      foreach ($entities as $entity) {
        $id = $entity->id();
        $entity_type = $entity->entityType();
    
        // Determine the list of instances to iterate on.
        $entity_instances = _field_invoke_get_instances($entity_type, $entity->bundle(), $options);
    
        foreach ($entity_instances as $instance) {
          $instance_id = $instance['id'];
          $field_name = $instance['field_name'];
    
          // Let the closure determine the target object on which the method should
          // be called.
          if (empty($grouped_targets[$instance_id])) {
            $grouped_targets[$instance_id] = call_user_func($target_function, $instance);
          }
    
          if (method_exists($grouped_targets[$instance_id], $method)) {
            // Add the instance to the list of instances to invoke the hook on.
            if (!isset($instances[$instance_id])) {
              $instances[$instance_id] = $instance;
            }
    
            // Unless a language code suggestion is provided we iterate on all the
            // available language codes.
            $field = field_info_field_by_id($instance['field_id']);
            $available_langcodes = field_available_languages($entity_type, $field);
            $langcode = !empty($options['langcode'][$id]) ? $options['langcode'][$id] : $options['langcode'];
            $langcodes = _field_language_suggestion($available_langcodes, $langcode, $field_name);
            foreach ($langcodes as $langcode) {
              // Group the entities and items corresponding to the current field.
              $grouped_entities[$instance_id][$langcode][$id] = $entities[$id];
              $grouped_items[$instance_id][$langcode][$id] = isset($entity->{$field_name}[$langcode]) ? $entity->{$field_name}[$langcode] : array();
            }
          }
        }
        // Initialize the return value for each entity.
        $return[$id] = array();
      }
    
      // For each instance, invoke the method and collect results.
      foreach ($instances as $instance_id => $instance) {
        $field_name = $instance['field_name'];
    
        // Iterate over all the field translations.
        foreach ($grouped_items[$instance_id] as $langcode => &$items) {
          $entities = $grouped_entities[$instance_id][$langcode];
          $results = $grouped_targets[$instance_id]->$method($entities, $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[$instance_id] as $langcode => $entities) {
          foreach ($entities as $id => $entity) {
            if ($grouped_items[$instance_id][$langcode][$id] !== array() || isset($entity->{$field_name}[$langcode])) {
              $entity->{$field_name}[$langcode] = $grouped_items[$instance_id][$langcode][$id];
            }
          }
        }
      }
    
      return $return;
    }
    
    /**
     * Invoke a field hook.
     *
     * @param $op
     *   Possible operations include:
     *   - form
     *   - validate
     *   - presave
     *   - insert
     *   - update
     *   - delete
     *   - delete revision
     *   - view
     *   - prepare translation
     * @param \Drupal\Core\Entity\EntityInterface $entity
     *   The entity object.
     * @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.
     *  - 'langcode': 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, EntityInterface $entity, &$a = NULL, &$b = NULL, $options = array()) {
      // Merge default options.
      $default_options = array(
        'default' => FALSE,
        'deleted' => FALSE,
        'langcode' => NULL,
      );
      $options += $default_options;
    
      // Determine the list of instances to iterate on.
      $instances = _field_invoke_get_instances($entity->entityType(), $entity->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_langcodes = field_available_languages($entity->entityType(), $field);
          $langcodes = _field_language_suggestion($available_langcodes, $options['langcode'], $field_name);
    
          foreach ($langcodes as $langcode) {
            $items = isset($entity->{$field_name}[$langcode]) ? $entity->{$field_name}[$langcode] : array();
            $result = $function($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;
    }
    
    /**
     * Invokes 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 entities in $entities; 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.
     *   - langcode: 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,
        'langcode' => 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.
        $instances = _field_invoke_get_instances($entity_type, $entity->bundle(), $options);
        $id = $entity->id();
    
        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 code suggestion is provided we iterate on all the
            // available language codes.
            $available_langcodes = field_available_languages($entity_type, $field);
            $langcode = !empty($options['langcode'][$id]) ? $options['langcode'][$id] : $options['langcode'];
            $langcodes = _field_language_suggestion($available_langcodes, $langcode, $field_name);
            foreach ($langcodes 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, EntityInterface $entity, &$a = NULL, &$b = NULL, $options = array()) {
      $options['default'] = TRUE;
      return _field_invoke($op, $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]().
     *
     * @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 entities in $entities; 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.
     *
     * @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);
    }
    
    /**
     * Retrieves a list of instances to operate on.
     *
     * Helper for _field_invoke().
     *
     * @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;
    }
    
    /**
     * Defines a 'target function' for field_invoke_method().
     *
     * Used to invoke methods on an instance's widget.
     *
     * @return callable $target_function
     *   A 'target function' for field_invoke_method().
     */
    function _field_invoke_widget_target() {
      return function ($instance) {
        return $instance->getWidget();
      };
    }
    
    /**
     * Adds 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 \Drupal\Core\Entity\EntityInterface $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_method() for
     *   details.
     *
     * @see field_form_get_state()
     * @see field_form_set_state()
     */
    function field_attach_form(EntityInterface $entity, &$form, &$form_state, $langcode = NULL, array $options = array()) {
      // Set #parents to 'top-level' by default.
      $form += array('#parents' => array());
    
      // If no language is provided use the default site language.
      $options['langcode'] = field_valid_language($langcode);
      $form += (array) field_invoke_method('form', _field_invoke_widget_target(), $entity, $form, $form_state, $options);
    
      // Add custom weight handling.
      $form['#pre_render'][] = '_field_extra_fields_pre_render';
      $form['#entity_type'] = $entity->entityType();
      $form['#bundle'] = $entity->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, $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 entities in $entities; 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('field')->getMultiple($cids);
        // 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) {
          $instances = _field_invoke_get_instances($entity_type, $entity->bundle(), $options);
          $id = $entity->id();
          $vid = $entity->getRevisionId();
          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();
            $instances = field_info_instances($entity_type, $entity->bundle());
            foreach ($instances as $instance) {
              $data[$instance['field_name']] = $queried_entities[$id]->{$instance['field_name']};
            }
            $cid = "field:$entity_type:$id";
            cache('field')->set($cid, $data);
          }
        }
      }
    }
    
    /**
     * Loads 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 entities in $entities; 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);
    }
    
    /**
     * Performs 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 \Drupal\Core\Entity\EntityInterface $entity
     *   The entity with fields to validate.
     * @throws Drupal\field\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_method() for
     *   details.
     */
    function field_attach_validate(EntityInterface $entity, array $options = array()) {
      $errors = array();
      // Check generic, field-type-agnostic errors first.
      $null = NULL;
      _field_invoke_default('validate', $entity, $errors, $null, $options);
      // Check field-type specific errors.
      _field_invoke('validate', $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, $errors);
      }
    
      if ($errors) {
        throw new FieldValidationException($errors);
      }
    }
    
    /**
     * Performs field validation against form-submitted field values.
     *
     * There are two levels of validation for fields in forms: widget validation and
     * 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 \Drupal\Core\Entity\EntityInterface $entity
     *   The entity being submitted. 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_method() for
     *   details.
     */
    function field_attach_form_validate(EntityInterface $entity, $form, &$form_state, array $options = array()) {
      // Perform field_level validation.
      try {
        field_attach_validate($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_method('flagErrors', _field_invoke_widget_target(), $entity, $form, $form_state, $options);
      }
    }
    
    /**
     * Performs 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 \Drupal\Core\Entity\EntityInterface $entity
     *   The entity being submitted. 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_method() for
     *   details.
     */
    function field_attach_submit(EntityInterface $entity, $form, &$form_state, array $options = array()) {
      // Extract field values from submitted values.
      field_invoke_method('submit', _field_invoke_widget_target(), $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, $form, $form_state);
      }
    }
    
    /**
     * Performs necessary operations just before fields data get saved.
     *
     * We take no specific action here, we just give other modules the opportunity
     * to act.
     *
     * @param \Drupal\Core\Entity\EntityInterface $entity
     *   The entity with fields to process.
     */
    function field_attach_presave($entity) {
      _field_invoke('presave', $entity);
    
      // Let other modules act on presaving the entity.
      module_invoke_all('field_attach_presave', $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 \Drupal\Core\Entity\EntityInterface $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(EntityInterface $entity) {
      _field_invoke('insert', $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, $skip_fields);
      }
    
      // Collect the storage backends used by the remaining fields in the entities.
      $storages = array();
      foreach (field_info_instances($entity->entityType(), $entity->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, FIELD_STORAGE_INSERT, $fields);
      }
    
      // Let other modules act on inserting the entity.
      module_invoke_all('field_attach_insert', $entity);
    }
    
    /**
     * Saves field data for an existing entity.
     *
     * @param \Drupal\Core\Entity\EntityInterface $entity
     *   The entity with fields to save.
     */
    function field_attach_update(EntityInterface $entity) {
      _field_invoke('update', $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, $skip_fields);
      }
    
      // Collect the storage backends used by the remaining fields in the entities.
      $storages = array();
      foreach (field_info_instances($entity->entityType(), $entity->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, FIELD_STORAGE_UPDATE, $fields);
      }
    
      // Let other modules act on updating the entity.
      module_invoke_all('field_attach_update', $entity);
    
      $entity_info = $entity->entityInfo();
      if ($entity_info['field_cache']) {
        cache('field')->delete('field:' . $entity->entityType() . ':' . $entity->id());
      }
    }
    
    /**
     * Deletes field data for an existing entity. This deletes all revisions of
     * field data for the entity.
     *
     * @param \Drupal\Core\Entity\EntityInterface $entity
     *   The entity whose field data to delete.
     */
    function field_attach_delete(EntityInterface $entity) {
      _field_invoke('delete', $entity);
    
      // Collect the storage backends used by the fields in the entities.
      $storages = array();
      foreach (field_info_instances($entity->entityType(), $entity->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, $fields);
      }
    
      // Let other modules act on deleting the entity.
      module_invoke_all('field_attach_delete', $entity);
    
      $entity_info = $entity->entityInfo();
      if ($entity_info['field_cache']) {
        cache('field')->delete('field:' . $entity->entityType() . ':' . $entity->id());
      }
    }
    
    /**
     * Delete field data for a single revision of an existing entity. The passed
     * entity must have a revision ID attribute.
     *
     * @param \Drupal\Core\Entity\EntityInterface $entity
     *   The entity with fields to save.
     */
    function field_attach_delete_revision(EntityInterface $entity) {
      _field_invoke('delete_revision', $entity);
    
      // Collect the storage backends used by the fields in the entities.
      $storages = array();
      foreach (field_info_instances($entity->entityType(), $entity->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, $fields);
      }
    
      // Let other modules act on deleting the revision.
      module_invoke_all('field_attach_delete_revision', $entity);
    }
    
    /**
     * Prepares 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 optimization 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 in $entities; e.g. 'node' or 'user'.
     * @param array $entities
     *   An array of entities, keyed by entity ID.
     * @param array $displays
     *   An array of entity display objects, keyed by bundle name.
     * @param $langcode
     *   (Optional) The language the field values are to be shown in. If no language
     *   is provided the current language is used.
     * @param array $options
     *   An associative array of additional options. See field_invoke_method() for
     *   details.
     */
    function field_attach_prepare_view($entity_type, array $entities, array $displays, $langcode = NULL, array $options = array()) {
      $options['langcode'] = array();
    
      // To ensure hooks are only run once per entity, only process items without
      // the _field_view_prepared flag.
      // @todo: resolve this more generally for both entity and field level hooks.
      $prepare = array();
      foreach ($entities as $id => $entity) {
        if (empty($entity->_field_view_prepared)) {
          // Add this entity to the items to be prepared.
          $prepare[$id] = $entity;
    
          // Enable BC if necessary.
          $entity = $entity->getBCEntity();
    
          // Determine the actual language code to display for each field, given the
          // language codes available in the field data.
          $options['langcode'][$id] = field_language($entity, NULL, $langcode);
    
          // Mark this item as prepared.
          $entity->_field_view_prepared = TRUE;
        }
      }
    
      $null = NULL;
      // First let the field types do their preparation.
      _field_invoke_multiple('prepare_view', $entity_type, $prepare, $null, $null, $options);
      // Then let the formatters do their own specific massaging. For each
      // instance, call the prepareView() method on the formatter object handed by
      // the entity display.
      $target_function = function ($instance) use ($displays) {
        if (isset($displays[$instance['bundle']])) {
          return $displays[$instance['bundle']]->getFormatter($instance['field_name']);
        }
      };
      field_invoke_method_multiple('prepareView', $target_function, $prepare, $null, $null, $options);
    }
    
    /**
     * Returns a renderable array for the fields on an entity.
     *
     * Each field is displayed according to the display options specified in the
     * instance definition for the given view mode.
     *
     * 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.
     *
     * Sample structure:
     * @code
     * array(
     *   'field_foo' => array(
     *     '#theme' => 'field',
     *     '#title' => the label of the field instance,
     *     '#label_display' => the label display mode,
     *     '#object' => the fieldable entity being displayed,
     *     '#entity_type' => the type of the entity being displayed,
     *     '#language' => the language of the field values being displayed,
     *     '#view_mode' => the view mode,
     *     '#field_name' => the name of the field,
     *     '#field_type' => the type of the field,
     *     '#formatter' => the name of the formatter,
     *     '#items' => the field values being displayed,
     *     // The element's children are the formatted values returned by
     *     // hook_field_formatter_view().
     *   ),
     * );
     * @endcode
     *
     * @param Drupal\Core\Entity\EntityInterface $entity
     *   The entity with fields to render.
     * @param \Drupal\entity\Plugin\Core\Entity\EntityDisplay $display
     *   The entity display object.
     * @param $langcode
     *   The language the field values are to be shown in. If no language is
     *   provided the current language is used.
     * @param array $options
     *   An associative array of additional options. See field_invoke_method() for
     *   details.
     *
     * @return array
     *   A renderable array for the field values.
     */
    function field_attach_view(EntityInterface $entity, EntityDisplay $display, $langcode = NULL, array $options = array()) {
      // Enable BC if necessary.
      $entity = $entity->getBCEntity();
      // Determine the actual language code to display for each field, given the
      // language codes available in the field data.
      $options['langcode'] = field_language($entity, NULL, $langcode);
    
      // For each instance, call the view() method on the formatter object handed
      // by the entity display.
      $target_function = function ($instance) use ($display) {
        return $display->getFormatter($instance['field_name']);
      };
      $null = NULL;
      $output = field_invoke_method('view', $target_function, $entity, $null, $null, $options);
      // Remove the BC layer now.
      $entity = $entity->getOriginalEntity();
    
      // Let other modules alter the renderable array.
      $view_mode = $display->originalViewMode;
      $context = array(
        'entity' => $entity,
        'view_mode' => $view_mode,
        'display_options' => $view_mode,
        'langcode' => $langcode,
      );
      drupal_alter('field_attach_view', $output, $context);
    
      // Reset the _field_view_prepared flag set in field_attach_prepare_view(),
      // in case the same entity is displayed with different settings later in
      // the request.
      unset($entity->_field_view_prepared);
    
      return $output;
    }
    
    /**
     * Populates the template variables with the available field values.
     *
     * The $variables array will be populated with all the field instance values
     * associated with the given entity type, keyed by field name; in case of
     * translatable fields the language currently chosen for display will be
     * selected.
     *
     * @param \Drupal\Core\Entity\EntityInterface $entity
     *   The entity with fields to render.
     * @param $element
     *   The structured array containing the values ready for rendering.
     * @param $variables
     *   The variables array is passed by reference and will be populated with field
     *   values.
     */
    function field_attach_preprocess(EntityInterface $entity, $element, &$variables) {
      // Enable BC if necessary.
      $entity = $entity->getBCEntity();
      foreach (field_info_instances($entity->entityType(), $entity->bundle()) as $instance) {
        $field_name = $instance['field_name'];
        if (isset($element[$field_name]['#language'])) {
          $langcode = $element[$field_name]['#language'];
          $variables[$field_name] = isset($entity->{$field_name}[$langcode]) ? $entity->{$field_name}[$langcode] : NULL;
        }
      }
    
      // Let other modules make changes to the $variables array.
      $context = array(
        'entity' => $entity,
        'element' => $element,
      );
      drupal_alter('field_attach_preprocess', $variables, $context);
    }
    
    /**
     * Prepares an entity for translation.
     *
     * This function is used to fill in the form default values for Field API fields
     * while performing entity translation. By default it copies all the source
     * values in the given source language to the new entity and assigns them the
     * target language.
     *
     * This is used as part of the 'per entity' translation pattern, which is
     * implemented only for nodes by translation.module. Other entity types may be
     * supported through contributed modules.
     *
     * @param \Drupal\Core\Entity\EntityInterface $entity
     *   The entity to be prepared for translation.
     * @param $langcode
     *   The language the entity has to be translated in.
     * @param $source_entity
     *   The source entity holding the field values to be translated.
     * @param $source_langcode
     *   The source language from which translate.
     */
    function field_attach_prepare_translation(EntityInterface $entity, $langcode, EntityInterface $source_entity, $source_langcode) {
      $options = array('langcode' => $langcode);
      // Copy source field values into the entity to be prepared.
      _field_invoke_default('prepare_translation', $entity, $source_entity, $source_langcode, $options);
      // Let field types handle their own advanced translation pattern if needed.
      _field_invoke('prepare_translation', $entity, $source_entity, $source_langcode, $options);
      // Let other modules alter the entity translation.
      $context = array(
        'langcode' => $langcode,
        'source_entity' => $source_entity,
        'source_langcode' => $source_langcode,
      );
      drupal_alter('field_attach_prepare_translation', $entity, $context);
    }
    
    /**
     * Notifies field.module that a new bundle was created.
     *
     * The default SQL-based storage doesn't need to do anything about it, but
     * others might.
     *
     * @param $entity_type
     *   The entity type to which the bundle is bound.
     * @param $bundle
     *   The name of the newly created bundle.
     */
    function field_attach_create_bundle($entity_type, $bundle) {
      // Clear the cache.
      field_cache_clear();
    
      // Let other modules act on creating the bundle.
      module_invoke_all('field_attach_create_bundle', $entity_type, $bundle);
    }
    
    /**
     * Notifies field.module that a bundle was renamed.
     *
     * @param $entity_type
     *   The entity type to which the bundle is bound.
     * @param $bundle_old
     *   The previous name of the bundle.
     * @param $bundle_new
     *   The new name of the bundle.
     */
    function field_attach_rename_bundle($entity_type, $bundle_old, $bundle_new) {
      db_update('field_config_instance')
        ->fields(array('bundle' => $bundle_new))
        ->condition('entity_type', $entity_type)
        ->condition('bundle', $bundle_old)
        ->execute();
    
      // Clear the cache.
      field_cache_clear();
      entity_info_cache_clear();
    
      // Update bundle settings.
      $settings = variable_get('field_bundle_settings_' . $entity_type . '__' . $bundle_old, array());
      variable_set('field_bundle_settings_' . $entity_type . '__' . $bundle_new, $settings);
      variable_del('field_bundle_settings_' . $entity_type . '__' . $bundle_old);
    
      // Let other modules act on renaming the bundle.
      module_invoke_all('field_attach_rename_bundle', $entity_type, $bundle_old, $bundle_new);
    }
    
    /**
     * Notifies field.module the a bundle was deleted.
     *
     * This deletes the data for the field instances as well as the field instances
     * themselves. This function actually just marks the data and field instances as
     * deleted, leaving the garbage collection for a separate process, because it is
     * not always possible to delete this much data in a single page request
     * (particularly since for some field types, the deletion is more than just a
     * simple DELETE query).
     *
     * @param $entity_type
     *   The entity type to which the bundle is bound.
     * @param $bundle
     *   The bundle to delete.
     */
    function field_attach_delete_bundle($entity_type, $bundle) {
      // First, delete the instances themselves. field_read_instances() must be
      // used here since field_info_instances() does not return instances for
      // disabled entity types or bundles.
      $instances = field_read_instances(array('entity_type' => $entity_type, 'bundle' => $bundle), array('include_inactive' => 1));
      foreach ($instances as $instance) {
        field_delete_instance($instance);
      }
    
      // Clear the cache.
      field_cache_clear();
    
      // Clear bundle display settings.
      variable_del('field_bundle_settings_' . $entity_type . '__' . $bundle);
    
      // Let other modules act on deleting the bundle.
      module_invoke_all('field_attach_delete_bundle', $entity_type, $bundle, $instances);
    }
    
    
    /**
     * @} End of "defgroup field_attach".
     */