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

The canonical Semitexa repository workflow is domain-first: application code depends on repository contracts and works with domain models, not raw ORM resources.

How it works

Repository contracts return domain objects. ORM repository implementations sit behind the contract, convert through explicit mappers, and keep persistence models behind the boundary.

Why it matters

This keeps the demo honest about best practices. Resource-level CRUD still exists, but it is not what we should teach as the primary architectural path.

Key concepts

Repository contract: Application-facing interface that expresses persistence in domain language.
Domain-first read path: Default repository reads return business models instead of persistence resources.
DomainRepository: New ORM entry point that coordinates ResourceModel queries, mapping, and aggregate writes.

Canonical Path

Business code should not pass ORM resources around

In Semitexa, handlers and services depend on repository contracts and receive domain models back. Resource models stay behind the persistence boundary unless you deliberately opt into a resource-level read.

What the demo should teach

Handlers should ask for repository contracts, not ORM implementations.
The default read path should return domain/business models through the explicit ResourceModel -> mapper -> domain pipeline.
insert(domainModel) and update(domainModel) are the happy path; low-level ResourceModel reads are an explicit infrastructure concern.

Best practice

Application / domain path

Contract repository returns MachineCredential domain objects with business behavior intact.

MachineCredentialRepositoryInterface MachineCredential insert(domain) update(domain)

Infrastructure-only

Persistence path

ResourceModel and mapper classes still matter, but their job is to describe storage and convert data between persistence and domain.

MachineCredentialResourceModel MachineCredentialMapper DomainRepository mapping only

Step	Canonical flow	Why it stays clean
Read	Handler -> repository contract -> fetchOne()/findById() -> domain model	Business code gets behavior and invariants, not ORM metadata.
Mutate	Domain object methods change state, e.g. revoke() or recordUsage()	The business rule lives on the business object, not in a persistence DTO.
Persist	Repository implementation converts domain -> resource model via explicit mapper and persists through the ORM core	Storage mapping stays in the persistence layer where it belongs.

domain model ResourceModel mapper #[SatisfiesRepositoryContract]

Verified against Semitexa Ultimate 2026.09.19.1020

Repository Workflow

The canonical Semitexa persistence path keeps business code working with domain models and confines ResourceModel and mapper logic to the persistence layer.

How it works

Handlers receive repository dependencies through #[InjectAsReadonly], preferably via contract interfaces where the module defines them. The repository implementation performs the read via ResourceModel → mapper → domain model, and persists through insert(domainModel) or update(domainModel). Low-level ResourceModel reads remain available but are an explicit infrastructure concern.

Why this matters

When business code depends on repository contracts and domain models, the storage mapping stays reviewable and isolated. Swapping a persistence implementation never forces changes in handlers or services, and the business rules stay on the business objects where they belong.

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\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\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;
    }
}

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(),
        );
    }
}

Low-Level Escape Hatch

When resource-level reads are acceptable

ResourceModel-level persistence is a capability, not the headline practice that the demo should teach first.

If a screen is demonstrating application architecture, show repository contracts and domain models, not direct ResourceModel mutation.

Mapper and ResourceModel code should stay clearly visible, but behind the repository boundary.

If a feature is mostly about domain behavior, the source tabs should foreground the domain model and contract before the persistence model.

How it works

Repository contracts return domain objects. ORM repository implementations sit behind the contract, convert through explicit mappers, and keep persistence models behind the boundary.

Why it matters

This keeps the demo honest about best practices. Resource-level CRUD still exists, but it is not what we should teach as the primary architectural path.

Key concepts

Repository contract: Application-facing interface that expresses persistence in domain language.
Domain-first read path: Default repository reads return business models instead of persistence resources.
DomainRepository: New ORM entry point that coordinates ResourceModel queries, mapping, and aggregate writes.