ApiPlatform\Serializer\Filter\GroupFilter

The group filter allows you to filter by serialization groups.

Syntax: ?groups[]=<group>.

You can add as many groups as you need.

Three arguments are available to configure the filter:

parameterName is the query parameter name (default: groups)
overrideDefaultGroups allows to override the default serialization groups (default: false)
whitelist groups whitelist to avoid uncontrolled data exposure (default: null to allow all groups)

<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiFilter;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Serializer\Filter\GroupFilter;
 
#[ApiResource]
#[ApiFilter(GroupFilter::class, arguments: ['parameterName' => 'groups', 'overrideDefaultGroups' => false, 'whitelist' => ['allowed_group']])]
class Book
{
    // ...
}

<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiFilter;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Serializer\Filter\GroupFilter;
 
#[ApiResource]
#[ApiFilter(GroupFilter::class, arguments: ['parameterName' => 'groups', 'overrideDefaultGroups' => false, 'whitelist' => ['allowed_group']])]
class Book
{
    // ...
}

# config/services.yaml
services:
    book.group_filter:
        parent: 'api_platform.serializer.group_filter'
        arguments: [ $parameterName: 'groups', $overrideDefaultGroups: false, $whitelist: ['allowed_group'] ]
        tags:  [ 'api_platform.filter' ]
        # The following are mandatory only if a _defaults section is defined with inverted values.
        # You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the defaults section)
        autowire: false
        autoconfigure: false
        public: false
 
# api/config/api_platform/resources.yaml
resources:
    App\Entity\Book:
        - operations:
              ApiPlatform\Metadata\GetCollection:
                  filters: ['book.group_filter']

# config/services.yaml
services:
    book.group_filter:
        parent: 'api_platform.serializer.group_filter'
        arguments: [ $parameterName: 'groups', $overrideDefaultGroups: false, $whitelist: ['allowed_group'] ]
        tags:  [ 'api_platform.filter' ]
        # The following are mandatory only if a _defaults section is defined with inverted values.
        # You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the defaults section)
        autowire: false
        autoconfigure: false
        public: false
 
# api/config/api_platform/resources.yaml
resources:
    App\Entity\Book:
        - operations:
              ApiPlatform\Metadata\GetCollection:
                  filters: ['book.group_filter']

<?xml version="1.0" encoding="UTF-8" ?>
<!-- api/config/services.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container
        xmlns="http://symfony.com/schema/dic/services"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">
    <services>
        <service id="book.group_filter" parent="api_platform.serializer.group_filter">
            <argument key="parameterName">groups</argument>
            <argument key="overrideDefaultGroups">false</argument>
            <argument key="whitelist" type="collection">
                <argument>allowed_group</argument>
            </argument>
            <tag name="api_platform.filter"/>
        </service>
    </services>
</container>
<!-- api/config/api_platform/resources.xml -->
<resources
        xmlns="https://api-platform.com/schema/metadata/resources-3.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
        https://api-platform.com/schema/metadata/resources-3.0.xsd">
    <resource class="App\Entity\Book">
        <operations>
            <operation class="ApiPlatform\Metadata\GetCollection">
                <filters>
                    <filter>book.group_filter</filter>
                </filters>
            </operation>
        </operations>
    </resource>
</resources>

<?xml version="1.0" encoding="UTF-8" ?>
<!-- api/config/services.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container
        xmlns="http://symfony.com/schema/dic/services"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">
    <services>
        <service id="book.group_filter" parent="api_platform.serializer.group_filter">
            <argument key="parameterName">groups</argument>
            <argument key="overrideDefaultGroups">false</argument>
            <argument key="whitelist" type="collection">
                <argument>allowed_group</argument>
            </argument>
            <tag name="api_platform.filter"/>
        </service>
    </services>
</container>
<!-- api/config/api_platform/resources.xml -->
<resources
        xmlns="https://api-platform.com/schema/metadata/resources-3.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
        https://api-platform.com/schema/metadata/resources-3.0.xsd">
    <resource class="App\Entity\Book">
        <operations>
            <operation class="ApiPlatform\Metadata\GetCollection">
                <filters>
                    <filter>book.group_filter</filter>
                </filters>
            </operation>
        </operations>
    </resource>
</resources>

Given that the collection endpoint is /books, you can filter books by serialization groups with the following query: /books?groups[]=read&groups[]=write.

class ApiPlatform\Serializer\Filter\GroupFilter implements `<a href="/docs/reference/Serializer/Filter/FilterInterface">ApiPlatform\Serializer\Filter\FilterInterface</a>`, `<a href="/docs/reference/Metadata/FilterInterface">ApiPlatform\Metadata\FilterInterface</a>`
{
    public __construct(string $parameterName, bool $overrideDefaultGroups, null|array $whitelist)
    public apply(Symfony\Component\HttpFoundation\Request $request, bool $normalization, array $attributes, array $context): null
    public getDescription(string $resourceClass): array
}

class ApiPlatform\Serializer\Filter\GroupFilter implements `<a href="/docs/reference/Serializer/Filter/FilterInterface">ApiPlatform\Serializer\Filter\FilterInterface</a>`, `<a href="/docs/reference/Metadata/FilterInterface">ApiPlatform\Metadata\FilterInterface</a>`
{
    public __construct(string $parameterName, bool $overrideDefaultGroups, null|array $whitelist)
    public apply(Symfony\Component\HttpFoundation\Request $request, bool $normalization, array $attributes, array $context): null
    public getDescription(string $resourceClass): array
}

Methods

__construct

public __construct(string $parameterName, bool $overrideDefaultGroups, null|array $whitelist)

public __construct(string $parameterName, bool $overrideDefaultGroups, null|array $whitelist)

Parameters

parameterName	string
overrideDefaultGroups	bool
whitelist	array

apply

Apply a filter to the serializer context.

public apply(Symfony\Component\HttpFoundation\Request $request, bool $normalization, array $attributes, array $context): null

public apply(Symfony\Component\HttpFoundation\Request $request, bool $normalization, array $attributes, array $context): null

Parameters

request	Symfony\Component\HttpFoundation\Request
normalization	bool
attributes	array
context	array

Returns

null

getDescription

Gets the description of this filter for the given resource.Returns an array with the filter parameter names as keys and array with the following data as values:

property: the property where the filter is applied
type: the type of the filter
required: if this filter is required
strategy (optional): the used strategy
is_collection (optional): if this filter is for collection
swagger (optional): additional parameters for the path operation, e.g. 'swagger' => [ 'description' => 'My Description', 'name' => 'My Name', 'type' => 'integer', ]
openapi (optional): additional parameters for the path operation in the version 3 spec, e.g. 'openapi' => [ 'description' => 'My Description', 'name' => 'My Name', 'schema' => [ 'type' => 'integer', ] ]
schema (optional): schema definition, e.g. 'schema' => [ 'type' => 'string', 'enum' => ['value_1', 'value_2'], ] The description can contain additional data specific to a filter.Gets the description of this filter for the given resource.Returns an array with the filter parameter names as keys and array with the following data as values:
property: the property where the filter is applied
type: the type of the filter
required: if this filter is required
strategy (optional): the used strategy
is_collection (optional): if this filter is for collection
swagger (optional): additional parameters for the path operation, e.g. 'swagger' => [ 'description' => 'My Description', 'name' => 'My Name', 'type' => 'integer', ]
openapi (optional): additional parameters for the path operation in the version 3 spec, e.g. 'openapi' => [ 'description' => 'My Description', 'name' => 'My Name', 'schema' => [ 'type' => 'integer', ] ]
schema (optional): schema definition, e.g. 'schema' => [ 'type' => 'string', 'enum' => ['value_1', 'value_2'], ] The description can contain additional data specific to a filter.

public getDescription(string $resourceClass): array

public getDescription(string $resourceClass): array

Parameters

resourceClass

string

Returns

array