doc(doctrine): document how to compute and sort a virtual field

[soyuka]

Q	A
Branch?	4.1
Tickets	N/a
License	MIT

This PR introduces the ability to use and filter on computed fields within API Platform, specifically for Doctrine entities.

Here's a configuration example with a filter and static functions :

use ApiPlatform\Doctrine\Orm\State\Options;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\QueryParameter;
use ApiPlatform\Tests\Fixtures\TestBundle\Filter\SortComputedFieldFilter;
use Doctrine\ORM\QueryBuilder;
use ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface;
use ApiPlatform\Metadata\Operation;

#[GetCollection(
    stateOptions: new Options(handleLinks: [self::class, 'handleLinks']),
    processor: [self::class, 'process'],
    write: true,
    parameters: [
        'sort[:property]' => new QueryParameter(
            filter: new SortComputedFieldFilter(),
            properties: ['totalQuantity']
        ),
    ]
)]
class Cart
{
    public static function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = [])
    {
        foreach ($data as &$value) {
            $cart = $value[0];
            $cart->totalQuantity = $value['totalQuantity'] ?? 0;
            $value = $cart;
        }

        return $data;
    }

    public static function handleLinks(QueryBuilder $queryBuilder, array $uriVariables, QueryNameGeneratorInterface $queryNameGenerator, array $context): void
    {
        $rootAlias = $queryBuilder->getRootAliases()[0] ?? 'o';
        $itemsAlias = $queryNameGenerator->generateParameterName('items');
        $queryBuilder->leftJoin(\sprintf('%s.items', $rootAlias), $itemsAlias)
            ->addSelect(\sprintf('COALESCE(SUM(%s.quantity), 0) AS totalQuantity', $itemsAlias))
            ->addGroupBy(\sprintf('%s.id', $rootAlias));
    }
}

use ApiPlatform\Doctrine\Orm\Filter\FilterInterface;
use ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface;
use ApiPlatform\Metadata\Operation;
use Doctrine\ORM\QueryBuilder;

class SortComputedFieldFilter implements FilterInterface
{
    public function apply(QueryBuilder $queryBuilder, QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, ?Operation $operation = null, array $context = []): void
    {
        if ($context['parameter']->getValue() instanceof ParameterNotFound) {
            return;
        }

        $queryBuilder->addOrderBy('totalQuantity', $context['parameter']->getValue()['totalQuantity'] ?? 'ASC');
    }
}

A new functional test (ComputedFieldTest.php) demonstrating the usage which will be transformed into a guide.

[dunglas]

Clever! We should really rename "handleLinks" if we use it like that, it's not related at all to links now :)

[soyuka]

Clever! We should really rename "handleLinks" if we use it like that, it's not related at all to links now :)

Maybe that we should add something like repositoryMethod to the stateOptions to hook at the call:

core/src/Doctrine/Orm/State/ItemProvider.php

Line 73 in 7c796de

$queryBuilder = $repository->createQueryBuilder('o');

It'd be even better and one could use the same query builder but still handle links on subresources.

[g-ra]

I suspect that the current solution has a drawback, how can we substitute the data of the current authorized user into this request?

for example, if we need to look at the total of only a multiple of the current authorized user

I think this problem will be solved if we switch to repository methods and not methods for getting in the entity itself

[soyuka]

so #7115 would be more appropriate? Can you share an example?