function field_read_instances

Reads in field instances that match an array of conditions.

Parameters

$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.

$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 value

An array of instances matching the arguments.:

Related topics

File

modules/field/field.crud.inc, line 734

Field CRUD API, handling field and field instance creation and deletion.

Code

function field_read_instances($params = array(), $include_additional = array()) {
  $include_inactive = isset($include_additional['include_inactive']) && $include_additional['include_inactive'];
  $include_deleted = isset($include_additional['include_deleted']) && $include_additional['include_deleted'];

  $prefix = 'field.instance.';
  $get_full_name = FALSE;
  if (isset($params['entity_type'])) {
    $prefix .= $params['entity_type'] . '.';
    unset($params['entity_type']);
    if (isset($params['bundle'])) {
      $prefix .= $params['bundle'] . '.';
      unset($params['bundle']);
      if (isset($params['field_name'])) {
        $prefix .= $params['field_name'];
        unset($params['field_name']);
        $get_full_name = TRUE;
      }
    }
  }

  if ($get_full_name) {
    $config_names = array($prefix);
  }
  else {
    $config_names = config_get_names_with_prefix($prefix);
  }

  // Fields used for reference.
  $fields = _field_read_fields_cache();

  $instances = array();
  foreach ($config_names as $config_name) {
    $config = config($config_name);
    $instance = $config->get();

    // Continue if matching against a specific field that doesn't exist.
    if ($get_full_name && empty($instance)) {
      continue;
    }

    if ($params) {
      foreach ($params as $param_key => $param_value) {
        if ($instance[$param_key] != $param_value) {
          continue 2;
        }
      }
    }

    // Continue if this is a deleted instance.
    if (!$include_deleted && $instance['deleted']) {
      continue;
    }

    // Load the field providing this instance.
    if (!isset($fields[$instance['field_name']])) {
      continue;
    }
    $field = $fields[$instance['field_name']];

    // Continue if the instance's field has been deleted or is inactive.
    if (!$include_deleted && $field['deleted']) {
      continue;
    }
    if (!$include_inactive && !$field['active']) {
      continue;
    }

    // Set default instance settings.
    $instance += field_defaults_instance();
    $instance['settings'] += field_info_instance_settings($field['type']);

    // Filter out instances on unknown entity types (for instance because the
    // module exposing them was disabled).
    $entity_info = entity_get_info($instance['entity_type']);
    if ($include_inactive || $entity_info) {
      module_invoke_all('field_read_instance', $instance);
      $instances[] = $instance;
    }

    // Reset the field read cache to avoid storing two copies of all fields.
    backdrop_static_reset('_field_read_fields_cache');
  }

  return $instances;
}