6 files changed, 74 insertions, 16 deletions
diff --git a/modules/field/field.api.php b/modules/field/field.api.php
index 415e8935c..a7e26bb35 100644
--- a/modules/field/field.api.php
+++ b/modules/field/field.api.php
@@ -759,15 +759,25 @@ function hook_field_widget_info_alter(&$info) {
  * invoke this hook as many times as needed.
  *
  * Note that, depending on the context in which the widget is being included
- * (regular entity edit form, 'default value' input in the field settings form,
- * etc.), the passed in values for $field and $instance might be different
- * from the official definitions returned by field_info_field() and
- * field_info_instance(). If the widget uses Form API callbacks (like
- * #element_validate, #value_callback...) that need to access the $field or
- * $instance definitions, they should not use the field_info_*() functions, but
- * fetch the information present in $form_state['field']:
- * - $form_state['field'][$field_name][$langcode]['field']
- * - $form_state['field'][$field_name][$langcode]['instance']
+ * (regular entity form, field configuration form, advanced search form...),
+ * the values for $field and $instance might be different from the "official"
+ * definitions returned by field_info_field() and field_info_instance().
+ * Examples: mono-value widget even if the field is multi-valued, non-required
+ * widget even if the field is 'required'...
+
+ * Therefore, the FAPI element callbacks (such as #process, #element_validate,
+ * #value_callback...) used by the widget cannot use the field_info_field()
+ * or field_info_instance() functions to retrieve the $field or $instance
+ * definitions they should operate on. The field_widget_field() and
+ * field_widget_instance() functions should be used instead to fetch the
+ * current working definitions from $form_state, where Field API stores them.
+ *
+ * Alternatively, hook_field_widget_form() can extract the needed specific
+ * properties from $field and $instance and set them as ad-hoc
+ * $element['#custom'] properties, for later use by its element callbacks.
+ *
+ * @see field_widget_field()
+ * @see field_widget_instance()
  *
  * @param $form
  *   The entire form array.
diff --git a/modules/field/field.form.inc b/modules/field/field.form.inc
index 474cc7f5b..ec8b8d60e 100644
--- a/modules/field/field.form.inc
+++ b/modules/field/field.form.inc
@@ -411,3 +411,51 @@ function field_add_more_js($form, $form_state) {
 
   return $element;
 }
+
+/**
+ * Retrieves the field definition for a widget's helper callbacks.
+ *
+ * Widgets helper element callbacks (such as #process, #element_validate,
+ * #value_callback, ...) should use field_widget_field() and
+ * field_widget_instance() instead of field_info_field() and
+ * field_info_instance() when they need to access field or instance properties.
+ * See hook_field_widget_form() for more details.
+ *
+ * @see field_widget_instance()
+ * @see hook_field_widget_form()
+ *
+ * @param $element
+ *   The structured array for the widget.
+ * @param $form_state
+ *   The form state.
+ * @return
+ *   The $field definition array for the current widget.
+ */
+function field_widget_field($element, $form_state) {
+  $info = $form_state['field'][$element['#field_name']][$element['#language']];
+  return $info['field'];
+}
+
+/**
+ * Provides the instance definition array for a widget's helper callbacks.
+ *
+ * Widgets helper element callbacks (such as #process, #element_validate,
+ * #value_callback, ...) should use field_widget_field() and
+ * field_widget_instance() instead of field_info_field() and
+ * field_info_instance() when they need to access field or instance properties.
+ * See hook_field_widget_form() for more details.
+ *
+ * @see field_widget_field()
+ * @see hook_field_widget_form()
+ *
+ * @param $element
+ *   The structured array for the widget.
+ * @param $form_state
+ *   The form state.
+ * @return
+ *   The $instance definition array for the current widget.
+ */
+function field_widget_instance($element, $form_state) {
+  $info = $form_state['field'][$element['#field_name']][$element['#language']];
+  return $info['instance'];
+}
diff --git a/modules/field/modules/number/number.module b/modules/field/modules/number/number.module
index aa792ab39..45ea95455 100644
--- a/modules/field/modules/number/number.module
+++ b/modules/field/modules/number/number.module
@@ -356,8 +356,8 @@ function number_field_widget_form(&$form, &$form_state, $field, $instance, $lang
  * FAPI validation of an individual number element.
  */
 function number_field_widget_validate($element, &$form_state) {
-  $field = $form_state['field'][$element['#field_name']][$element['#language']]['field'];
-  $instance = $form_state['field'][$element['#field_name']][$element['#language']]['instance'];
+  $field = field_widget_field($element, $form_state);
+  $instance = field_widget_instance($element, $form_state);
 
   $type = $element['#number_type'];
   $value = $element['#value'];
diff --git a/modules/file/file.field.inc b/modules/file/file.field.inc
index 3b75f5bf9..37c192b87 100644
--- a/modules/file/file.field.inc
+++ b/modules/file/file.field.inc
@@ -583,7 +583,7 @@ function file_field_widget_value($element, $input = FALSE, $form_state) {
   if ($input) {
     // Checkboxes lose their value when empty.
     // If the display field is present make sure its unchecked value is saved.
-    $field = $form_state['field'][$element['#field_name']][$element['#language']]['field'];
+    $field = field_widget_field($element, $form_state);
     if (empty($input['display'])) {
       $input['display'] = $field['settings']['display_field'] ? 0 : 1;
     }
@@ -611,8 +611,8 @@ function file_field_widget_process($element, &$form_state, $form) {
   $item = $element['#value'];
   $item['fid'] = $element['fid']['#value'];
 
-  $field = $form_state['field'][$element['#field_name']][$element['#language']]['field'];
-  $instance = $form_state['field'][$element['#field_name']][$element['#language']]['instance'];
+  $field = field_widget_field($element, $form_state);
+  $instance = field_widget_instance($element, $form_state);
   $settings = $instance['widget']['settings'];
 
   $element['#theme'] = 'file_widget';
diff --git a/modules/image/image.field.inc b/modules/image/image.field.inc
index 1fbc63062..249195d0b 100644
--- a/modules/image/image.field.inc
+++ b/modules/image/image.field.inc
@@ -335,7 +335,7 @@ function image_field_widget_process($element, &$form_state, $form) {
   $item = $element['#value'];
   $item['fid'] = $element['fid']['#value'];
 
-  $instance = $form_state['field'][$element['#field_name']][$element['#language']]['instance'];
+  $instance = field_widget_instance($element, $form_state);
 
   $settings = $instance['settings'];
   $widget_settings = $instance['widget']['settings'];
diff --git a/modules/taxonomy/taxonomy.module b/modules/taxonomy/taxonomy.module
index 1e0cf45ad..47e845b23 100644
--- a/modules/taxonomy/taxonomy.module
+++ b/modules/taxonomy/taxonomy.module
@@ -1457,7 +1457,7 @@ function taxonomy_autocomplete_validate($element, &$form_state) {
   $value = array();
   if ($tags = $element['#value']) {
     // Collect candidate vocabularies.
-    $field = $form_state['field'][$element['#field_name']][$element['#language']]['field'];
+    $field = field_widget_field($element, $form_state);
     $vocabularies = array();
     foreach ($field['settings']['allowed_values'] as $tree) {
       if ($vocabulary = taxonomy_vocabulary_machine_name_load($tree['vocabulary'])) {