How to keep pagination information when using output DTOs?

[bpolaszek]

Hello there,

Using output DTOs in API-Platform 2.x could be done by using data transformers, meaning we could transform each returned item from the persistence layer to a representation meant for output.

In API-Platform 3.x, this can be achieved by some sort of overriding/decorating the persistence layer itself, by creating a state provider.

This raises a question we didn't need to ask in API-Platform 2.x, and which is not covered by the documentation: how do we keep pagination information when using different representations?

TL; DR:

hydra:totalItems is lost as soon as we use output DTOs.

Reproduction

Consider that resource:

namespace App\Entity;

use ApiPlatform\Metadata\GetCollection;
use App\State\BookCollectionProvider;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
#[GetCollection(
    output: BookOutput::class,
    provider: BookCollectionProvider::class,
)]
class Book
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    public ?int $id = null;

    #[ORM\Column(length: 255)]
    public ?string $name = null;
}

with the following representation:

namespace App\Entity;

final class BookOutput
{
    public ?int $id = null;
    public ?string $name = null;
    public string $isbn = 'some-hardcoded-isbn';
}

And its provider:

namespace App\State;

use ApiPlatform\Doctrine\Orm\State\CollectionProvider;
use ApiPlatform\Metadata\Operation;
use ApiPlatform\State\ProviderInterface;
use App\Entity\BookOutput;
use Generator;

final readonly class BookCollectionProvider implements ProviderInterface
{
    public function __construct(
        private CollectionProvider $collectionProvider,
    ) {
    }

    public function provide(Operation $operation, array $uriVariables = [], array $context = []): Generator
    {
        $results = $this->collectionProvider->provide($operation, $uriVariables, $context);

        foreach ($results as $book) {
            $output = new BookOutput();
            $output->id = $book->id;
            $output->name = $book->name;

            yield $output;
        }
    }
}

By returning a generator which will map each Book to a BookOutput, API-Platform won't return the hydra:totalItems property anymore.
What's the best practice to handle this?

[norkunas]

You can preserve hydra:totalItems with ArrayPaginator:

namespace App\State;

use ApiPlatform\Doctrine\Orm\State\CollectionProvider;
use ApiPlatform\Metadata\Operation;
use ApiPlatform\State\Pagination\ArrayPaginator
use ApiPlatform\State\Pagination\Pagination;
use ApiPlatform\State\ProviderInterface;
use App\Entity\BookOutput;

final readonly class BookCollectionProvider implements ProviderInterface
{
    public function __construct(
        private CollectionProvider $collectionProvider,
        private Pagination $pagination,
    ) {
    }

    public function provide(Operation $operation, array $uriVariables = [], array $context = []): ArrayPaginator
    {
        $results = $this->collectionProvider->provide($operation, $uriVariables, $context);
        $books = [];

        foreach ($results as $book) {
            $output = new BookOutput();
            $output->id = $book->id;
            $output->name = $book->name;

            $books[] = $output;
        }

        return new ArrayPaginator($books, $this->pagination->getOffset($operation, $context), $this->pagination->getLimit($operation, $context));
    }
}

Also you could try ApiPlatform\State\Pagination\TraversablePaginator to check if it suits you

[bpolaszek]

Hey @norkunas, nice to see you (meilisearch fellow here)!

It works! I didn't notice the existence of this class. After investigation it is briefly mentioned in the docs but this would definitely deserve an example like the one you provided!

Thanks a lot,
Ben