3 files changed, 69 insertions, 11 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'];