ApiPlatform\State\OptionsInterface $stateOptions
bool $nested
string $resolver
array $args
array $extraArgs
array $links
string $shortName
string $class
bool $paginationEnabled
The paginationEnabled
option enables (or disables) the pagination for the current collection operation.
<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\GetCollection;
#[GetCollection(paginationEnabled: true)]
class Book
{
// ...
}
# api/config/api_platform/resources.yaml
resources:
App\Entity\Book:
- operations:
ApiPlatform\Metadata\GetCollection:
paginationEnabled: true
<?xml version="1.0" encoding="UTF-8" ?>
<!-- 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" paginationEnabled=true />
</operations>
</resource>
</resources>
string $paginationType
The paginationType
option defines the type of pagination (page
or cursor
) to use for the current collection operation.
<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\GetCollection;
#[GetCollection(paginationType: 'page')]
class Book
{
// ...
}
# api/config/api_platform/resources.yaml
resources:
App\Entity\Book:
- operations:
ApiPlatform\Metadata\GetCollection:
paginationType: page
<?xml version="1.0" encoding="UTF-8" ?>
<!-- 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" paginationType="page" />
</operations>
</resource>
</resources>
int $paginationItemsPerPage
The paginationItemsPerPage
option defines the number of items per page for the current collection operation.
<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\GetCollection;
#[GetCollection(paginationItemsPerPage: 30)]
class Book
{
// ...
}
# api/config/api_platform/resources.yaml
resources:
App\Entity\Book:
- operations:
ApiPlatform\Metadata\GetCollection:
paginationItemsPerPage: 30
<?xml version="1.0" encoding="UTF-8" ?>
<!-- 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" paginationItemsPerPage=30 />
</operations>
</resource>
</resources>
int $paginationMaximumItemsPerPage
The paginationMaximumItemsPerPage
option defines the maximum number of items per page for the current resource.
<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\GetCollection;
#[GetCollection(paginationMaximumItemsPerPage: 50)]
class Book
{
// ...
}
# api/config/api_platform/resources.yaml
resources:
App\Entity\Book:
- operations:
ApiPlatform\Metadata\GetCollection:
paginationMaximumItemsPerPage: 50
<?xml version="1.0" encoding="UTF-8" ?>
<!-- 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" paginationMaximumItemsPerPage=50 />
</operations>
</resource>
</resources>
bool $paginationPartial
The paginationPartial
option enables (or disables) the partial pagination for the current collection operation.
<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\GetCollection;
#[GetCollection(paginationPartial: true)]
class Book
{
// ...
}
# api/config/api_platform/resources.yaml
resources:
App\Entity\Book:
- operations:
ApiPlatform\Metadata\GetCollection:
paginationPartial: true
<?xml version="1.0" encoding="UTF-8" ?>
<!-- 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" paginationPartial=true />
</operations>
</resource>
</resources>
bool $paginationClientEnabled
The paginationClientEnabled
option allows (or disallows) the client to enable (or disable) the pagination for the current collection operation.
<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\GetCollection;
#[GetCollection(paginationClientEnabled: true)]
class Book
{
// ...
}
# api/config/api_platform/resources.yaml
resources:
App\Entity\Book:
- operations:
ApiPlatform\Metadata\GetCollection:
paginationClientEnabled: true
<?xml version="1.0" encoding="UTF-8" ?>
<!-- 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" paginationClientEnabled=true />
</operations>
</resource>
</resources>
The pagination can now be enabled (or disabled) by adding a query parameter named pagination
:
GET /books?pagination=false
: disabledGET /books?pagination=true
: enabledbool $paginationClientItemsPerPage
The paginationClientItemsPerPage
option allows (or disallows) the client to set the number of items per page for the current collection operation.
<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\GetCollection;
#[GetCollection(paginationClientItemsPerPage: true)]
class Book
{
// ...
}
# api/config/api_platform/resources.yaml
resources:
App\Entity\Book:
- operations:
ApiPlatform\Metadata\GetCollection:
paginationClientItemsPerPage: true
<?xml version="1.0" encoding="UTF-8" ?>
<!-- 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" paginationClientItemsPerPage=true />
</operations>
</resource>
</resources>
The number of items can now be set by adding a query parameter named itemsPerPage
:
GET /books?itemsPerPage=50
bool $paginationClientPartial
The paginationClientPartial
option allows (or disallows) the client to enable (or disable) the partial pagination for the current collection operation.
<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\GetCollection;
#[GetCollection(paginationClientPartial: true)]
class Book
{
// ...
}
# api/config/api_platform/resources.yaml
resources:
App\Entity\Book:
- operations:
ApiPlatform\Metadata\GetCollection:
paginationClientPartial: true
<?xml version="1.0" encoding="UTF-8" ?>
<!-- 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" paginationClientPartial=true />
</operations>
</resource>
</resources>
The partial pagination can now be enabled (or disabled) by adding a query parameter named partial
:
GET /books?partial=false
: disabledGET /books?partial=true
: enabledbool $paginationFetchJoinCollection
The PaginationExtension of API Platform performs some checks on the QueryBuilder
to guess, in most common
cases, the correct values to use when configuring the Doctrine ORM Paginator: $fetchJoinCollection
argument, whether there is a join to a collection-valued association.
When set to true
, the Doctrine ORM Paginator will perform an additional query, in order to get the
correct number of results. You can configure this using the paginationFetchJoinCollection
option:
<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\GetCollection;
#[GetCollection(paginationFetchJoinCollection: false)]
class Book
{
// ...
}
# api/config/api_platform/resources.yaml
resources:
App\Entity\Book:
- operations:
ApiPlatform\Metadata\GetCollection:
paginationFetchJoinCollection: false
<?xml version="1.0" encoding="UTF-8" ?>
<!-- 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" paginationFetchJoinCollection=false />
</operations>
</resource>
</resources>
For more information, please see the Pagination entry in the Doctrine ORM documentation.
bool $paginationUseOutputWalkers
The PaginationExtension of API Platform performs some checks on the QueryBuilder
to guess, in most common
cases, the correct values to use when configuring the Doctrine ORM Paginator: $setUseOutputWalkers
setter,
whether to use output walkers.
When set to true
, the Doctrine ORM Paginator will use output walkers, which are compulsory for some types
of queries. You can configure this using the paginationUseOutputWalkers
option:
<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\GetCollection;
#[GetCollection(paginationUseOutputWalkers: false)]
class Book
{
// ...
}
# api/config/api_platform/resources.yaml
resources:
App\Entity\Book:
- operations:
ApiPlatform\Metadata\GetCollection:
paginationUseOutputWalkers: false
<?xml version="1.0" encoding="UTF-8" ?>
<!-- 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" paginationUseOutputWalkers=false />
</operations>
</resource>
</resources>
For more information, please see the Pagination entry in the Doctrine ORM documentation.
array $paginationViaCursor
The paginationViaCursor
option configures the cursor-based pagination for the current resource.
Select your unique sorted field as well as the direction you’ll like the pagination to go via filters.
Note that for now you have to declare a RangeFilter
and an OrderFilter
on the property used for the cursor-based pagination:.
<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiFilter;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Doctrine\Odm\Filter\OrderFilter;
use ApiPlatform\Doctrine\Odm\Filter\RangeFilter;
#[GetCollection(paginationPartial: true, paginationViaCursor: [['field' => 'id', 'direction' => 'DESC']])]
#[ApiFilter(RangeFilter::class, properties: ["id"])]
#[ApiFilter(OrderFilter::class, properties: ["id" => "DESC"])]
class Book
{
// ...
}
# api/config/api_platform/resources.yaml
resources:
App\Entity\Book:
- operations:
ApiPlatform\Metadata\GetCollection:
paginationPartial: true
paginationViaCursor:
- { field: 'id', direction: 'DESC' }
filters: [ 'app.filters.book.range', 'app.filters.book.order' ]
<?xml version="1.0" encoding="UTF-8" ?>
<!-- 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" paginationPartial=true>
<filters>
<filter>app.filters.book.range</filter>
<filter>app.filters.book.order</filter>
</filters>
<paginationViaCursor>
<paginationField field="id" direction="DESC" />
</paginationViaCursor>
</operation>
</operations>
</resource>
</resources>
To know more about cursor-based pagination take a look at this blog post on medium (draft).
array $order
string $description
array $normalizationContext
array $denormalizationContext
bool $collectDenormalizationErrors
Stringable|string $security
string $securityMessage
Stringable|string $securityPostDenormalize
string $securityPostDenormalizeMessage
Stringable|string $securityPostValidation
string $securityPostValidationMessage
string $deprecationReason
The deprecationReason
option deprecates the current operation with a deprecation message.
<?php
// api/src/Entity/Parchment.php
use ApiPlatform\Metadata\Get;
#[Get(deprecationReason: 'Create a Book instead')]
class Parchment
{
// ...
}
# api/config/api_platform/resources.yaml
resources:
App\Entity\Parchment:
- operations:
ApiPlatform\Metadata\Get:
deprecationReason: 'Create a Book instead'
<?xml version="1.0" encoding="UTF-8" ?>
<!-- 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\Parchment">
<operations>
<operation class="ApiPlatform\Metadata\Get" deprecationReason="Create a Book instead" />
<operations>
</resource>
</resources>
owl:deprecated
annotation property will be added to the appropriate data structuredeprecated
property will be addedisDeprecated
and deprecationReason
properties will be added to the schemaarray $filters
The filters
option configures the filters (declared as services) available on the collection routes for the current resource.
<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\GetCollection;
#[GetCollection(filters: ['app.filters.book.search'])]
class Book
{
// ...
}
# api/config/api_platform/resources.yaml
resources:
App\Entity\Book:
- operations:
ApiPlatform\Metadata\GetCollection:
filters: ['app.filters.book.search']
<?xml version="1.0" encoding="UTF-8" ?>
<!-- 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>app.filters.book.search</filter>
</filters>
</operation>
</operations>
</resource>
</resources>
array $validationContext
The validationContext
option configure the context of validation for the current Operation.
You can, for instance, describe the validation groups that will be used :.
#[Put(validationContext: ['groups' => ['Default', 'putValidation']])]
#[Post(validationContext: ['groups' => ['Default', 'postValidation']])]
For more examples, read our guide on validation.
$input
$output
$mercure
string|bool $messenger
The messenger
option dispatches the current resource through the Message Bus.
<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\Post;
#[Post(messenger: true)]
class Book
{
// ...
}
# api/config/api_platform/resources.yaml
resources:
App\Entity\Book:
- operations:
ApiPlatform\Metadata\Post:
messenger: true
<?xml version="1.0" encoding="UTF-8" ?>
<!-- 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\Post" messenger=true />
</operations>
</resource>
</resources>
Note: when using messenger=true
on a Doctrine entity, the Doctrine Processor is not called. If you want it
to be called, you should decorate a built-in state processor
and implement your own logic.
Read how to use Messenger with an Input object.
bool $elasticsearch
int $urlGenerationStrategy
bool $read
bool $deserialize
bool $validate
bool $write
bool $serialize
bool $fetchPartial
bool $forceEager
int $priority
The priority helps with the order of operations when looping over a resource’s operations. It can be usefull when we loop over operations to find a matching IRI, although most of the use cases should be covered by the HttpOperation::itemUriTemplate or the ApiProperty::uriTemplate functionalities. Sort is ascendant: a lower priority comes first in the list.
string $name
$provider
$processor
ApiPlatform\Metadata\Parameters|array $parameters
array $extraProperties
Made with love by
Les-Tilleuls.coop can help you design and develop your APIs and web projects, and train your teams in API Platform, Symfony, Next.js, Kubernetes and a wide range of other technologies.
Learn more