strictQueryParameterValidation blocks pagination parameters

[jannes-io]

API Platform version(s) affected: 4.3.4

Description

When enabling defaults.strictQueryParameterValidation in global config:

#config/packages/api-platform.yaml
api_platform:
    defaults:
        strictQueryParameterValidation: true
        parameters:
            # Some of our own global parameters, not sure if this might be related that we also define more params
            ApiPlatform\Metadata\QueryParameter:
                key: '_lang'
                required: false
                description: '2 letter language code, for example EN. By default, the primary language is used.'

It does not automatically whitelist the pagination query parameters for GetCollection operations. The openapi docs do include the pagination parameters, so they are definitely added to the operation, but for the parameter validation, they are not included.

How to reproduce
Enable strictQueryParameterValidation, then try to do a GetCollection operation with pagination parameters. Result is 400:

"title": "Parameter not supported",
"detail": "Parameter \"page\" not supported",
"description": "Parameter \"page\" not supported"

Possible Solution
Add the pagination parameters to the operation before query parameter validation.

#8544

Additional Context

[jannes-io]

Note

This comment was auto-generated by AI after an investigation

I did some digging into api-platform/core (branch 4.3, confirmed reproducing on v4.3.4) and found two distinct issues stacking on top of each other:

1. Pagination parameters are never registered in the Parameter/Parameters system at all

The strict-validation check lives in ParameterProvider::provide() (src/State/Provider/ParameterProvider.php:57-70): it builds $keys from $operation->getParameters() and throws ParameterNotSupportedException for any query key not in that list.

However, page/itemsPerPage/pagination/partial are never turned into ApiPlatform\Metadata\QueryParameter objects anywhere in core. State\Pagination\Pagination::getPage()/getLimit() reads them straight out of $context['filters']/the request query string (src/State/Pagination/Pagination.php), completely bypassing the Parameters whitelist. The only place these keys become "parameters" is OpenApi\Factory\OpenApiFactory.php:825-876 — but that's the unrelated ApiPlatform\OpenApi\Model\Parameter, used purely for Swagger docs. That's why the OpenAPI spec shows them but validation rejects them.

So GetCollection + strictQueryParameterValidation: true rejects pagination params unconditionally, with or without any custom defaults.parameters — this reproduces on a bare GetCollection with no other config.

2. defaults.parameters silently disables the one fallback that partially masks this

There's an existing fallback in Validator\Metadata\Resource\Factory\ParameterValidationResourceMetadataCollectionFactory::addFilterValidation(), gated by 0 === $parameters->count() (ParameterValidationResourceMetadataCollectionFactory.php:57). When an operation has zero declared parameters, it auto-converts each FilterInterface filter into a QueryParameter, whitelisting filter-based query keys.

The global api_platform.defaults.parameters config (wired at Symfony/Bundle/DependencyInjection/ApiPlatformExtension.php:414 → validator.php:35-41) gets merged into every operation's Parameters unconditionally, before that count() === 0 check runs. So as soon as you declare even one global default parameter (e.g. our _lang QueryParameter), every operation's parameter count becomes ≥ 1, the addFilterValidation() fallback is skipped, and any filter-derived query keys that were previously implicitly whitelisted now 400 too. (Note: PaginationExtension isn't a FilterInterface, so this fallback never covered pagination anyway — this is a compounding, separate bug.)

Suggested fix direction

Pagination parameters need to be explicitly registered as QueryParameter objects on GetCollection operations (respecting paginationEnabled/paginationClientEnabled/etc.) before ParameterProvider's strict check runs — similar to how OpenApiFactory already builds their names/schema, just wired into the actual Parameters collection instead of only the OpenAPI model. Separately, ParameterValidationResourceMetadataCollectionFactory's 0 === $parameters->count() guard should probably run before global-default merging, or be reconsidered entirely, since global defaults shouldn't silently opt every operation out of filter-based whitelisting.

[jannes-io]

Done in d59d95d