1 <?php

     2 

     3 /**

     4  * @file

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

     6  */

     7 

     8 /**

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

    10  */

    11 class FieldValidationException extends FieldException {

    12   var $errors;

    13 

    14  /**

    15   * Constructor for FieldValidationException.

    16   *

    17   * @param $errors

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

    19   *   delta that contains two keys:

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

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

    22   *     how to report the error.

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

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

    25   */

    26   function __construct($errors) {

    27     $this->errors = $errors;

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

    29   }

    30 }

    31 

    32 /**

    33  * @defgroup field_storage Field Storage API

    34  * @{

    35  * Implement a storage engine for Field API data.

    36  *

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

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

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

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

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

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

    43  * such as a cloud-based database.

    44  *

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

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

    47  *

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

    49  * the Field API.

    50  */

    51 

    52 /**

    53  * Argument for an update operation.

    54  *

    55  * This is used in hook_field_storage_write when updating an

    56  * existing entity.

    57  */

    58 define('FIELD_STORAGE_UPDATE', 'update');

    59 

    60 /**

    61  * Argument for an insert operation.

    62  *

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

    64  */

    65 define('FIELD_STORAGE_INSERT', 'insert');

    66 

    67 /**

    68  * @} End of "defgroup field_storage".

    69  */

    70 

    71 /**

    72  * @defgroup field_attach Field Attach API

    73  * @{

    74  * Operate on Field API data attached to Drupal entities.

    75  *

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

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

    78  * to individual entities.

    79  *

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

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

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

    83  * itself.

    84  *

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

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

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

    88  *

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

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

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

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

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

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

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

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

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

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

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

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

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

   102  *

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

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

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

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

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

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

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

   110  *

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

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

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

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

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

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

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

   118  * operate on specified fields.

   119  *

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

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

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

   123  *

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

   125  * the structure of field objects.

   126  *

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

   128  * the Field API.

   129  */

   130 

   131 /**

   132  * Invoke a field hook.

   133  *

   134  * @param $op

   135  *   Possible operations include:

   136  *   - form

   137  *   - validate

   138  *   - presave

   139  *   - insert

   140  *   - update

   141  *   - delete

   142  *   - delete revision

   143  *   - view

   144  *   - prepare translation

   145  * @param $entity_type

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

   147  * @param $entity

   148  *   The fully formed $entity_type entity.

   149  * @param $a

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

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

   152  *   - Otherwise NULL.

   153  * @param $b

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

   155  *   - Otherwise NULL.

   156  * @param $options

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

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

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

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

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

   162  *    instead.

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

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

   165  *    in the entity's' bundles.

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

   167  *    the operation should be invoked.

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

   169  *      will be invoked (hook_field_[op])

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

   171  *      will be invoked (field_default_[op])

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

   173  *    _field_invoke_default() instead.

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

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

   176  *    non-deleted fields are operated on.

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

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

   179  *    languages to act on.

   180  */

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

   182   // Merge default options.

   183   $default_options = array(

   184     'default' => FALSE,

   185     'deleted' => FALSE,

   186     'language' => NULL,

   187   );

   188   $options += $default_options;

   189 

   190   // Determine the list of instances to iterate on.

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

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

   193 

   194   // Iterate through the instances and collect results.

   195   $return = array();

   196   foreach ($instances as $instance) {

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

   198     // field_info_field_by_id().

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

   200     $field_name = $field['field_name'];

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

   202     if (function_exists($function)) {

   203       // Determine the list of languages to iterate on.

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

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

   206 

   207       foreach ($languages as $langcode) {

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

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

   210         if (isset($result)) {

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

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

   213           if (is_array($result)) {

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

   215           }

   216           else {

   217             $return[] = $result;

   218           }

   219         }

   220 

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

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

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

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

   225         }

   226       }

   227     }

   228   }

   229 

   230   return $return;

   231 }

   232 

   233 /**

   234  * Invoke a field hook across fields on multiple entities.

   235  *

   236  * @param $op

   237  *   Possible operations include:

   238  *   - load

   239  *   - prepare_view

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

   241  *   instead.

   242  * @param $entity_type

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

   244  * @param $entities

   245  *   An array of entities, keyed by entity id.

   246  * @param $a

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

   248  *   - Otherwise NULL.

   249  * @param $b

   250  *   Currently always NULL.

   251  * @param $options

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

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

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

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

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

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

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

   259  *    in the entity's' bundles.

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

   261  *    the operation should be invoked.

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

   263  *      will be invoked (hook_field_[op])

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

   265  *      will be invoked (field_default_[op])

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

   267  *    _field_invoke_multiple_default() instead.

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

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

   270  *    non-deleted fields are operated on.

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

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

   273  *    value the available languages to act on.

   274  *

   275  * @return

   276  *   An array of returned values keyed by entity id.

   277  */

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

   279   // Merge default options.

   280   $default_options = array(

   281     'default' => FALSE,

   282     'deleted' => FALSE,

   283     'language' => NULL,

   284   );

   285   $options += $default_options;

   286 

   287   $fields = array();

   288   $grouped_instances = array();

   289   $grouped_entities = array();

   290   $grouped_items = array();

   291   $return = array();

   292 

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

   294   // invoked.

   295   //

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

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

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

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

   300   // $entity->$field_name property.

   301   foreach ($entities as $entity) {

   302     // Determine the list of instances to iterate on.

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

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

   305 

   306     foreach ($instances as $instance) {

   307       $field_id = $instance['field_id'];

   308       $field_name = $instance['field_name'];

   309       $field = field_info_field_by_id($field_id);

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

   311       if (function_exists($function)) {

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

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

   314           $fields[$field_id] = $field;

   315         }

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

   317         // by hook implementations.

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

   319         // available languages.

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

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

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

   323         foreach ($languages as $langcode) {

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

   325           // Group the instances and entities corresponding to the current

   326           // field.

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

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

   329         }

   330       }

   331     }

   332     // Initialize the return value for each entity.

   333     $return[$id] = array();

   334   }

   335 

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

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

   338     $field_name = $field['field_name'];

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

   340     // Iterate over all the field translations.

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

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

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

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

   345       if (isset($results)) {

   346         // Collect results by entity.

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

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

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

   350           if (is_array($result)) {

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

   352           }

   353           else {

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

   355           }

   356         }

   357       }

   358     }

   359 

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

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

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

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

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

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

   366         }

   367       }

   368     }

   369   }

   370 

   371   return $return;

   372 }

   373 

   374 /**

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

   376  *

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

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

   379  * hook_field_[op]().

   380  *

   381  * @see _field_invoke()

   382  */

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

   384   $options['default'] = TRUE;

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

   386 }

   387 

   388 /**

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

   390  *

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

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

   393  * hook_field_[op]().

   394  *

   395  * @see _field_invoke_multiple()

   396  */

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

   398   $options['default'] = TRUE;

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

   400 }

   401 

   402 /**

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

   404  *

   405  * @param $entity_type

   406  *   The entity type.

   407  * @param $bundle

   408  *   The bundle name.

   409  * @param $options

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

   411  *   following keys are considered :

   412  *   - deleted

   413  *   - field_name

   414  *   - field_id

   415  *   See _field_invoke() for details.

   416  *

   417  * @return

   418  *   The array of selected instance definitions.

   419  */

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

   421   if ($options['deleted']) {

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

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

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

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

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

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

   428       // option.

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

   430     }

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

   432   }

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

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

   435     // filtering.

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

   437   }

   438   else {

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

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

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

   442       // find the right one.

   443       foreach ($instances as $instance) {

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

   445           $instances = array($instance);

   446           break;

   447         }

   448       }

   449     }

   450   }

   451 

   452   return $instances;

   453 }

   454 

   455 /**

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

   457  *

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

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

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

   461  *

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

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

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

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

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

   467  *

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

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

   470  * element.

   471  *

   472  * Sample resulting structure in $form:

   473  * @code

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

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

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

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

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

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

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

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

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

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

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

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

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

   487  *   'field_foo' => array(

   488  *     '#tree' => TRUE,

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

   490  *     '#language' => $langcode,

   491  *     $langcode => array(

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

   493  *       '#language' => $langcode,

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

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

   496  *          field_attach_form(),

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

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

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

   500  *

   501  *       // Only for 'single' widgets:

   502  *       '#theme' => 'field_multiple_value_form',

   503  *       '#cardinality' => The field cardinality,

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

   505  *       0 => array(

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

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

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

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

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

   511  *            field_attach_form(),

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

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

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

   515  *         '#delta' => 0,

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

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

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

   519  *         ...

   520  *       ),

   521  *       1 => array(

   522  *         ...

   523  *       ),

   524  *

   525  *       // Only for multiple widgets:

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

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

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

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

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

   531  *       ...

   532  *     ),

   533  *     ...

   534  *   ),

   535  * )

   536  * @endcode

   537  *

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

   539  * accessed by field_form_get_state() and field_form_set_state().

   540  *

   541  * @param $entity_type

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

   543  * @param $entity

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

   545  *   default form values.

   546  * @param $form

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

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

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

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

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

   552  * @param $form_state

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

   554  * @param $langcode

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

   556  *   is provided the default site language will be used.

   557  * @param array $options

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

   559  *   details.

   560  *

   561  * @see field_form_get_state()

   562  * @see field_form_set_state()

   563  */

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

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

   566   // released.

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

   568 

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

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

   571 

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

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

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

   575 

   576   // Add custom weight handling.

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

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

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

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

   581 

   582   // Let other modules make changes to the form.

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

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

   585     $function = $module . '_field_attach_form';

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

   587   }

   588 }

   589 

   590 /**

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

   592  *

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

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

   595  *

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

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

   598  * entity type module.

   599  *

   600  * @param $entity_type

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

   602  * @param $entities

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

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

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

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

   607  * @param $age

   608  *   FIELD_LOAD_CURRENT to load the most recent revision for all

   609  *   fields, or FIELD_LOAD_REVISION to load the version indicated by

   610  *   each entity. Defaults to FIELD_LOAD_CURRENT; use

   611  *   field_attach_load_revision() instead of passing FIELD_LOAD_REVISION.

   612  * @param $options

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

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

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

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

   617  *     from a cache.

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

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

   620  *     non-deleted fields are operated on.

   621  */

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

   623   $load_current = $age == FIELD_LOAD_CURRENT;

   624 

   625   // Merge default options.

   626   $default_options = array(

   627     'deleted' => FALSE,

   628   );

   629   $options += $default_options;

   630 

   631   $info = entity_get_info($entity_type);

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

   633   // types can be cached.

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

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

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

   637 

   638   if (empty($entities)) {

   639     return;

   640   }

   641 

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

   643   // will be removed from the list.

   644   $queried_entities = $entities;

   645 

   646   // Fetch available entities from cache, if applicable.

   647   if ($cache_read) {

   648     // Build the list of cache entries to retrieve.

   649     $cids = array();

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

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

   652     }

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

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

   655     // the list of entities to query.

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

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

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

   659         unset($queried_entities[$id]);

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

   661           $entity->$field_name = $values;

   662         }

   663       }

   664     }

   665   }

   666 

   667   // Fetch other entities from their storage location.

   668   if ($queried_entities) {

   669     // The invoke order is:

   670     // - hook_field_storage_pre_load()

   671     // - storage backend's hook_field_storage_load()

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

   673     // - hook_field_attach_load()

   674 

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

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

   677     $skip_fields = array();

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

   679       $function = $module . '_field_storage_pre_load';

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

   681     }

   682 

   683     $instances = array();

   684 

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

   686     $storages = array();

   687     foreach ($queried_entities as $entity) {

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

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

   690 

   691       foreach ($instances as $instance) {

   692         $field_name = $instance['field_name'];

   693         $field_id = $instance['field_id'];

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

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

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

   697         }

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

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

   700           $field = field_info_field_by_id($field_id);

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

   702         }

   703       }

   704     }

   705 

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

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

   708       $storage_info = field_info_storage_types($storage);

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

   710     }

   711 

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

   713     $null = NULL;

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

   715 

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

   717     // entity.

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

   719 

   720     // Build cache data.

   721     if ($cache_write) {

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

   723         $data = array();

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

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

   726         foreach ($instances as $instance) {

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

   728         }

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

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

   731       }

   732     }

   733   }

   734 }

   735 

   736 /**

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

   738  *

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

   740  * be done by separate calls to the function.

   741  *

   742  * field_attach_load_revision() is automatically called by the default entity

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

   744  * called by the entity type module.

   745  *

   746  * @param $entity_type

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

   748  * @param $entities

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

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

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

   752  *   entity objects of the $entities array.

   753  * @param $options

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

   755  *   details.

   756  */

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

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

   759 }

   760 

   761 /**

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

   763  *

   764  * This function does not perform field widget validation on form

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

   766  * operations. Use field_attach_form_validate() to validate form

   767  * submissions.

   768  *

   769  * @param $entity_type

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

   771  * @param $entity

   772  *   The entity with fields to validate.

   773  * @throws FieldValidationException

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

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

   776  *   language and delta.

   777  * @param array $options

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

   779  *   details.

   780  */

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

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

   783   // released.

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

   785 

   786   $errors = array();

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

   788   $null = NULL;

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

   790   // Check field-type specific errors.

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

   792 

   793   // Let other modules validate the entity.

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

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

   796     $function = $module . '_field_attach_validate';

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

   798   }

   799 

   800   if ($errors) {

   801     throw new FieldValidationException($errors);

   802   }

   803 }

   804 

   805 /**

   806  * Perform field validation against form-submitted field values.

   807  *

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

   809  * validation, and field validation.

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

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

   812  *   #element_validate property during normal form validation.

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

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

   815  *   field type's implementation of hook_field_validate().

   816  *

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

   818  * submission. It converts field validation errors into form errors

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

   820  * this function during their own form validation function.

   821  *

   822  * @param $entity_type

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

   824  * @param $entity

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

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

   827  *   from $form_state['values'].

   828  * @param $form

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

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

   831  * @param $form_state

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

   833  * @param array $options

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

   835  *   details.

   836  */

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

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

   839   // released.

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

   841 

   842   // Extract field values from submitted values.

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

   844 

   845   // Perform field_level validation.

   846   try {

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

   848   }

   849   catch (FieldValidationException $e) {

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

   851     // flagging.

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

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

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

   855         $field_state['errors'] = $errors;

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

   857       }

   858     }

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

   860   }

   861 }

   862 

   863 /**

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

   865  *

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

   867  * field values, and filtering of empty values.

   868  *

   869  * @param $entity_type

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

   871  * @param $entity

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

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

   874  *   from $form_state['values'].

   875  * @param $form

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

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

   878  * @param $form_state

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

   880  * @param array $options

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

   882  *   details.

   883  */

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

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

   886   // released.

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

   888 

   889   // Extract field values from submitted values.

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

   891 

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

   893 

   894   // Let other modules act on submitting the entity.

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

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

   897     $function = $module . '_field_attach_submit';

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

   899   }

   900 }

   901 

   902 /**

   903  * Perform necessary operations just before fields data get saved.

   904  *

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

   906  * modules the opportunity to act.

   907  *

   908  * @param $entity_type

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

   910  * @param $entity

   911  *   The entity with fields to process.

   912  */

   913 function field_attach_presave($entity_type, $entity) {

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

   915 

   916   // Let other modules act on presaving the entity.

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

   918 }

   919 

   920 /**

   921  * Save field data for a new entity.

   922  *

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

   924  * revision id attributes.

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

   926  * $entity.

   927  *

   928  * @param $entity_type

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

   930  * @param $entity

   931  *   The entity with fields to save.

   932  * @return

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

   934  *   it leaves unspecified.

   935  */

   936 function field_attach_insert($entity_type, $entity) {

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

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

   939 

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

   941 

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

   943   // saved fields along the way.

   944   $skip_fields = array();

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

   946     $function = $module . '_field_storage_pre_insert';

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

   948   }

   949 

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

   951   $storages = array();

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

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

   954     $field_id = $field['id'];

   955     $field_name = $field['field_name'];

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

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

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

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

   960       }

   961     }

   962   }

   963 

   964   // Field storage backends save any remaining unsaved fields.

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

   966     $storage_info = field_info_storage_types($storage);

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

   968   }

   969 

   970   // Let other modules act on inserting the entity.

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

   972 

   973   $entity_info = entity_get_info($entity_type);

   974 }

   975 

   976 /**

   977  * Save field data for an existing entity.

   978  *

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

   980  * clear caches for the entity:

   981  * @code

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

   983  * @endcode

   984  *

   985  * @param $entity_type

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

   987  * @param $entity

   988  *   The entity with fields to save.

   989  */

   990 function field_attach_update($entity_type, $entity) {

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

   992 

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

   994 

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

   996   // saved fields along the way.

   997   $skip_fields = array();

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

   999     $function = $module . '_field_storage_pre_update';

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

  1001   }

  1002 

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

  1004   $storages = array();

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

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

  1007     $field_id = $field['id'];

  1008     $field_name = $field['field_name'];

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

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

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

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

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

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

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

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

  1017       }

  1018     }

  1019   }

  1020 

  1021   // Field storage backends save any remaining unsaved fields.

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

  1023     $storage_info = field_info_storage_types($storage);

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

  1025   }

  1026 

  1027   // Let other modules act on updating the entity.

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

  1029 

  1030   $entity_info = entity_get_info($entity_type);

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

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

  1033   }

  1034 }

  1035 

  1036 /**

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

  1038  * revisions of field data for the entity.

  1039  *

  1040  * @param $entity_type

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

  1042  * @param $entity

  1043  *   The entity whose field data to delete.

  1044  */

  1045 function field_attach_delete($entity_type, $entity) {

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

  1047 

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

  1049 

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

  1051   $storages = array();

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

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

  1054     $field_id = $field['id'];

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

  1056   }

  1057 

  1058   // Field storage backends delete their data.

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

  1060     $storage_info = field_info_storage_types($storage);

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

  1062   }

  1063 

  1064   // Let other modules act on deleting the entity.

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

  1066 

  1067   $entity_info = entity_get_info($entity_type);

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

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

  1070   }

  1071 }

  1072 

  1073 /**

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

  1075  * passed entity must have a revision id attribute.

  1076  *

  1077  * @param $entity_type

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

  1079  * @param $entity

  1080  *   The entity with fields to save.

  1081  */

  1082 function field_attach_delete_revision($entity_type, $entity) {

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

  1084 

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

  1086 

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

  1088   $storages = array();

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

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

  1091     $field_id = $field['id'];

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

  1093   }

  1094 

  1095   // Field storage backends delete their data.

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

  1097     $storage_info = field_info_storage_types($storage);

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

  1099   }

  1100 

  1101   // Let other modules act on deleting the revision.

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

  1103 }

  1104 

  1105 /**

  1106  * Prepare field data prior to display.

  1107  *

  1108  * This function lets field types and formatters load additional data

  1109  * needed for display that is not automatically loaded during

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

  1111  * optimisation when displaying lists of entities.

  1112  *

  1113  * field_attach_prepare_view() and field_attach_view() are two halves

  1114  * of the same operation. It is safe to call

  1115  * field_attach_prepare_view() multiple times on the same entity

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

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

  1118  * functions may yield incorrect results.

  1119  *

  1120  * @param $entity_type

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

  1122  * @param $entities

  1123  *   An array of entities, keyed by entity id.

  1124  * @param $view_mode

  1125  *   View mode, e.g. 'full', 'teaser'...

  1126  * @param $langcode

  1127  *   (Optional) The language the field values are to be shown in. If no language

  1128  *   is provided the current language is used.

  1129  * @param array $options

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

  1131  *   details.

  1132  */

  1133 function field_attach_prepare_view($entity_type, $entities, $view_mode, $langcode = NULL, $options = array()) {

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

  1135   // released.

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