Guides

References

    Tutorials

    In depth

    Reference
    C
    Class

    ApiPlatform\Serializer\Filter\PropertyFilter

    The property filter adds the possibility to select the properties to serialize (sparse fieldsets).

    Note: We strongly recommend using Vulcain instead of this filter. Vulcain is faster, allows a better hit rate, and is supported out of the box in the API Platform distribution.

    Syntax: ?properties[]=<property>&properties[<relation>][]=<property>.

    You can add as many properties as you need.

    Three arguments are available to configure the filter:

    • parameterName is the query parameter name (default: properties)
    • overrideDefaultProperties allows to override the default serialization properties (default: false)
    • whitelist properties whitelist to avoid uncontrolled data exposure (default: null to allow all properties)
    <?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiFilter;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Serializer\Filter\PropertyFilter;
 
#[ApiResource]
#[ApiFilter(PropertyFilter::class, arguments: ['parameterName' => 'properties', 'overrideDefaultProperties' => false, 'whitelist' => ['allowed_property']])]
class Book
{
    // ...
}
    <?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiFilter;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Serializer\Filter\PropertyFilter;
 
#[ApiResource]
#[ApiFilter(PropertyFilter::class, arguments: ['parameterName' => 'properties', 'overrideDefaultProperties' => false, 'whitelist' => ['allowed_property']])]
class Book
{
    // ...
}

    Given that the collection endpoint is /books, you can filter the serialization properties with the following query: /books?properties[]=title&properties[]=author. If you want to include some properties of the nested "author" document, use: /books?properties[]=title&properties[author][]=name.

    class ApiPlatform\Serializer\Filter\PropertyFilter 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 $overrideDefaultProperties, null|array $whitelist, null|Symfony\Component\Serializer\NameConverter\NameConverterInterface $nameConverter)
    public apply(Symfony\Component\HttpFoundation\Request $request, bool $normalization, array $attributes, array $context): null
    public getDescription(string $resourceClass): array
}
    class ApiPlatform\Serializer\Filter\PropertyFilter 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 $overrideDefaultProperties, null|array $whitelist, null|Symfony\Component\Serializer\NameConverter\NameConverterInterface $nameConverter)
    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 $overrideDefaultProperties, null|array $whitelist, null|Symfony\Component\Serializer\NameConverter\NameConverterInterface $nameConverter)
    public __construct(string $parameterName, bool $overrideDefaultProperties, null|array $whitelist, null|Symfony\Component\Serializer\NameConverter\NameConverterInterface $nameConverter)

    Parameters

    parameterNamestring
    overrideDefaultPropertiesbool
    whitelistarray
    nameConverterSymfony\Component\Serializer\NameConverter\NameConverterInterface

    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

    requestSymfony\Component\HttpFoundation\Request
    normalizationbool
    attributesarray
    contextarray

    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

    resourceClassstring

    Returns

    array

    Copyright © 2023 Kévin Dunglas

    Sponsored by Les-Tilleuls.coop

    Resources

    LogosWallpapersColouring webby
    HelpScreencastsStack overflowSlackCode of conductReport issues
    CommunityEventsAPI Platform ConferenceContributorsTwitterGithubContribute

    Code licensed under MIT, documentation under CC by 3.0

    Enterprise subscriptionSecurity PolicyTrademark Policy