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

Understand why Semitexa keeps transport, use case, and rendering as separate explicit responsibilities.

Architecture Contrast

A controller is one object doing yesterday's whole HTTP stack

Semitexa is not anti-class. It is anti-collapse. The example payload below owns a real `{slug}` route parameter, its regex guard, normalization, and validation before the handler even starts business work.

The controller pattern feels compact only while the endpoint is trivial.

As soon as route parameters, input rules, auth rules, response variants, and SSR composition appear, the controller becomes a mixed-concern shell that is harder to test, harder to extend, and harder for tooling to explain.

Concern	Typical controller-first class	Semitexa canonical owner
Route contract	Annotation or controller method metadata	Payload DTO
Input boundary	Request object + ad hoc reads	Payload setters and validation
Use case orchestration	Controller action body	Typed handler
Response shape	Inline arrays / Response building	Resource DTO
Extensibility	Middleware, helper traits, controller inheritance	Explicit contracts and modules

Semitexa keeps the HTTP boundary typed so route discovery, validation, response decoration, and introspection can all reason about the same declared contract.

controllers payload handler resource rendering boundary

Verified against Semitexa Ultimate 2026.09.19.1020

Beyond Controllers

Semitexa does not treat controllers as the universal container for transport, orchestration, and rendering.

Canonical split

payload owns inbound HTTP structure
handler owns the use case
resource owns response data and metadata
template owns presentation

What this avoids

transport and business logic collapsing into one unstable class
hidden rendering state
ad hoc arrays passed across unclear boundaries

Why this matters

The framework stays readable because each layer owns one job. That keeps growth additive instead of turning every new feature into another oversized controller.

1<?php23declare(strict_types=1);45use Semitexa\Core\Attribute\AsPublicPayload;6use Semitexa\Core\Exception\ValidationException;78#[AsPublicPayload(9    path: '/products/{slug}',10    methods: ['GET'],11    responseWith: ProductShowcaseResource::class,12    requirements: ['slug' => '[a-z0-9-]+'],13    defaults: ['slug' => 'wireless-headphones'],14)]15final class ProductShowcasePayload16{17    protected string $slug = 'wireless-headphones';1819    public function getSlug(): string20    {21        return $this->slug;22    }2324    public function setSlug(string $slug): void25    {26        $normalized = strtolower(trim($slug));27        $normalized = preg_replace('/[^a-z0-9-]+/', '-', $normalized) ?? '';28        $normalized = trim($normalized, '-');2930        if ($normalized === '') {31            throw new ValidationException(['slug' => ['Product slug is required.']]);32        }3334        if (strlen($normalized) > 120) {35            throw new ValidationException(['slug' => ['Product slug must stay below 120 characters.']]);36        }3738        if (preg_match('/^[a-z0-9-]+$/', $normalized) !== 1) {39            throw new ValidationException(['slug' => ['Product slug may only contain lowercase letters, numbers, and dashes.']]);40        }4142        $this->slug = $normalized;43    }44}45

<?php

declare(strict_types=1);

use Semitexa\Core\Attribute\AsPublicPayload;
use Semitexa\Core\Exception\ValidationException;

#[AsPublicPayload(
    path: '/products/{slug}',
    methods: ['GET'],
    responseWith: ProductShowcaseResource::class,
    requirements: ['slug' => '[a-z0-9-]+'],
    defaults: ['slug' => 'wireless-headphones'],
)]
final class ProductShowcasePayload
{
    protected string $slug = 'wireless-headphones';

    public function getSlug(): string
    {
        return $this->slug;
    }

    public function setSlug(string $slug): void
    {
        $normalized = strtolower(trim($slug));
        $normalized = preg_replace('/[^a-z0-9-]+/', '-', $normalized) ?? '';
        $normalized = trim($normalized, '-');

        if ($normalized === '') {
            throw new ValidationException(['slug' => ['Product slug is required.']]);
        }

        if (strlen($normalized) > 120) {
            throw new ValidationException(['slug' => ['Product slug must stay below 120 characters.']]);
        }

        if (preg_match('/^[a-z0-9-]+$/', $normalized) !== 1) {
            throw new ValidationException(['slug' => ['Product slug may only contain lowercase letters, numbers, and dashes.']]);
        }

        $this->slug = $normalized;
    }
}

1<?php23declare(strict_types=1);45use Examples\Shared\CatalogReadRepositoryInterface;6use Semitexa\Core\Attribute\AsPayloadHandler;7use Semitexa\Core\Attribute\InjectAsReadonly;8use Semitexa\Core\Contract\TypedHandlerInterface;9use Semitexa\Core\Exception\NotFoundException;1011#[AsPayloadHandler(payload: ProductShowcasePayload::class, resource: ProductShowcaseResource::class)]12final class ProductShowcaseHandler implements TypedHandlerInterface13{14    #[InjectAsReadonly]15    protected CatalogReadRepositoryInterface $catalog;1617    public function handle(ProductShowcasePayload $payload, ProductShowcaseResource $resource): ProductShowcaseResource18    {19        $product = $this->catalog->findBySlug($payload->getSlug());2021        if ($product === null) {22            throw new NotFoundException('Product', $payload->getSlug());23        }2425        return $resource26            ->withSlug($product->slug)27            ->withProductName($product->name)28            ->withPriceLabel('$' . number_format($product->price, 2))29            ->withInventoryState($product->stock > 0 ? 'In stock' : 'Backorder')30            ->withSummary($product->summary)31            ->withHeroActions([32                ['label' => 'Buy now', 'href' => '/products/' . $product->slug . '/buy'],33                ['label' => 'Read specs', 'href' => '/products/' . $product->slug . '#specs'],34            ]);35    }36}37

<?php

declare(strict_types=1);

use Examples\Shared\CatalogReadRepositoryInterface;
use Semitexa\Core\Attribute\AsPayloadHandler;
use Semitexa\Core\Attribute\InjectAsReadonly;
use Semitexa\Core\Contract\TypedHandlerInterface;
use Semitexa\Core\Exception\NotFoundException;

#[AsPayloadHandler(payload: ProductShowcasePayload::class, resource: ProductShowcaseResource::class)]
final class ProductShowcaseHandler implements TypedHandlerInterface
{
    #[InjectAsReadonly]
    protected CatalogReadRepositoryInterface $catalog;

    public function handle(ProductShowcasePayload $payload, ProductShowcaseResource $resource): ProductShowcaseResource
    {
        $product = $this->catalog->findBySlug($payload->getSlug());

        if ($product === null) {
            throw new NotFoundException('Product', $payload->getSlug());
        }

        return $resource
            ->withSlug($product->slug)
            ->withProductName($product->name)
            ->withPriceLabel('$' . number_format($product->price, 2))
            ->withInventoryState($product->stock > 0 ? 'In stock' : 'Backorder')
            ->withSummary($product->summary)
            ->withHeroActions([
                ['label' => 'Buy now', 'href' => '/products/' . $product->slug . '/buy'],
                ['label' => 'Read specs', 'href' => '/products/' . $product->slug . '#specs'],
            ]);
    }
}

1<?php23declare(strict_types=1);45use Semitexa\Core\Attribute\AsResource;6use Semitexa\Ssr\Application\Service\Http\Response\HtmlResponse;78#[AsResource(9    handle: 'product_showcase',10    template: '@project/catalog/pages/product-show.html.twig',11)]12final class ProductShowcaseResource extends HtmlResponse13{14    public function withSlug(string $slug): self15    {16        return $this->with('slug', $slug);17    }1819    public function withProductName(string $name): self20    {21        return $this->with('productName', $name);22    }2324    public function withPriceLabel(string $priceLabel): self25    {26        return $this->with('priceLabel', $priceLabel);27    }2829    public function withInventoryState(string $state): self30    {31        return $this->with('inventoryState', $state);32    }3334    public function withSummary(string $summary): self35    {36        return $this->with('summary', $summary);37    }3839    public function withHeroActions(array $actions): self40    {41        return $this->with('heroActions', $actions);42    }43}44

<?php

declare(strict_types=1);

use Semitexa\Core\Attribute\AsResource;
use Semitexa\Ssr\Application\Service\Http\Response\HtmlResponse;

#[AsResource(
    handle: 'product_showcase',
    template: '@project/catalog/pages/product-show.html.twig',
)]
final class ProductShowcaseResource extends HtmlResponse
{
    public function withSlug(string $slug): self
    {
        return $this->with('slug', $slug);
    }

    public function withProductName(string $name): self
    {
        return $this->with('productName', $name);
    }

    public function withPriceLabel(string $priceLabel): self
    {
        return $this->with('priceLabel', $priceLabel);
    }

    public function withInventoryState(string $state): self
    {
        return $this->with('inventoryState', $state);
    }

    public function withSummary(string $summary): self
    {
        return $this->with('summary', $summary);
    }

    public function withHeroActions(array $actions): self
    {
        return $this->with('heroActions', $actions);
    }
}

1<?php23declare(strict_types=1);45namespace App\Catalog\Controller;67use Framework\Http\Request;8use Framework\Http\Response;9use App\Catalog\Service\ProductService;1011final class ProductShowController12{13    public function __construct(14        private ProductService $products,15    ) {}1617    public function __invoke(Request $request): Response18    {19        $slug = (string) $request->query->get('slug', '');2021        if ($slug === '') {22            return new Response(23                body: json_encode(['error' => 'Missing slug']),24                status: 422,25                headers: ['Content-Type' => 'application/json'],26            );27        }2829        $product = $this->products->findBySlug($slug);3031        if ($product === null) {32            return new Response(33                body: json_encode(['error' => 'Not found']),34                status: 404,35                headers: ['Content-Type' => 'application/json'],36            );37        }3839        return new Response(40            body: json_encode([41                'slug' => $product->slug,42                'name' => $product->name,43                'price' => $product->price,44            ]),45            headers: ['Content-Type' => 'application/json'],46        );47    }48}49

<?php

declare(strict_types=1);

namespace App\Catalog\Controller;

use Framework\Http\Request;
use Framework\Http\Response;
use App\Catalog\Service\ProductService;

final class ProductShowController
{
    public function __construct(
        private ProductService $products,
    ) {}

    public function __invoke(Request $request): Response
    {
        $slug = (string) $request->query->get('slug', '');

        if ($slug === '') {
            return new Response(
                body: json_encode(['error' => 'Missing slug']),
                status: 422,
                headers: ['Content-Type' => 'application/json'],
            );
        }

        $product = $this->products->findBySlug($slug);

        if ($product === null) {
            return new Response(
                body: json_encode(['error' => 'Not found']),
                status: 404,
                headers: ['Content-Type' => 'application/json'],
            );
        }

        return new Response(
            body: json_encode([
                'slug' => $product->slug,
                'name' => $product->name,
                'price' => $product->price,
            ]),
            headers: ['Content-Type' => 'application/json'],
        );
    }
}

Why Controller-First Ages Badly

Common failure modes that look normal until the codebase grows

The problem is not the word "controller". The problem is using one class as the accidental dumping ground for every HTTP concern.

Validation logic leaks into action methods because the transport contract is not a first-class object.

Route parameters such as slugs are often trimmed, sanitized, defaulted, and rejected ad hoc in the controller body instead of at the payload boundary.

Response shape drifts between arrays, Response objects, view models, and template variables.

Route metadata becomes harder to inspect because it is attached to controller actions, middleware, and framework conventions at the same time.

Module extension gets coarse-grained because replacing a small behavior often means replacing the whole controller action or wrapping it indirectly.

LLM and static-analysis tooling see one mixed blob instead of a typed transport contract, a use case step, and a response contract.

Semitexa Canon

What to remember when building the first real feature

Once the transport boundary, use case, and response each have an owner, the rest of the framework becomes easier to inspect, extend, and automate.

Declare the route, HTTP methods, and payload boundary on the payload DTO, not in a controller method signature.

Keep the handler focused on orchestration and use-case flow, not transport parsing or response assembly details.

Let the resource own response shape, SEO metadata, and template context so rendering stays explicit and reusable.

Add modules and contracts around this typed spine instead of reopening one growing action class for every new concern.