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
{
    // ...
}

<?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']

# 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>

<?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:

[codeSelector]

<?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
{
    // ...
}

<?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']

# 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>

<?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>

[/codeSelector]

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 ApiPlatform\Doctrine\Orm\Filter\AbstractFilter implements `<a href="/docs/reference/Doctrine/Orm/Filter/FilterInterface">ApiPlatform\Doctrine\Orm\Filter\FilterInterface</a>`, `<a href="/docs/reference/Metadata/FilterInterface">ApiPlatform\Metadata\FilterInterface</a>`, `<a href="/docs/reference/Doctrine/Common/Filter/OrderFilterInterface">ApiPlatform\Doctrine\Common\Filter\OrderFilterInterface</a>`
{
    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, ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, null|ApiPlatform\Metadata\Operation $operation, array $context): null
    protected filterProperty(string $property, $direction, Doctrine\ORM\QueryBuilder $queryBuilder, ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, null|ApiPlatform\Metadata\Operation $operation, array $context): null
    protected getManagerRegistry(): Doctrine\Persistence\ManagerRegistry
    protected getProperties(): array
    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 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&lt;int, string&gt; $associations): Doctrine\Persistence\Mapping\ClassMetadata
    protected getClassMetadata(string $resourceClass): Doctrine\Persistence\Mapping\ClassMetadata
    public getDescription(string $resourceClass): array
}

class ApiPlatform\Doctrine\Orm\Filter\OrderFilter extends ApiPlatform\Doctrine\Orm\Filter\AbstractFilter implements `<a href="/docs/reference/Doctrine/Orm/Filter/FilterInterface">ApiPlatform\Doctrine\Orm\Filter\FilterInterface</a>`, `<a href="/docs/reference/Metadata/FilterInterface">ApiPlatform\Metadata\FilterInterface</a>`, `<a href="/docs/reference/Doctrine/Common/Filter/OrderFilterInterface">ApiPlatform\Doctrine\Common\Filter\OrderFilterInterface</a>`
{
    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, ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, null|ApiPlatform\Metadata\Operation $operation, array $context): null
    protected filterProperty(string $property, $direction, Doctrine\ORM\QueryBuilder $queryBuilder, ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, null|ApiPlatform\Metadata\Operation $operation, array $context): null
    protected getManagerRegistry(): Doctrine\Persistence\ManagerRegistry
    protected getProperties(): array
    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 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&lt;int, string&gt; $associations): Doctrine\Persistence\Mapping\ClassMetadata
    protected getClassMetadata(string $resourceClass): Doctrine\Persistence\Mapping\ClassMetadata
    public getDescription(string $resourceClass): array
}

Properties

logger

Psr\Log\LoggerInterface $logger

Psr\Log\LoggerInterface $logger

managerRegistry

Doctrine\Persistence\ManagerRegistry $managerRegistry

Doctrine\Persistence\ManagerRegistry $managerRegistry

properties

array $properties

array $properties

nameConverter

Symfony\Component\Serializer\NameConverter\NameConverterInterface $nameConverter

Symfony\Component\Serializer\NameConverter\NameConverterInterface $nameConverter

orderParameterName

string $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)

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, ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, null|ApiPlatform\Metadata\Operation $operation, array $context): null

public apply(Doctrine\ORM\QueryBuilder $queryBuilder, ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, null|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, ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, null|ApiPlatform\Metadata\Operation $operation, array $context): null

protected filterProperty(string $property, $direction, Doctrine\ORM\QueryBuilder $queryBuilder, ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, null|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

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

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

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

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

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&lt;int, string&gt; $associations): Doctrine\Persistence\Mapping\ClassMetadata

protected getNestedMetadata(string $resourceClass, array&lt;int, string&gt; $associations): Doctrine\Persistence\Mapping\ClassMetadata

Parameters

resourceClass	string
associations	array<int, string>

Returns

Doctrine\Persistence\Mapping\ClassMetadata

getClassMetadata

Gets class metadata for the given resource.

protected getClassMetadata(string $resourceClass): Doctrine\Persistence\Mapping\ClassMetadata

protected getClassMetadata(string $resourceClass): Doctrine\Persistence\Mapping\ClassMetadata

Parameters

resourceClass

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
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.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