Docblock incomplete in field_read_instances().

[laryn]

Description of the bug

I ran into a warning in a contrib module:

Warning: Array to string conversion in field_read_instances() (line 757 of /var/www/html/backdrop/core/modules/field/field.crud.inc).

This led me to look into field_read_instances, where the contrib module was sending $params['field_name'] as an array of field names. The code seems to expect a string for this optional property -- but looking up to the docblock for verification, I don't see this property listed:

/**
 * Reads in field instances that match an array of conditions.
 *
 * @param $param
 *   An array of properties to use in selecting a field instance. Supported
 *   properties include:
 *   - entity_type: The entity type to which to limit instances.
 *   - bundle: The bundle type within the entity to which instances should be
 *     limited. If specified, an entity_type must be specified as well.
 * @param $include_additional
 *   The default behavior of this function is to not return field
 *   instances that have been marked deleted, or whose field is inactive.
 *   Setting $include_additional['include_inactive'] or
 *   $include_additional['include_deleted'] to TRUE will override this
 *   behavior.
 * @return
 *   An array of instances matching the arguments.
 */

[laryn]

Interestingly I just ran across this again in a different module. It looks like D7 allowed an array of values for field_name -- should we change the function to allow for that, or document the change to only allow a single value for field_name?

[avpaderno]

Drupal 7 allows to use an array for field_name because $query->condition('fci.' . $key, $value); (used by field_read_instances() could either accept a single value for $value or an array.

The functions calling field_read_instances() should not count on that, as that is not documented in Drupal 7, in the same way they should not count on the fact they could pass an array for entity_type too.