Allow to set an ApiFilter as required or not

[llupa]

While trying to setup a filter on GetCollection I stumbled across an interesting case. A quick recap of my setup is as follows:

public class Category
{
    //...
}

#[ApiResource]
public class Item
{
    #[ORM\ManyToOne(targetEntity: Category::class)]
    #[ApiProperty(required: true)]
    #[ApiFilter(SearchFilter::class)]
    private Category $category;
}

This setup, works as expected and documented. But, when I tried to make the ?category or ?category[] query parameter as mandatory (it is for my use-case) I noticed that it was not possible to do.

I was looking at the fields option for ApiResource and at first I thought I needed a more verbose connection between my resource and filter. I tried to give the ApiFilter a custom id and put it under filters of the ApiResource attribute but it was still not working. After some digging around I found that the ApiPlatform\Doctrine\Common\Filter\SearchFilterTrait has the following code block:

// just for my association case, works the same for direct property
if ($metadata->hasAssociation($field)) {
    $filterParameterNames = [
        $propertyName,
        $propertyName.'[]',
    ];

    foreach ($filterParameterNames as $filterParameterName) {
        $description[$filterParameterName] = [
            'property' => $propertyName,
            'type' => 'string',
            'required' => false, // <---! hard-coded --->
            'strategy' => self::STRATEGY_EXACT,
            'is_collection' => str_ends_with((string) $filterParameterName, '[]'),
        ];
    }
}

I still thought, maybe there is some black magic happening elsewhere, because I saw queryParameterValidationEnabled as an option, and the validators list has Required constraint. So I proceeded to adjust my config as follows:

#[ApiResource(queryParameterValidationEnabled: true)]
public class Item
{
    #[ORM\ManyToOne(targetEntity: Category::class)]
    #[ApiProperty(required: true)]
    #[ApiFilter(SearchFilter::class)]
    private Category $category;
}

It still did not work. The ApiPlatform\Symfony\EventListener\QueryParameterValidateListener was working correctly and the config from above was hooking things accordingly. I then dug deeper into Required and found:

if (!($filterDescription['required'] ?? false)) {
  return [];
}

Ok, this makes sense, the required attribute is never set to true so this validator always passes. I did my best to make sure if another place is supposed to set this, but I did not find anything.

I then created a POC and named it RequiredSearchFilter, with its own RequiredSearchFilterTrait. (genius I know)
In here I hardcoded the required to true just to see if it would work, and I stumbled to the next issue (and last). The filter query params are now both required ?category and ?category[]. So, I just added an allowMultiple flag to my POC and made some minimal changes to make sure that when a filter is required it has to either allow or disallow multi-values.

It seems to be working fine and the rest of API Platform plays well with it.

Is this something worth considering to make it part of the Core project? Should I open a proposal PR?

Edit 20.09.2023:
After some deliberation with the team, in our case we transformed this entity as a subresource. The mandatory query parameters that equates to a relationship over another entity was begging for this, and it works well for us. Maybe this can be a good solution for others facing this same situation.

The discussion stays the same if you have Enum type fields, or other logic that is not a relationship.