In hook_field_validate(), the errors array is described as:
$errors[$field['field_name']][$delta][]
instead of:
$errors[$field['field_name']][$langcode][$delta][]

CommentFileSizeAuthor
#6 985804-hook-field-validate-1.patch1.86 KBsolotandem
#1 985804-hook-field-validate.patch1.43 KBsolotandem

Comments

solotandem’s picture

solotandem commented
Assigned: Unassigned » solotandem
Status: Active » Needs review
StatusFileSize
new 985804-hook-field-validate.patch1.43 KB

A 2-line patch is attached.

solotandem’s picture

solotandem commented
Title: Documentation problem with hook_field_validate » Errors array missing $langcode key in hook_field_validate

This was the title originally input, but after preview the default title from api.d.o was back.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Needs review » Needs work

Good catch! I see that this issue report is correct (you can look at text_field_validate() for a working example).

One small thing:

- *   The array of errors, keyed by field name and by value delta, that have
+ *   The array of errors (keyed by field name, langcode, and delta) that have

I don't think we should use "langcode" in documentation text. It should be "language code", I think. And I'm not sure about value delta -> delta -- did you do that on purpose or just to make the line wrap at the same spot? What's the usage elsewhere in the field API?

I like the parens you added to the documentation though -- good decision.

solotandem’s picture

solotandem commented

As is often the case, the usage varies as the summary below confirms. Given that, how about we use the word "language" instead of "langcode" in the item you question above?

In hook_field_attach_view_alter(), one of the keys is "language: The language code used for rendering."

In hook_field_attach_prepare_translation_alter(), one of the keys is "langcode: The language the entity has to be translated in."

In hook_field_language_alter(), one of the keys is "langcode: The language code $entity has to be displayed in."

In hook_field_load(), $langcode is described as "The language code associated with $items." In all (or virtually all) other instances, $langcode is described as "The language associated [with|to] $items" or "The language the field values are to be [entered|shown] in. If no language is provided the [current|default site] language is used."

In hook_field_widget_form(), one of the $element keys is "#language: The language the field is being edited in." Is this the language code or the language object?

This is in addition to the differences in the variable names in the code.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

The examples you are giving for language vs. langcode vs. language code are where the literal 'langcode' or 'language' is used as an array key, or where it's a variable name $language or $langcode. Here, neither of those is the case -- it's the two-letter language code that is being used as the array key, and I'm just asking that in the documentation text, we don't use "langcode", which isn't an English word, but instead use "language code" to refer to this two-letter (usually) code.

And it's too bad the other field API hooks are inconsistent about the literal array keys and variable names, but at this point we cannot change the API (too close to release).

The other thing I think we should check for documentation consistency is whether the 3rd key should be referred to as "delta" or "element delta". You changed it in your patch from what it was (element delta) to just "delta", and I am not sure what the justification is for that change, which is why I asked about how it was referred to elsewhere in the documentation.

solotandem’s picture

solotandem commented
Status: Needs work » Needs review
StatusFileSize
new 985804-hook-field-validate-1.patch1.86 KB

Revised patch attached.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

That is fine... do you also want to fix up the line above your changed section? 

  * @param $items
  *   $entity->{$field['field_name']}[$langcode], or an empty array if unset.

Should have [] not {} I think?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Needs review » Reviewed & tested by the community

solotandem pointed out (gently) in IRC that that is actually the correct notation. So this is fine.

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented
Status: Reviewed & tested by the community » Fixed

Committed to HEAD. Thanks!

Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for 2 weeks with no activity.