Same name and namespace in other branches

1. 9 core/modules/jsonapi/jsonapi.api.php \hook_jsonapi_entity_filter_access()
2. 8.9.x core/modules/jsonapi/jsonapi.api.php \hook_jsonapi_entity_filter_access()
3. 10 core/modules/jsonapi/jsonapi.api.php \hook_jsonapi_entity_filter_access()

Controls access when filtering by entity data via JSON:API.

This module supports filtering by resource object attributes referenced by relationship fields. For example, a site may add a "Favorite Animal" field to user entities, which would permit the following filtered query:

/jsonapi/node/article?filter[uid.field_favorite_animal]=llama

This query would return articles authored by users whose favorite animal is a llama. However, the information about a user's favorite animal should not be available to users without the "access user profiles" permission. The same must hold true even if that user is referenced as an article's author. Therefore, access to filter by this data must be restricted so that access cannot be bypassed via a JSON:API filtered query.

As a rule, clients should only be able to filter by data that they can view.

Conventionally, `$entity->access('view')` is how entity access is checked. This call invokes the corresponding hooks. However, these access checks require an `$entity` object. This means that they cannot be called prior to executing a database query.

In order to safely enable filtering across a relationship, modules responsible for entity access must do two things:

• Implement this hook (or hook_jsonapi_ENTITY_TYPE_filter_access()) and return an array of AccessResults keyed by the named entity subsets below.
• If the AccessResult::allowed() returned by the above hook does not provide enough granularity (for example, if access depends on a bundle field value of the entity being queried), then hook_query_TAG_alter() must be implemented using the 'entity_access' or 'ENTITY_TYPE_access' query tag. See node_query_node_access_alter() for an example.

Parameters

\Drupal\Core\Entity\EntityTypeInterface $entity_type: The entity type of the entity to be filtered upon.

\Drupal\Core\Session\AccountInterface $account: The account for which to check access.

Return value

\Drupal\Core\Access\AccessResultInterface[] An array keyed by a constant which identifies a subset of entities. For each subset, the value is one of the following access results:

• AccessResult::allowed() if all entities within the subset (potentially narrowed by hook_query_TAG_alter() implementations) are viewable.
• AccessResult::forbidden() if any entity within the subset is not viewable.
• AccessResult::neutral() if the implementation has no opinion.

The supported subsets for which an access result may be returned are:

• JSONAPI_FILTER_AMONG_ALL: all entities of the given type.
• JSONAPI_FILTER_AMONG_PUBLISHED: all published entities of the given type.
• JSONAPI_FILTER_AMONG_ENABLED: all enabled entities of the given type.
• JSONAPI_FILTER_AMONG_OWN: all entities of the given type owned by the user for whom access is being checked.

See the documentation of the above constants for more information about each subset.

See also

hook_jsonapi_ENTITY_TYPE_filter_access()

Related topics

1 function implements hook_jsonapi_entity_filter_access()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

jsonapi_jsonapi_entity_filter_access in core/modules/jsonapi/jsonapi.module

Implements hook_jsonapi_entity_filter_access().

File

core/modules/jsonapi/jsonapi.api.php, line 273

Code

function hook_jsonapi_entity_filter_access(\Drupal\Core\Entity\EntityTypeInterface $entity_type, \Drupal\Core\Session\AccountInterface $account) {
    // For every entity type that has an admin permission, allow access to filter
    // by all entities of that type to users with that permission.
    if ($admin_permission = $entity_type->getAdminPermission()) {
        return [
            JSONAPI_FILTER_AMONG_ALL => AccessResult::allowedIfHasPermission($account, $admin_permission),
        ];
    }
}

---