Add pagination to a list endpoint

use apivalk\apivalk\Router\Route\Pagination\Pagination;
use apivalk\apivalk\Router\Route\Route;

// Page pagination — ?page=1&limit=20
Route::get('/api/v1/animals')
    ->pagination(Pagination::page()->setMaxLimit(50));

// Offset pagination — ?offset=40&limit=20
Route::get('/api/v1/animals')
    ->pagination(Pagination::offset()->setMaxLimit(50));

// Cursor pagination — ?cursor=abc&limit=20
Route::get('/api/v1/animals')
    ->pagination(Pagination::cursor()->setMaxLimit(50));

public function __invoke(ApivalkRequestInterface $request): AbstractApivalkResponse
{
    $paginator = $request->paginator(); // PagePaginator

    $page  = $paginator->getPage();   // int — 1-based
    $limit = $paginator->getLimit();  // int — capped by setMaxLimit

    $rows  = $this->animals->findPage(($page - 1) * $limit, $limit);
    $total = $this->animals->count();
    $totalPages = (int)\ceil($total / $limit);

    $response = new ListAnimalsResponse($rows);
    $response->setPaginationResponse(
        new PagePaginationResponse(
            $page,
            $limit,
            $page < $totalPages,
            $totalPages
        )
    );

    return $response;
}

$paginator = $request->paginator(); // OffsetPaginator
$rows = $this->animals->findRange($paginator->getOffset(), $paginator->getLimit());
$total = $this->animals->count();

$response->setPaginationResponse(
    new OffsetPaginationResponse(
        $paginator->getLimit(),
        $paginator->getOffset(),
        $paginator->getOffset() + $paginator->getLimit() < $total,
        $total
    )
);

$paginator = $request->paginator(); // CursorPaginator
$rows = $this->animals->findAfter($paginator->getCursor(), $paginator->getLimit());

$nextCursor = \end($rows) !== false ? \end($rows)['id'] : null;

$response->setPaginationResponse(
    new CursorPaginationResponse(
        $paginator->getLimit(),
        $paginator->getCursor(),
        $nextCursor,
        $nextCursor !== null
    )
);

{
  "data": [/* ... */],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "has_more": true,
    "total_pages": 5
  }
}

/**
 * @extends AbstractListResourceController<AnimalResource>
 */
final class ListAnimalController extends AbstractListResourceController
{
    public static function getResourceClass(): string
    {
        return AnimalResource::class;
    }

    public static function pagination(): ?Pagination
    {
        return Pagination::page()->setMaxLimit(50);
    }

    // __invoke() reads $request->paginator() as normal
}