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

Compose type-safe queries with a fluent API — no raw SQL, no magic strings.

Query Builder

Compiled query example

The repository composes fluent constraints with typed column references, then materializes a filtered collection.

10 Returned rows

10 Limit

$products = $orm->repository(DemoProductResource::class, DemoProduct::class)
    ->query()
    ->limit(10)
    ->fetchAllAs(DemoProduct::class, $orm->getMapperRegistry());

Name	Price	Status
Air Purifier	$149.99	active
Domain-Driven Design	$54.99	active
Ergonomic Chair	$299.99	active
Foam Roller	$29.99	active
Head First Design Patterns	$49.99	active

ResourceModelQuery where() orderBy() limit() fetchAllAs() fetchOneAs()

Verified against Semitexa Ultimate 2026.09.19.1020

Query Builder

The Semitexa ORM exposes a fluent query API that compiles type-safe constraints against ResourceModel column references without raw SQL.

How it works

A repository opens a query with ->query() on the ORM repository instance, chains where(), orderBy(), and limit() calls using typed ResourceModel::column() references and Operator / Direction enums, then materializes results with fetchAllAs() or fetchOneAs(). The result is a concrete typed collection — no magic arrays.

Why this matters

Raw SQL strings and magic column name literals are the most common source of silent query bugs. Typed column references catch rename mismatches at boot, and the fluent API keeps the query shape visible in code review without losing flexibility for complex filtering or ordering needs.

1<?php23declare(strict_types=1);45namespace Examples\Orm\QueryBuilder;67use Semitexa\Core\Attribute\InjectAsReadonly;8use Semitexa\Demo\Application\Db\MySQL\Model\DemoProductResource;9use Semitexa\Demo\Domain\Model\DemoProduct;10use Semitexa\Orm\Attribute\AsRepository;11use Semitexa\Orm\Query\Direction;12use Semitexa\Orm\Query\Operator;1314#[AsRepository]15final class ProductReadRepository16{17    #[InjectAsReadonly]18    protected ProductQueryBuilder $queryBuilder;1920    public function findActivePage(int $limit = 12, int $offset = 0): array21    {22        return $this->queryBuilder23            ->map(24                $this->queryBuilder25                    ->new()26                    ->where(DemoProductResource::column('status'), Operator::Equals, 'active')27                    ->whereNull(DemoProductResource::column('deletedAt'))28                    ->orderBy(DemoProductResource::column('createdAt'), Direction::Desc)29                    ->limit($limit)30                    ->offset($offset),31            );32    }3334    public function searchCatalog(string $term, ?float $maxPrice = null): array35    {36        $query = $this->queryBuilder37            ->new()38            ->where(DemoProductResource::column('name'), Operator::Like, '%' . $term . '%')39            ->where(DemoProductResource::column('status'), Operator::Equals, 'active')40            ->orderBy(DemoProductResource::column('name'), Direction::Asc)41            ->limit(20);4243        if ($maxPrice !== null) {44            $query->where(DemoProductResource::column('price'), Operator::LessThanOrEquals, $maxPrice);45        }4647        return $this->queryBuilder->map($query);48    }4950    public function findOneByName(string $name): ?DemoProduct51    {52        return $this->queryBuilder53            ->one(54                $this->queryBuilder55                    ->new()56                    ->where(DemoProductResource::column('name'), Operator::Equals, $name)57                    ->where(DemoProductResource::column('status'), Operator::Equals, 'active'),58            );59    }60}61

<?php

declare(strict_types=1);

namespace Examples\Orm\QueryBuilder;

use Semitexa\Core\Attribute\InjectAsReadonly;
use Semitexa\Demo\Application\Db\MySQL\Model\DemoProductResource;
use Semitexa\Demo\Domain\Model\DemoProduct;
use Semitexa\Orm\Attribute\AsRepository;
use Semitexa\Orm\Query\Direction;
use Semitexa\Orm\Query\Operator;

#[AsRepository]
final class ProductReadRepository
{
    #[InjectAsReadonly]
    protected ProductQueryBuilder $queryBuilder;

    public function findActivePage(int $limit = 12, int $offset = 0): array
    {
        return $this->queryBuilder
            ->map(
                $this->queryBuilder
                    ->new()
                    ->where(DemoProductResource::column('status'), Operator::Equals, 'active')
                    ->whereNull(DemoProductResource::column('deletedAt'))
                    ->orderBy(DemoProductResource::column('createdAt'), Direction::Desc)
                    ->limit($limit)
                    ->offset($offset),
            );
    }

    public function searchCatalog(string $term, ?float $maxPrice = null): array
    {
        $query = $this->queryBuilder
            ->new()
            ->where(DemoProductResource::column('name'), Operator::Like, '%' . $term . '%')
            ->where(DemoProductResource::column('status'), Operator::Equals, 'active')
            ->orderBy(DemoProductResource::column('name'), Direction::Asc)
            ->limit(20);

        if ($maxPrice !== null) {
            $query->where(DemoProductResource::column('price'), Operator::LessThanOrEquals, $maxPrice);
        }

        return $this->queryBuilder->map($query);
    }

    public function findOneByName(string $name): ?DemoProduct
    {
        return $this->queryBuilder
            ->one(
                $this->queryBuilder
                    ->new()
                    ->where(DemoProductResource::column('name'), Operator::Equals, $name)
                    ->where(DemoProductResource::column('status'), Operator::Equals, 'active'),
            );
    }
}

1<?php23declare(strict_types=1);45namespace Examples\Orm\QueryBuilder;67use Semitexa\Core\Attribute\InjectAsReadonly;8use Semitexa\Demo\Application\Db\MySQL\Model\DemoProductResource;9use Semitexa\Demo\Domain\Model\DemoProduct;10use Semitexa\Orm\Attribute\AsRepository;11use Semitexa\Orm\Query\Direction;12use Semitexa\Orm\Query\Operator;1314#[AsRepository]15final class ProductAdminRepository16{17    #[InjectAsReadonly]18    protected ProductQueryBuilder $queryBuilder;1920    public function findDraftsForTenant(string $tenantId): array21    {22        return $this->queryBuilder23            ->map(24                $this->queryBuilder25                    ->new()26                    ->forTenant($tenantId)27                    ->where(DemoProductResource::column('status'), Operator::Equals, 'draft')28                    ->includeSoftDeleted()29                    ->orderBy(DemoProductResource::column('updatedAt'), Direction::Desc)30                    ->limit(50),31            );32    }3334    public function findWithoutCategory(string $tenantId): array35    {36        return $this->queryBuilder37            ->map(38                $this->queryBuilder39                    ->new()40                    ->forTenant($tenantId)41                    ->whereNull(DemoProductResource::column('categoryId'))42                    ->whereNotNull(DemoProductResource::column('createdAt'))43                    ->orderBy(DemoProductResource::column('name'), Direction::Asc),44            );45    }4647    public function findMostExpensiveForTenant(string $tenantId): ?DemoProduct48    {49        return $this->queryBuilder50            ->one(51                $this->queryBuilder52                    ->new()53                    ->forTenant($tenantId)54                    ->where(DemoProductResource::column('status'), Operator::Equals, 'active')55                    ->orderBy(DemoProductResource::column('price'), Direction::Desc)56                    ->limit(1),57            );58    }59}60

<?php

declare(strict_types=1);

namespace Examples\Orm\QueryBuilder;

use Semitexa\Core\Attribute\InjectAsReadonly;
use Semitexa\Demo\Application\Db\MySQL\Model\DemoProductResource;
use Semitexa\Demo\Domain\Model\DemoProduct;
use Semitexa\Orm\Attribute\AsRepository;
use Semitexa\Orm\Query\Direction;
use Semitexa\Orm\Query\Operator;

#[AsRepository]
final class ProductAdminRepository
{
    #[InjectAsReadonly]
    protected ProductQueryBuilder $queryBuilder;

    public function findDraftsForTenant(string $tenantId): array
    {
        return $this->queryBuilder
            ->map(
                $this->queryBuilder
                    ->new()
                    ->forTenant($tenantId)
                    ->where(DemoProductResource::column('status'), Operator::Equals, 'draft')
                    ->includeSoftDeleted()
                    ->orderBy(DemoProductResource::column('updatedAt'), Direction::Desc)
                    ->limit(50),
            );
    }

    public function findWithoutCategory(string $tenantId): array
    {
        return $this->queryBuilder
            ->map(
                $this->queryBuilder
                    ->new()
                    ->forTenant($tenantId)
                    ->whereNull(DemoProductResource::column('categoryId'))
                    ->whereNotNull(DemoProductResource::column('createdAt'))
                    ->orderBy(DemoProductResource::column('name'), Direction::Asc),
            );
    }

    public function findMostExpensiveForTenant(string $tenantId): ?DemoProduct
    {
        return $this->queryBuilder
            ->one(
                $this->queryBuilder
                    ->new()
                    ->forTenant($tenantId)
                    ->where(DemoProductResource::column('status'), Operator::Equals, 'active')
                    ->orderBy(DemoProductResource::column('price'), Direction::Desc)
                    ->limit(1),
            );
    }
}

1<?php23declare(strict_types=1);45namespace Examples\Orm\QueryBuilder;67use Semitexa\Core\Attribute\InjectAsReadonly;8use Semitexa\Demo\Application\Db\MySQL\Model\DemoProductResource;9use Semitexa\Demo\Domain\Model\DemoProduct;10use Semitexa\Orm\OrmManager;11use Semitexa\Orm\Query\ResourceModelQuery;12use Semitexa\Orm\Repository\DomainRepository;1314final class ProductQueryBuilder15{16    #[InjectAsReadonly]17    protected ?OrmManager $orm = null;1819    private ?DomainRepository $repository = null;2021    public function new(): ResourceModelQuery22    {23        return $this->repository()->query();24    }2526    public function map(ResourceModelQuery $query): array27    {28        /** @var list<DemoProduct> */29        return $query->fetchAllAs(DemoProduct::class, $this->orm()->getMapperRegistry());30    }3132    public function one(ResourceModelQuery $query): ?DemoProduct33    {34        /** @var DemoProduct|null */35        return $query->fetchOneAs(DemoProduct::class, $this->orm()->getMapperRegistry());36    }3738    private function repository(): DomainRepository39    {40        return $this->repository ??= $this->orm()->repository(41            DemoProductResource::class,42            DemoProduct::class,43        );44    }4546    private function orm(): OrmManager47    {48        return $this->orm ??= new OrmManager();49    }50}51

<?php

declare(strict_types=1);

namespace Examples\Orm\QueryBuilder;

use Semitexa\Core\Attribute\InjectAsReadonly;
use Semitexa\Demo\Application\Db\MySQL\Model\DemoProductResource;
use Semitexa\Demo\Domain\Model\DemoProduct;
use Semitexa\Orm\OrmManager;
use Semitexa\Orm\Query\ResourceModelQuery;
use Semitexa\Orm\Repository\DomainRepository;

final class ProductQueryBuilder
{
    #[InjectAsReadonly]
    protected ?OrmManager $orm = null;

    private ?DomainRepository $repository = null;

    public function new(): ResourceModelQuery
    {
        return $this->repository()->query();
    }

    public function map(ResourceModelQuery $query): array
    {
        /** @var list<DemoProduct> */
        return $query->fetchAllAs(DemoProduct::class, $this->orm()->getMapperRegistry());
    }

    public function one(ResourceModelQuery $query): ?DemoProduct
    {
        /** @var DemoProduct|null */
        return $query->fetchOneAs(DemoProduct::class, $this->orm()->getMapperRegistry());
    }

    private function repository(): DomainRepository
    {
        return $this->repository ??= $this->orm()->repository(
            DemoProductResource::class,
            DemoProduct::class,
        );
    }

    private function orm(): OrmManager
    {
        return $this->orm ??= new OrmManager();
    }
}

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 [];
    }
}