ApiPlatform\Doctrine\Orm\Filter\OrderFilter

The order filter allows to sort a collection against the given properties.

Syntax: ?order[property]=<asc|desc>.

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

#[ApiResource]
#[ApiFilter(OrderFilter::class, properties: ['id', 'title'], arguments: ['orderParameterName' => 'order'])]
class Book
{
    // ...
}

# config/services.yaml
services:
    book.order_filter:
        parent: 'api_platform.doctrine.orm.order_filter'
        arguments: [ $properties: { id: ~, title: ~ }, $orderParameterName: order ]
        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.order_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.order_filter" parent="api_platform.doctrine.orm.order_filter">
            <argument type="collection" key="properties">
                <argument key="id"/>
                <argument key="title"/>
            </argument>
            <argument key="orderParameterName">order</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.order_filter</filter>
                </filters>
            </operation>
        </operations>
    </resource>
</resources>

Given that the collection endpoint is /books, you can filter books by title in ascending order and then by ID in descending order with the following query: /books?order[title]=desc&order[id]=asc.

By default, whenever the query does not specify the direction explicitly (e.g.: /books?order[title]&order[id]), filters will not be applied unless you configure a default order direction to use:

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

#[ApiResource]
#[ApiFilter(OrderFilter::class, properties: ['id' => 'ASC', 'title' => 'DESC'])]
class Book
{
    // ...
}

# config/services.yaml
services:
    book.order_filter:
        parent: 'api_platform.doctrine.orm.order_filter'
        arguments: [ { id: ASC, title: DESC } ]
        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.order_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.order_filter" parent="api_platform.doctrine.orm.order_filter">
            <argument type="collection">
                <argument key="id">ASC</argument>
                <argument key="title">DESC</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.order_filter</filter>
                </filters>
            </operation>
        </operations>
    </resource>
</resources>

When the property used for ordering can contain null values, you may want to specify how null values are treated in the comparison:

Use the default behavior of the DBMS: use null strategy
Exclude items: use ApiPlatform\Doctrine\Orm\Filter\OrderFilter::NULLS_SMALLEST (nulls_smallest) strategy
Consider items as oldest: use ApiPlatform\Doctrine\Orm\Filter\OrderFilter::NULLS_LARGEST (nulls_largest) strategy
Consider items as youngest: use ApiPlatform\Doctrine\Orm\Filter\OrderFilter::NULLS_ALWAYS_FIRST (nulls_always_first) strategy
Always include items: use ApiPlatform\Doctrine\Orm\Filter\OrderFilter::NULLS_ALWAYS_LAST (nulls_always_last) strategy

class ApiPlatform\Doctrine\Orm\Filter\OrderFilter extends implements `<a href="/docs/main/references/Doctrine/Orm/Filter/FilterInterface">ApiPlatform\Doctrine\Orm\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/OrderFilterInterface">ApiPlatform\Doctrine\Common\Filter\OrderFilterInterface
{
    public __construct(Doctrine\Persistence\ManagerRegistry $managerRegistry, string $orderParameterName, null|Psr\Log\LoggerInterface $logger, null|array $properties, null|Symfony\Component\Serializer\NameConverter\NameConverterInterface $nameConverter, null|string $orderNullsComparison)
    public apply(Doctrine\ORM\QueryBuilder $queryBuilder, $queryNameGenerator, string $resourceClass, null|`<a href="/docs/main/references/Metadata/Operation">ApiPlatform\Metadata\Operation $operation, array $context): null
    protected filterProperty(string $property, $direction, Doctrine\ORM\QueryBuilder $queryBuilder, $queryNameGenerator, string $resourceClass, null|`<a href="/docs/main/references/Metadata/Operation">ApiPlatform\Metadata\Operation $operation, array $context): null
    protected getManagerRegistry(): Doctrine\Persistence\ManagerRegistry
    protected getProperties(): array
    protected getLogger(): Psr\Log\LoggerInterface
    public setProperties(array<int, string> $properties): null
    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 addJoinsForNestedProperty(string $property, string $rootAlias, Doctrine\ORM\QueryBuilder $queryBuilder, ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, string $joinType): 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
}

Properties

logger

Psr\Log\LoggerInterface $logger

managerRegistry

Doctrine\Persistence\ManagerRegistry $managerRegistry

properties

array $properties

nameConverter

Symfony\Component\Serializer\NameConverter\NameConverterInterface $nameConverter

orderParameterName

string $orderParameterName

Methods

__construct

public __construct(Doctrine\Persistence\ManagerRegistry $managerRegistry, string $orderParameterName, null|Psr\Log\LoggerInterface $logger, null|array $properties, null|Symfony\Component\Serializer\NameConverter\NameConverterInterface $nameConverter, null|string $orderNullsComparison)

Parameters

managerRegistry	Doctrine\Persistence\ManagerRegistry
orderParameterName	string
logger	Psr\Log\LoggerInterface
properties	array
nameConverter	Symfony\Component\Serializer\NameConverter\NameConverterInterface
orderNullsComparison	string

apply

Applies the filter.Applies the filter.

public apply(Doctrine\ORM\QueryBuilder $queryBuilder, $queryNameGenerator, string $resourceClass, null|`<a href="/docs/main/references/Metadata/Operation">ApiPlatform\Metadata\Operation $operation, array $context): null

Parameters

queryBuilder	Doctrine\ORM\QueryBuilder
queryNameGenerator	`ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface`
resourceClass	string
operation	`ApiPlatform\Metadata\Operation`
context	array

Returns

null

filterProperty

Passes a property through the filter.

protected filterProperty(string $property, $direction, Doctrine\ORM\QueryBuilder $queryBuilder, $queryNameGenerator, string $resourceClass, null|`<a href="/docs/main/references/Metadata/Operation">ApiPlatform\Metadata\Operation $operation, array $context): null

Parameters

property	string
direction
queryBuilder	Doctrine\ORM\QueryBuilder
queryNameGenerator	`ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface`
resourceClass	string
operation	`ApiPlatform\Metadata\Operation`
context	array

Returns

null

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