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

Semitexa deliberately separates persistence resources from domain-level business models instead of pretending one class should do both jobs.

How it works

A ResourceModel maps the table, and an explicit mapper converts between persistence and domain. Repositories then return domain objects on the normal read path.

Why it matters

This keeps business code free from ORM metadata and keeps persistence code free from fake business semantics. The boundary stays reviewable and intentional.

Key concepts

ResourceModel: Persistence-side model that maps one table row shape and relation metadata.
Mapper: Explicit converter between ResourceModel and DomainModel.
Resource model: ORM-facing class responsible for table mapping, columns, indexes, and storage conversion.
Domain model: Business object carrying behavior, invariants, and ubiquitous language without persistence metadata.

Two Model Layers

Resource model and domain model do different jobs

Semitexa does not force one giant class to be table mapping, behavior container, and business language at the same time. The ORM resource maps persistence. The domain model carries the business rules.

Why this matters

When one class is both ORM mapping and business model, storage concerns leak into business code immediately.
That usually pushes handlers and services to pass persistence resources around as if they were the real business objects.
Semitexa keeps the separation explicit: repositories can expose domain models while still using ResourceModel + mapper for persistence.

Persistence layer

ResourceModel + mapper

Maps columns, table name, and explicit conversion rules into the domain layer.

#[FromTable] #[Column] #[AsMapper] explicit mapping

Business layer

Domain model

Holds business semantics like revoke(), rotateSecretHash(), recordUsage(), hasScope().

behavior invariants business language no ORM attrs

Concern	Resource model	Domain model
Primary responsibility	Describe how one table row is stored and rehydrated.	Describe what the business object means and how it behaves.
Allowed dependencies	ORM attributes, SQL-facing concerns, mapping metadata.	Only domain language and behavior, no storage metadata.
Repository default reads	Built as ResourceModel and then mapped explicitly inside the repository implementation.	Returned by the repository contract through the canonical ORM path.
Mutation path	Useful for low-level persistence mutation or infrastructure-only workflows.	Preferred for business flows through contract repositories like MachineCredentialRepositoryInterface.

#[AsMapper] #[SatisfiesRepositoryContract] DomainRepository

Verified against Semitexa Ultimate 2026.09.19.1020

Domain-Level Models

Semitexa keeps persistence resources and business domain models as separate classes with explicit mappers between them.

How it works

A ResourceModel describes how one table row is stored and rehydrated. A domain model holds business semantics — methods like revoke(), rotateSecretHash(), recordUsage(), and hasScope(). A mapper annotated with #[AsMapper] converts between the two, and a repository implementation annotated with #[SatisfiesRepositoryContract] returns domain models from the contract boundary.

Why this matters

When one class is both an ORM mapping and a business model, storage concerns leak into business code immediately. Semitexa keeps the separation explicit so that handlers and services work with objects that carry business meaning, not persistence metadata.

1<?php23declare(strict_types=1);45namespace App\Domain\Auth;67final class MachineCredential8{9    public function __construct(10        public readonly string $id,11        public readonly string $secretHash,12        public readonly array $scopes,13    ) {}14}15

<?php

declare(strict_types=1);

namespace App\Domain\Auth;

final class MachineCredential
{
    public function __construct(
        public readonly string $id,
        public readonly string $secretHash,
        public readonly array $scopes,
    ) {}
}

1<?php23declare(strict_types=1);45namespace App\Application\Db\ResourceModel;67use Semitexa\Orm\Adapter\MySqlType;8use Semitexa\Orm\Attribute\Column;9use Semitexa\Orm\Attribute\FromTable;1011#[FromTable(name: 'machine_credentials')]12final class MachineCredentialResourceModel13{14    #[Column(type: MySqlType::Varchar, length: 64)]15    public string $id;1617    #[Column(type: MySqlType::Varchar, length: 255)]18    public string $secret_hash;19}20

<?php

declare(strict_types=1);

namespace App\Application\Db\ResourceModel;

use Semitexa\Orm\Adapter\MySqlType;
use Semitexa\Orm\Attribute\Column;
use Semitexa\Orm\Attribute\FromTable;

#[FromTable(name: 'machine_credentials')]
final class MachineCredentialResourceModel
{
    #[Column(type: MySqlType::Varchar, length: 64)]
    public string $id;

    #[Column(type: MySqlType::Varchar, length: 255)]
    public string $secret_hash;
}

1<?php23declare(strict_types=1);45namespace Semitexa\Api\Application\Db\MySQL\Mapper;67use Semitexa\Api\Application\Db\MySQL\Model\MachineCredentialResourceModel;8use Semitexa\Api\Domain\Model\MachineCredential;9use Semitexa\Orm\Attribute\AsMapper;10use Semitexa\Orm\Domain\Contract\ResourceModelMapperInterface;1112#[AsMapper(resourceModel: MachineCredentialResourceModel::class, domainModel: MachineCredential::class)]13final class MachineCredentialMapper implements ResourceModelMapperInterface14{15    public function toDomain(object $resourceModel): object16    {17        $resourceModel instanceof MachineCredentialResourceModel || throw new \InvalidArgumentException('Unexpected resource model.');1819        return new MachineCredential(20            id: $resourceModel->id,21            clientName: $resourceModel->clientName,22            secretHash: $resourceModel->secretHash,23            scopes: $resourceModel->scopes,24            tenantId: $resourceModel->tenantId,25            createdAt: $resourceModel->createdAt,26            lastUsedAt: $resourceModel->lastUsedAt,27            requestCount: $resourceModel->requestCount,28            rotatedAt: $resourceModel->rotatedAt,29            revokedAt: $resourceModel->revokedAt,30        );31    }3233    public function toSourceModel(object $domainModel): object34    {35        $domainModel instanceof MachineCredential || throw new \InvalidArgumentException('Unexpected domain model.');3637        return new MachineCredentialResourceModel(38            id: $domainModel->getId(),39            clientName: $domainModel->getClientName(),40            secretHash: $domainModel->getSecretHash(),41            scopes: $domainModel->getScopes(),42            tenantId: $domainModel->getTenantId(),43            createdAt: $domainModel->getCreatedAt(),44            lastUsedAt: $domainModel->getLastUsedAt(),45            requestCount: $domainModel->getRequestCount(),46            rotatedAt: $domainModel->getRotatedAt(),47            revokedAt: $domainModel->getRevokedAt(),48        );49    }50}51

<?php

declare(strict_types=1);

namespace Semitexa\Api\Application\Db\MySQL\Mapper;

use Semitexa\Api\Application\Db\MySQL\Model\MachineCredentialResourceModel;
use Semitexa\Api\Domain\Model\MachineCredential;
use Semitexa\Orm\Attribute\AsMapper;
use Semitexa\Orm\Domain\Contract\ResourceModelMapperInterface;

#[AsMapper(resourceModel: MachineCredentialResourceModel::class, domainModel: MachineCredential::class)]
final class MachineCredentialMapper implements ResourceModelMapperInterface
{
    public function toDomain(object $resourceModel): object
    {
        $resourceModel instanceof MachineCredentialResourceModel || throw new \InvalidArgumentException('Unexpected resource model.');

        return new MachineCredential(
            id: $resourceModel->id,
            clientName: $resourceModel->clientName,
            secretHash: $resourceModel->secretHash,
            scopes: $resourceModel->scopes,
            tenantId: $resourceModel->tenantId,
            createdAt: $resourceModel->createdAt,
            lastUsedAt: $resourceModel->lastUsedAt,
            requestCount: $resourceModel->requestCount,
            rotatedAt: $resourceModel->rotatedAt,
            revokedAt: $resourceModel->revokedAt,
        );
    }

    public function toSourceModel(object $domainModel): object
    {
        $domainModel instanceof MachineCredential || throw new \InvalidArgumentException('Unexpected domain model.');

        return new MachineCredentialResourceModel(
            id: $domainModel->getId(),
            clientName: $domainModel->getClientName(),
            secretHash: $domainModel->getSecretHash(),
            scopes: $domainModel->getScopes(),
            tenantId: $domainModel->getTenantId(),
            createdAt: $domainModel->getCreatedAt(),
            lastUsedAt: $domainModel->getLastUsedAt(),
            requestCount: $domainModel->getRequestCount(),
            rotatedAt: $domainModel->getRotatedAt(),
            revokedAt: $domainModel->getRevokedAt(),
        );
    }
}

1<?php23declare(strict_types=1);45namespace App\Domain\Auth;67interface MachineCredentialRepositoryInterface8{9    public function findById(string $id): ?MachineCredential;10}11

<?php

declare(strict_types=1);

namespace App\Domain\Auth;

interface MachineCredentialRepositoryInterface
{
    public function findById(string $id): ?MachineCredential;
}

1<?php23declare(strict_types=1);45namespace App\Application\Db\Repository;67use App\Domain\Auth\MachineCredential;8use App\Domain\Auth\MachineCredentialRepositoryInterface;910final class MachineCredentialRepository implements MachineCredentialRepositoryInterface11{12    public function findById(string $id): ?MachineCredential13    {14        return null;15    }16}17

<?php

declare(strict_types=1);

namespace App\Application\Db\Repository;

use App\Domain\Auth\MachineCredential;
use App\Domain\Auth\MachineCredentialRepositoryInterface;

final class MachineCredentialRepository implements MachineCredentialRepositoryInterface
{
    public function findById(string $id): ?MachineCredential
    {
        return null;
    }
}

Repository Boundary

What should cross the boundary

Repository contracts at the application boundary should usually speak in domain models, not ORM resources.

ResourceModel and mapper classes are still first-class, but mostly for mapping, hydration, and persistence-specific operations.

When a workflow truly needs raw persistence shape, keep that path explicit and infrastructure-scoped.

The canonical repository read path should remain ResourceModel -> mapper -> domain model.

How it works

A ResourceModel maps the table, and an explicit mapper converts between persistence and domain. Repositories then return domain objects on the normal read path.

Why it matters

This keeps business code free from ORM metadata and keeps persistence code free from fake business semantics. The boundary stays reviewable and intentional.

Key concepts

ResourceModel: Persistence-side model that maps one table row shape and relation metadata.
Mapper: Explicit converter between ResourceModel and DomainModel.
Resource model: ORM-facing class responsible for table mapping, columns, indexes, and storage conversion.
Domain model: Business object carrying behavior, invariants, and ubiquitous language without persistence metadata.