Add nulls_always_first and nulls_always_last to nulls_comparison

[famoser]

Q	A
Branch?	main
Bug fix?	no
New feature?	yes
Deprecations?	no
Tickets	(no issue)
License	MIT
Doc PR	api-platform/docs#1297

Add nulls_always_first and nulls_always_last to nulls_comparison of the OrderFilter. This allows to always sort in null values first or last, independent of the current order.

This is useful for UIs with optional fields; displaying empty fields might not be useful to the user. Sorting these always last, independent of the chosen ordering, is the expected behavior.

Given something like

/**
 * @ApiResource(order={"number": "ASC"})
 * @ApiFilter(
 *     OrderFilter::class,
 *     properties={
 *         "number": {
 *             "nulls_comparison": OrderFilter::NULLS_ALWAYS_LAST
 *         }
 *     }
 * )
 */

will result in an ordering like

1
4
NULL
NULL

[famoser]

Pinging the maintainers as described in CONTRIBUTING.md (only those listed as one of the authors of the modified files):
@dunglas
@theofidry

Notes:

• The failing unit test seems to be unrelated to this patch
• There might be a unit tests missing for mongoDB: ApiPlatform\Core\Tests\Bridge\Doctrine\MongoDbOdm\Filter\OrderFilterTest; although no unit test seems to fail because of it.
• Do I need to / am allowed to add myself as one of the authors of the modified files?

I am actually using this functionality in a "real-world" project (https://github.com/mangelio/web/), so in my opinion, there exists an actual use case. Thanks for considering to integrate it into the core.

[alanpoulain]

I think it would be simpler if you reused the direction map instead (clearer and no need to add specific code).

[famoser]

Done 👍🏻

[alanpoulain]

Do you want to try to fix the MongoDB tests too?

[famoser]

I seem to have succeeded. See comment below.

[alanpoulain]

Hello, thank you for this PR!
The use case seems legit to me too.
I don't know why but the MongoDB unit tests are not executed anymore, but I think they are failing. I will fix it.
I don't think you need to add yourself as the author. Generally, it's done when the file is created for the first time, or when a lot of code is changed.

[alanpoulain]

Rebased to show the MongoDB issue.

[famoser]

The MongoDB tests are also passing now.

I have to be honest: I am not sure I understood the MongoDB tests specification 100%. Could you please quickly glance over it for a plausibility check?

[alanpoulain]

Nice work! Thank you @famoser.