Applying Filters to QueryParameter in unclear to me.

[etshy]

My need is simple : I would like to attach a SearchFilter to a QueryParameter.
I saw this example code that shows it

<?php
#[QueryParameter(key: ':property', filter: SearchFilter::class)]
class Book {
    public string $id;
    public string $title;
    public Author $author;
}

https://api-platform.com/docs/core/filters/#the-property-placeholder

So I tried something like that.

<?php
#[GetCollection(
    class: WrapperEntity::class,
    output: WrapperApiResource::class,
    provider: State\Provider\WrapperProvider::class,
    parameters: [
        'makes[]' => new QueryParameter(
            'makes[]',
            schema: [
                'type' => 'array',
                'items' => ['type' => 'string'],
            ],
            filter: SearchFilter::class,
            description: 'Make of the vehicle',
            properties: ['vehicle.make'],
            filterContext: [
                'properties' => [
                    'vehicle.make' => 'exact',
                ],
            ],
        ),
    ]
)]
final class WrapperApiResource

With that I thought I'd be able to link my queryParameter makes[] and automatically make it search on vehicle.make.
But thats doesn't seem to work. I dumped the QueryBuilder (in a custom Provider that calls collectionProvider to have automated filters etc.) and there is no parameter applied.

I'm a bit lost with that, I don't think it's a use case that complex that would need a custom filter so i wanted to avoid that but have I to make one (or a custom Doctrine Extension) ?

[soyuka]

It's quite hard to have working filters for all the use cases and in the end developers often just use a custom filter. We simplified a lot the approach with query parameters, a few fixes to your code:

• makes[] => makes (it's the query parameter name it should not hold brackets
• properties is useful for this classes properties, here you're trying to use a relation but by doing so API Platform has to find out the nature of the database relation, therefore probably needs a "join". If we do so automatically it'll lead to bad performances at some point. We're working on that at feat(doctrine): new iri search filters #7121 anyways. For now you can not use the SearchFilter like this with a QueryParameter (but it may work with ApiFilter although I don't recommend using it).
• don't change class it may have unwanted behavior
• try not to use output if you can, you resource should be the face of your API, we plug data into it.

<?php
#[GetCollection(
    // do not use this, please declare the ApiResource on the class you want
    // class: WrapperEntity::class,
    // This is "okay" but if you should prefer just having this class represent your API
    output: WrapperApiResource::class,
    provider: State\Provider\WrapperProvider::class,
    parameters: [
        'makes' => new QueryParameter(
            'makes[]',
            schema: [
                'type' => 'array',
                'items' => ['type' => 'string'],
            ],
            filter: SearchFilter::class,
            description: 'Make of the vehicle',
        ),
    ]
)]
final class WrapperEntity

use ApiPlatform\Doctrine\Orm\Filter\FilterInterface;


final class SearchFilter implements FilterInterface
{

    public function apply(QueryBuilder $queryBuilder, QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, ?Operation $operation = null, array $context = []): void
    {
        $queryBuilder->join('o.vehicle', 'v')->andWhere('v.make = :make')->setParameter('make', $context['parameter']->getValue());
    }

    // Avoid this, use OpenApiParameterFilterInterface and/or JsonSchemaFilterInterface if you need, by default we use the values on the parameters
    public function getDescription(string $resourceClass): array
    {
        return [];
    }

}

[etshy]

First thanks for all the hints !

• don't change class it may have unwanted behavior
• try not to use output if you can, you resource should be the face of your API, we plug data into it.

Yeah It was me trying to link my Doctrine Entity and my ApiResource classes, but I discovered the stateOption that can be used to do that (I don't think it is in api-platform docs though).

I ended up doing a customFilter (and my customProvider calling manually CollectionProvider so that the customFilter is called automatically, I'm no sure if there is a better way.)

//ApiResource
#[ApiResource(
    shortName: 'Wrapper',
    stateOptions: new Options(entityClass: WrapperEntity::class) // THAT ! so the CollectionProvider know I'm targetting a Doctrine Entity for my custom filter
)]
#[GetCollection(
    provider: WrapperProvider::class,
    parameters: [
        'make' => new QueryParameter(
            'make',
            filter: VehicleMakeFilter::class,
        ),
    ]
)]
final class WrapperApiResource
{

//Provider

use ApiPlatform\State\ProviderInterface;

final readonly class WrapperProvider implements ProviderInterface
{
    public function __construct(
        #[Autowire(service: 'api_platform.doctrine.orm.state.collection_provider')]
        private ProviderInterface $collectionProvider,
    ) {
    }

    public function provide(Operation $operation, array $uriVariables = [], array $context = []): object|array|null
    {
        if ($operation instanceof CollectionOperationInterface) {
            $entities = $this->collectionProvider->provide($operation, $uriVariables, $context); // will apply my different customFilters automatically
            // map entities to apiResources
            return $apiResources;
        }

        return $this->getItem($uriVariables['uid']);
    }

---

but it may work with ApiFilter although I don't recommend using it

I was sure I read that somewhere before but couldn't find it again !
Why is ApiFilter not recommended ?

I have another filter, on vehicle.price, and from the doc I read I have no idea how to filter on it without using an ApiFilter linked to my QueryParam (or customFilter obviously).
And I found the RangeFilter really fitting for my useCase.

Here is what I currently have for this price param.

#[ApiResource(
    shortName: 'Wrapper',
    stateOptions: new Options(entityClass: WrapperEntity::class)
)]
#[GetCollection(
    provider: WrapperProvider::class,
    parameters: [
        'price' => new QueryParameter(
            'price',
            filter: 'app_wrapper_numeric_filter',
            property: 'vehicle.price',
        ),
    ]
)]
#[ApiFilter(
    filterClass: RangeFilter::class,
    properties: ['vehicle.price'],
    alias: 'app_wrapper_numeric_filter'
)]
final class Wrapper
{

I couldn't make my price parameter filter anything without "binding" the #[ApiFilter] through the alias string.
Even using RangeFilter::class in the Parameter didn't work.

//This doesn't work to filter on vehicle.price
#[ApiResource(
    shortName: 'Wrapper',
    stateOptions: new Options(entityClass: WrapperEntity::class)
)]
#[GetCollection(
    provider: WrapperProvider::class,
    parameters: [
        'price' => new QueryParameter(
            'price',
            filter: RangeFilter::class,
            property: 'vehicle.price',
        ),
    ]
)]
final class Wrapper

Did I misunderstand/misuse something about Parameters ?
Are Parameters only for documentation, and you need to define an ApiFilter (or a custom one) to it ?

I wanted to try implementing my make parameter the same way but with SearchFilter, but if it's not recommended I guess I'll keep the customFilter ?

---

// Avoid this, use OpenApiParameterFilterInterface and/or JsonSchemaFilterInterface if you need, by default we use the values on the parameters
public function getDescription(string $resourceClass): array

So I should return empty array like your example ? getDescription is mandatory when using ApiPlatform\Doctrine\Orm\Filter\FilterInterface because it extends Metadata\FilterInterface.
What's the difference between getDescription from Metadata\FilterInterface, getSchema from JsonSchemaFilternterface and getOpenApiParameters from OpenApiParameterFilterInterface ?
As they're not documented in api-platform website (?) and don't have phpDoc explaining their uses, they seem kinda similar to each other.
I guess OpenApiParameterFilterInterface can describe everything OpenApi needs while JsonSchemaFilternterface contains only the schema (the type) ?

Sorry for all the questions, I find the documentation on filters/Parameters is really too vague ^^" (creating a custom filter is kinda easy though, just had to call manually CollecionProvider so it's applied automagically).

[soyuka]

Are Parameters only for documentation, and you need to define an ApiFilter (or a custom one) to it ?

Short answer yes. Defining an ApiFilter does two things: declare a filter Symfony service, add documentation.
The Parameter is a metadata-first approach and the filter is basically a simple callable (like I showed earlier). It's still compatible with services but as our current filters need some mandatory arguments it's hard to make them compatible (especially for the SearchFilter, see linked PR).

I'm sorry for the lack of documentation, best is to take a look at https://github.com/api-platform/core/tree/main/tests/Functional/Parameters and https://github.com/api-platform/core/blob/main/tests/Fixtures/TestBundle/Entity/FilteredRangeParameter.php

Why is ApiFilter not recommended ?

Because at some point we're going to deprecate its usage (with a BC layer, and in ~2 years) though when starting a new project you can use Parameters and therefore gain simplicity over filters and parameter usage. An ApiFilter has too much responsabilities. A Parameter splits this responsability: metadata-first approach. Then it can use a Filter to actually filter through SQL or whatever.
Also Parameters have a better integration with validation (parameter validation before that relied on the schema definition, now we're using constraints directly, if none are provided we use the schema to create constraints).

I guess OpenApiParameterFilterInterface can describe everything OpenApi needs while JsonSchemaFilternterface contains only the schema (the type) ?

yes, JsonSchema is for the json schema that describes the parameter. OpenApi also reuses this schema's definition if none is provided inside the parameter. You often just want to change your schema, our defaults are quite good for OpenApi. If the defaults are not what you expect please open an issue with your parameter and what you expect

As they're not documented in api-platform website (?) and don't have phpDoc explaining their uses, they seem kinda similar to each other.

PR welcome!

[etshy]

Thanks that explains a lot.
So, if I understand well, filters will still be there but only for filtering and params will do the metadata work, instead of filter doing everything ?
Because I stil didn't find how to filter using only Parameter.

That sounds more logical to me, define parameter for the docs then use a filter to effectively filter the value.

PR welcome!

I started apiPlatform just a few weeks ago, but I learned a bit of it by trying and digging the sources (about filters at least) so maybe I'll take an attentive look at the doc and add some things that needs more clarification.