Feature Guide

A quick orientation block that answers the essential questions: what this feature does, how it works, why it matters, and the key concepts behind it.

What this does

Offset and cursor pagination out of the box — switch modes with a single query parameter.

Offset pagination

Current page window

Page 3 of 7 with 62 total products and 10 rows per page.

3 Current page

7 Total pages

62 Total rows

Name	Price
No results — seed data first.

← Prev Next →

PaginatedResult limit() offset() cursor pagination total count

Verified against Semitexa Ultimate 2026.09.19.1020

Pagination

Semitexa ORM repositories support both offset-based and cursor-based pagination through the same query API, switchable at runtime via a request parameter.

How it works

A handler reads mode, limit, and page from the payload, validates bounds (page >= 1, limit > 0 with an upper cap), computes offset = (page - 1) * limit, and calls findPage($limit, $offset) on the repository. The repository uses limit() and offset() on the query builder. Switching to cursor mode changes only the query strategy — the handler and repository interface stay identical. A countAll() call provides the total for page count computation, and the validated bounds keep offsets non-negative.

Why this matters

Offset pagination is simple but degrades on large datasets. Cursor pagination stays performant at scale. Having both available through the same repository contract means the choice can be deferred until the data size makes it matter, without rewriting handler logic.

1<?php23declare(strict_types=1);45namespace App\Application\Handler\Data;67use App\Application\Payload\Data\ProductCatalogPayload;8use App\Application\Resource\Page\ProductCatalogResource;9use App\Domain\Catalog\ProductReadRepositoryInterface;10use Semitexa\Core\Attribute\AsPayloadHandler;11use Semitexa\Core\Attribute\InjectAsReadonly;12use Semitexa\Core\Contract\TypedHandlerInterface;1314#[AsPayloadHandler(payload: ProductCatalogPayload::class, resource: ProductCatalogResource::class)]15final class ProductCatalogHandler implements TypedHandlerInterface16{17    #[InjectAsReadonly]18    protected ProductReadRepositoryInterface $products;1920    public function handle(ProductCatalogPayload $payload, ProductCatalogResource $resource): ProductCatalogResource21    {22        return $resource->fromProducts($this->products->findForCatalog($payload));23    }24}25

<?php

declare(strict_types=1);

namespace App\Application\Handler\Data;

use App\Application\Payload\Data\ProductCatalogPayload;
use App\Application\Resource\Page\ProductCatalogResource;
use App\Domain\Catalog\ProductReadRepositoryInterface;
use Semitexa\Core\Attribute\AsPayloadHandler;
use Semitexa\Core\Attribute\InjectAsReadonly;
use Semitexa\Core\Contract\TypedHandlerInterface;

#[AsPayloadHandler(payload: ProductCatalogPayload::class, resource: ProductCatalogResource::class)]
final class ProductCatalogHandler implements TypedHandlerInterface
{
    #[InjectAsReadonly]
    protected ProductReadRepositoryInterface $products;

    public function handle(ProductCatalogPayload $payload, ProductCatalogResource $resource): ProductCatalogResource
    {
        return $resource->fromProducts($this->products->findForCatalog($payload));
    }
}

1<?php23declare(strict_types=1);45namespace App\Application\Db\Repository;67use App\Application\Db\Model\ProductResource;8use App\Domain\Catalog\ProductReadRepositoryInterface;910final class ProductRepository implements ProductReadRepositoryInterface11{12    /**13     * @return list<ProductResource>14     */15    public function findForCatalog(object $criteria): array16    {17        return [];18    }19}20

<?php

declare(strict_types=1);

namespace App\Application\Db\Repository;

use App\Application\Db\Model\ProductResource;
use App\Domain\Catalog\ProductReadRepositoryInterface;

final class ProductRepository implements ProductReadRepositoryInterface
{
    /**
     * @return list<ProductResource>
     */
    public function findForCatalog(object $criteria): array
    {
        return [];
    }
}