ApiPlatform\Doctrine\Odm\Filter\SearchFilter

The search filter allows to filter a collection by given properties.

The search filter supports exact, partial, start, end, and word_start matching strategies:

exact strategy searches for fields that exactly match the value
partial strategy uses LIKE %value% to search for fields that contain the value
start strategy uses LIKE value% to search for fields that start with the value
end strategy uses LIKE %value to search for fields that end with the value
word_start strategy uses LIKE value% OR LIKE % value% to search for fields that contain words starting with the value

Note: it is possible to filter on properties and relations too.

Prepend the letter i to the filter if you want it to be case-insensitive. For example ipartial or iexact. Note that this will use the LOWER function and will impact performance if there is no proper index.

Case insensitivity may already be enforced at the database level depending on the collation used. If you are using MySQL, note that the commonly used utf8_unicode_ci collation (and its sibling utf8mb4_unicode_ci) are already case-insensitive, as indicated by the _ci part in their names.

Note: Search filters with the exact strategy can have multiple values for the same property (in this case the condition will be similar to a SQL IN clause).

Syntax: ?property[]=foo&property[]=bar.

<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiFilter;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Doctrine\Odm\Filter\SearchFilter;

#[ApiResource]
#[ApiFilter(SearchFilter::class, properties: ['isbn' => 'exact', 'description' => 'partial'])]
class Book
{
    // ...
}

# config/services.yaml
services:
    book.search_filter:
        parent: 'api_platform.doctrine.odm.search_filter'
        arguments: [ { isbn: 'exact', description: 'partial' } ]
        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.search_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.search_filter" parent="api_platform.doctrine.odm.search_filter">
            <argument type="collection">
                <argument key="isbn">exact</argument>
                <argument key="description">partial</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.search_filter</filter>
                </filters>
            </operation>
        </operations>
    </resource>
</resources>

class ApiPlatform\Doctrine\Odm\Filter\SearchFilter extends implements `<a href="/docs/main/references/Doctrine/Odm/Filter/FilterInterface">ApiPlatform\Doctrine\Odm\Filter\FilterInterface</a>`, `<a href="/docs/main/references/Doctrine/Common/Filter/PropertyAwareFilterInterface">ApiPlatform\Doctrine\Common\Filter\PropertyAwareFilterInterface</a>`, `<a href="/docs/main/references/Metadata/FilterInterface">ApiPlatform\Metadata\FilterInterface</a>`, `<a href="/docs/main/references/Doctrine/Common/Filter/SearchFilterInterface">ApiPlatform\Doctrine\Common\Filter\SearchFilterInterface
{
    public __construct(Doctrine\Persistence\ManagerRegistry $managerRegistry, |`<a href="/docs/main/references/Api/IriConverterInterface">ApiPlatform\Api\IriConverterInterface</a>` $iriConverter, null|`<a href="/docs/main/references/Api/IdentifiersExtractorInterface">ApiPlatform\Metadata\IdentifiersExtractorInterface</a>`|`<a href="/docs/main/references/Api/IdentifiersExtractorInterface">ApiPlatform\Api\IdentifiersExtractorInterface $identifiersExtractor, null|Symfony\Component\PropertyAccess\PropertyAccessorInterface $propertyAccessor, null|Psr\Log\LoggerInterface $logger, null|array $properties, null|Symfony\Component\Serializer\NameConverter\NameConverterInterface $nameConverter)
    protected getIriConverter(): |`<a href="/docs/main/references/Api/IriConverterInterface">ApiPlatform\Metadata\IriConverterInterface
    protected getPropertyAccessor(): Symfony\Component\PropertyAccess\PropertyAccessorInterface
    protected filterProperty(string $property, $value, Doctrine\ODM\MongoDB\Aggregation\Builder $aggregationBuilder, string $resourceClass, null|ApiPlatform\Metadata\Operation $operation, array $context): null
    protected getType(string $doctrineType): string
    public apply(Doctrine\ODM\MongoDB\Aggregation\Builder $aggregationBuilder, string $resourceClass, null|ApiPlatform\Metadata\Operation $operation, array $context): null
    protected getManagerRegistry(): Doctrine\Persistence\ManagerRegistry
    protected getProperties(): array
    public setProperties(array<int, string> $properties): null
    protected getLogger(): Psr\Log\LoggerInterface
    protected isPropertyEnabled(string $property, string $resourceClass): bool
    protected denormalizePropertyName(string|int $property): string
    protected normalizePropertyName(string $property): string
    protected splitPropertyParts(string $property, string $resourceClass): array
    protected getClassMetadata(string $resourceClass): Doctrine\Persistence\Mapping\ClassMetadata
    protected addLookupsForNestedProperty(string $property, Doctrine\ODM\MongoDB\Aggregation\Builder $aggregationBuilder, string $resourceClass, bool $preserveNullAndEmptyArrays): array
    protected isPropertyMapped(string $property, string $resourceClass, bool $allowAssociation): bool
    protected isPropertyNested(string $property, string $resourceClass): bool
    protected isPropertyEmbedded(string $property, string $resourceClass): bool
    protected getDoctrineFieldType(string $property, string $resourceClass): string
    protected getNestedMetadata(string $resourceClass, array<int, string> $associations): Doctrine\Persistence\Mapping\ClassMetadata
    public getDescription(string $resourceClass): array
    protected getIdFromValue(string $value)
    protected normalizeValues(array $values, string $property): array
    protected hasValidValues(array $values, null|string $type): bool
}

Properties

logger

Psr\Log\LoggerInterface $logger

managerRegistry

Doctrine\Persistence\ManagerRegistry $managerRegistry

properties

array $properties

nameConverter

Symfony\Component\Serializer\NameConverter\NameConverterInterface $nameConverter

iriConverter

|`<a href="/docs/main/references/Api/IriConverterInterface">ApiPlatform\Api\IriConverterInterface $iriConverter

propertyAccessor

Symfony\Component\PropertyAccess\PropertyAccessorInterface $propertyAccessor

identifiersExtractor

|`<a href="/docs/main/references/Api/IdentifiersExtractorInterface">ApiPlatform\Api\IdentifiersExtractorInterface $identifiersExtractor

Methods

__construct

public __construct(Doctrine\Persistence\ManagerRegistry $managerRegistry, |`<a href="/docs/main/references/Api/IriConverterInterface">ApiPlatform\Api\IriConverterInterface</a>` $iriConverter, null|`<a href="/docs/main/references/Api/IdentifiersExtractorInterface">ApiPlatform\Metadata\IdentifiersExtractorInterface</a>`|`<a href="/docs/main/references/Api/IdentifiersExtractorInterface">ApiPlatform\Api\IdentifiersExtractorInterface $identifiersExtractor, null|Symfony\Component\PropertyAccess\PropertyAccessorInterface $propertyAccessor, null|Psr\Log\LoggerInterface $logger, null|array $properties, null|Symfony\Component\Serializer\NameConverter\NameConverterInterface $nameConverter)

Parameters

managerRegistry	Doctrine\Persistence\ManagerRegistry
iriConverter	`ApiPlatform\Metadata\IriConverterInterface` `ApiPlatform\Api\IriConverterInterface`
identifiersExtractor	`ApiPlatform\Metadata\IdentifiersExtractorInterface` `ApiPlatform\Api\IdentifiersExtractorInterface`
propertyAccessor	Symfony\Component\PropertyAccess\PropertyAccessorInterface
logger	Psr\Log\LoggerInterface
properties	array
nameConverter	Symfony\Component\Serializer\NameConverter\NameConverterInterface

getIriConverter

protected getIriConverter(): |`<a href="/docs/main/references/Api/IriConverterInterface">ApiPlatform\Metadata\IriConverterInterface

Returns

<a href="/docs/main/references/Api/IriConverterInterface">ApiPlatform\Api\IriConverterInterface</a>
<a href="/docs/main/references/Api/IriConverterInterface">ApiPlatform\Metadata\IriConverterInterface</a>

getPropertyAccessor

protected getPropertyAccessor(): Symfony\Component\PropertyAccess\PropertyAccessorInterface

Returns

Symfony\Component\PropertyAccess\PropertyAccessorInterface

filterProperty

Passes a property through the filter.

protected filterProperty(string $property, $value, Doctrine\ODM\MongoDB\Aggregation\Builder $aggregationBuilder, string $resourceClass, null|ApiPlatform\Metadata\Operation $operation, array $context): null

Parameters

property	string
value
aggregationBuilder	Doctrine\ODM\MongoDB\Aggregation\Builder
resourceClass	string
operation	`ApiPlatform\Metadata\Operation`
context	array

Returns

null

getType

protected getType(string $doctrineType): string

Parameters

doctrineType

string

Returns

string

splitPropertyParts

Splits the given property into parts.Returns an array with the following keys:

associations: array of associations according to nesting order
field: string holding the actual field (leaf node)

protected splitPropertyParts(string $property, string $resourceClass): array

Parameters

property	string
resourceClass	string

Returns

array

isPropertyMapped

Determines whether the given property is mapped.

protected isPropertyMapped(string $property, string $resourceClass, bool $allowAssociation): bool

Parameters

property	string
resourceClass	string
allowAssociation	bool

Returns

bool

isPropertyNested

Determines whether the given property is nested.

protected isPropertyNested(string $property, string $resourceClass): bool

Parameters

property	string
resourceClass	string

Returns

bool

isPropertyEmbedded

Determines whether the given property is embedded.

protected isPropertyEmbedded(string $property, string $resourceClass): bool

Parameters

property	string
resourceClass	string

Returns

bool

getDoctrineFieldType

Gets the Doctrine Type of a given property/resourceClass.

protected getDoctrineFieldType(string $property, string $resourceClass): string

Parameters

property	string
resourceClass	string

Returns

string

getNestedMetadata

Gets nested class metadata for the given resource.

protected getNestedMetadata(string $resourceClass, array<int, string> $associations): Doctrine\Persistence\Mapping\ClassMetadata

Parameters

resourceClass	string
associations	array<int, string>

Returns

Doctrine\Persistence\Mapping\ClassMetadata

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
description : the description of the filter
strategy: the used strategy
is_collection: if this filter is for collection
swagger: additional parameters for the path operation, e.g. ‘swagger’ => [ ‘description’ => ‘My Description’, ’name’ => ‘My Name’, ’type’ => ‘integer’, ]
openapi: additional parameters for the path operation in the version 3 spec, e.g. ‘openapi’ => [ ‘description’ => ‘My Description’, ’name’ => ‘My Name’, ‘schema’ => [ ’type’ => ‘integer’, ] ]
schema: 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
description : the description of the filter
strategy: the used strategy
is_collection: if this filter is for collection
swagger: additional parameters for the path operation, e.g. ‘swagger’ => [ ‘description’ => ‘My Description’, ’name’ => ‘My Name’, ’type’ => ‘integer’, ]
openapi: additional parameters for the path operation in the version 3 spec, e.g. ‘openapi’ => [ ‘description’ => ‘My Description’, ’name’ => ‘My Name’, ‘schema’ => [ ’type’ => ‘integer’, ] ]
schema: 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
description : the description of the filter
strategy: the used strategy
is_collection: if this filter is for collection
swagger: additional parameters for the path operation, e.g. ‘swagger’ => [ ‘description’ => ‘My Description’, ’name’ => ‘My Name’, ’type’ => ‘integer’, ]
openapi: additional parameters for the path operation in the version 3 spec, e.g. ‘openapi’ => [ ‘description’ => ‘My Description’, ’name’ => ‘My Name’, ‘schema’ => [ ’type’ => ‘integer’, ] ]
schema: 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

Parameters

resourceClass

string

Returns

array

getIdFromValue

Gets the ID from an IRI or a raw ID.

protected getIdFromValue(string $value)

Parameters

value

string

Returns

normalizeValues

Normalize the values array.

protected normalizeValues(array $values, string $property): array

Parameters

values	array
property	string

Returns

array

hasValidValues

When the field should be an integer, check that the given value is a valid one.

protected hasValidValues(array $values, null|string $type): bool

Parameters

values	array
type	string

Returns

bool