docs(filters): document enhanced QueryParameter syntax on old filters

[vinceAmstoutz]

Completes #2203

And here to avoid these issues:

• ExistsFilter: properties must be associative array when used with QueryParameter, but not with ApiFilter core#7483
• With QueryParameter, it is not possible to set multiple filters for the same property core#7493
• :property key cannot be used in SearchFilter (Symfony only) core#7495

Main changes:

• Added examples for Date, Boolean, Numeric, Range, Exists, and Order filters using the QueryParameter approach. Included notes on configuring custom strategies, handling null values, and enabling filters for nested properties.
• Add other warnings to promote the QueryParameter attribute over ApiFilter, as the latter is deprecated and scheduled for removal in API Platform 5.0.
• Fix several typos

[ttskch]

@vinceAmstoutz

Thank you for improving the documentation. Please allow me to share my insights.

In v4.2.3, when setting filters using QueryParameter, declaring the key using the associative array index in the parameters argument is not possible, resulting in a 500 error with the message "A Parameter should have a key." Instead, you must use the key argument of QueryParameter.

- parameters: [
-     'search[:property]' => new QueryParameter(/* ... */)
+ parameters: [
+     new QueryParameter(key: 'search[:property]', /* ... */)

Also, directly passing a filter instance to the filter argument still mostly does not work correctly. Defining the filter service in services.yaml and passing the service ID works correctly in most cases (excluding #7493, #7494, and #7495).

For example, I have observed the following issues in my environment.

new QueryParameter(key: 'date', filter: new DateFilter())

• date[<after|before|strictly_after|strictly_before>] is not output in OpenAPI or Hydra's search.template, only date is output.
• Searching works.

new QueryParameter(key: 'id', filter: new RangeFilter())

• id[<lt|gt|lte|gte|between>] is not output in OpenAPI or Hydra's search.template, only id is output.
• Searching works.

new QueryParameter(key: ':property', filter: new PartialSearchFilter(), properties: ['title', 'note'])

• The query parameter :property is output in OpenAPI instead of title or note.
• {?title,note} is correctly output in Hydra's search.template.
• Searching does not work even when requesting with ?title={query} or ?note={query}.

new QueryParameter(key: 'title', filter: new PartialSearchFilter(), property: 'title')

• Both OpenAPI and Hydra output correctly, and searching works.
• However, in the case of BooleanFilter, NumericFilter, RangeFilter, etc., if the key is the property name itself, it works even if the property argument is omitted, but in the above case, omitting property causes an error because $property becomes null here.

new QueryParameter(key: 'comments.content', filter: new PartialSearchFilter(), property: 'comments.content')

• Nested properties are not parsed, and an error such as Error: Class App\\Entity\\Foo has no field or association named comments.content occurs at the DB layer.

new QueryParameter(key: 'exists[:property]', filter: new ExistsFilter(), properties: ['content', 'comments'])

• In OpenAPI... - The query parameter exists[:property] is output instead of exists[content] or exists[comments].
• Hydra's search.template correctly outputs {?exists[content],exists[comments]}.
• Searching does not work even when requesting with ?exists[content]=true or ?exists[comments]=false.
• Defining the following two parameters instead makes it work completely:

new QueryParameter(key: 'exists[content]', filter: new ExistsFilter(), property: 'content'),
new QueryParameter(key: 'exists[comments]', filter: new ExistsFilter(), property: 'comments'),

new QueryParameter(key: 'order[:property]', filter: new OrderFilter(), properties: ['id', 'date'])

• The query parameter order[:property] is output in OpenAPI instead of order[id] or order[date].
• Hydra's search.template correctly outputs {?order[id],order[date]}.
• Searching does not work even when requesting with ?order[id]=asc or ?order[date]=desc.
• Defining the following two parameters instead makes it work completely:

new QueryParameter(key: 'order[id]', filter: new OrderFilter(), property: 'id'),
new QueryParameter(key: 'order[date]', filter: new OrderFilter(), property: 'date'),

[aegypius]

polish: I made a bunch of suggestions regarding spelling.‏

[soyuka]

1. parameters argument using associative array vs. key argument:
   When you define parameters using parameters: ['search[:property]' => new QueryParameter()], the Parameters collection internally uses 'search[:property]' as a key for the Parameter object. However, the QueryParameter object itself (the new QueryParameter()) initially has key: null. The error "A Parameter should have a key" likely occurs if another part of the system attempts to access $parameter->getKey() before the ApiPlatform\Metadata\Resource\Factory\ParameterResourceMetadataCollectionFactory::getDefaultParameters method has a chance to explicitly call $parameter = $parameter->withKey($key) to set the key on the Parameter object itself.
   Resolution: Your observation is correct. Always use new QueryParameter(key: 'search[:property]', /* ... */) to explicitly set the key on the QueryParameter object during its construction.

2. Directly passing filter instance vs. service ID:
   The ApiPlatform\Doctrine\Orm\Extension\ParameterExtension and ApiPlatform\Doctrine\Odm\Extension\ParameterExtension (and ApiPlatform\Laravel\Eloquent\Extension\FilterQueryExtension) are designed to handle both filter instances and service IDs. The relevant code snippets (e.g., in ParameterExtension::applyFilter):

   // ...
   $filter = match (true) {
       $filterId instanceof FilterInterface => $filterId,
       \is_string($filterId) && $this->filterLocator->has($filterId) => $this->filterLocator->get($filterId),
       default => null,
   };
   // ...

   This match statement explicitly supports $filterId instanceof FilterInterface.
   The issue you're observing stems from how these directly instantiated filters are configured. When a filter is retrieved as a service, its constructor dependencies (like ManagerRegistry, LoggerInterface, or an initial $properties array) are automatically injected by the Dependency Injection Container. When you use new DateFilter(), these dependencies default to null.
   While ApiPlatform\Doctrine\Common\ParameterExtensionTrait::configureFilter attempts to set ManagerRegistry and LoggerInterface if the filter implements the AwareInterface (which AbstractFilter does), and also sets $properties for PropertyAwareFilterInterface, the initial state of the filter and how its getDescription method (ExistsFilterTrait::getDescription, DateFilterTrait::getDescription) uses a potentially null internal $properties array can lead to incorrect behavior, especially in OpenAPI/Hydra documentation generation or when filters expect specific property configurations.
   Resolution: It's best practice to define your filters as services in your services.yaml and pass their service IDs. This ensures proper dependency injection and consistent behavior.

About the other issues we refactored the code for the :property placeholder it should solve most of the problems, note that now there's a key for parameters and a property for each of these parameters.

[soyuka]

Many thanks for the work on this! I'll fix linting issues in another PR!

[ttskch]

@soyuka

#2227 (comment)

2. Directly passing filter instance vs. service ID:

Thank you for the detailed explanation.

I finally understand the conditions for reproduction. I declare parameters as follows in the apiResource() method instead of using class attributes. This was the direct cause.

#[ORM\Entity(repositoryClass: ArticleRepository::class)]
class Article
{
    // ...

    public static function apiResource(): array
    {
        return [
            new GetCollection(
                parameters: [
                    new QueryParameter(filter: new DateFilter(),　key: ':property',　properties: ['date']),
                ],
            ),
        ];
    }
}

If we declare it as follows using class attributes, the output will be correct.

#[GetCollection(
    parameters: [
        new QueryParameter(filter: new DateFilter(),　key: ':property',　properties: ['date']),
    ],
)]
#[ORM\Entity(repositoryClass: ArticleRepository::class)]
class Article
{
    // ...
}

Incidentally, even if we declare it as follows using a PHP resource file, OpenAPI/Hydra still does not output correctly.

<?php

use ApiPlatform\Doctrine\Orm\Filter\DateFilter;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\Operations;
use ApiPlatform\Metadata\QueryParameter;
use App\Entity\Article;

return (new ApiResource())
    ->withClass(Article::class)
    ->withOperations(new Operations([
        new GetCollection(
            parameters: [
                new QueryParameter(filter: new DateFilter(),　key: ':property',　properties: ['date']),
            ],
        ),
    ]))
;

Do you know what the cause is?

[ttskch]

@soyuka At api-platform/core#7654 and api-platform/core#7655, I have exhaustively summarized the filter-related bugs I'm aware of in the Issues. Apologies for the trouble, but please check them.