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

Resource DTOs are the real presentation boundary: handlers build one typed response object, and templates consume that object instead of reshaping ad hoc arrays.

How it works

A payload declares responseWith, the handler receives a concrete resource DTO, and the resource accumulates named presentation fields through with*() methods before HtmlResponse auto-renders the declared template.

Why it matters

This is real separation of data and presentation. The template stops doing data surgery, partials stop inventing their own mapping rules, and the whole view layer reads from one explicit source of truth.

Key concepts

#[AsResource]: Declares the template and render handle for a typed response DTO.
HtmlResponse: Base SSR response that stores render context and auto-renders the declared template.
with*() methods: Explicit resource methods that define the vocabulary of data allowed to reach the template.

Presentation Boundary

One handler shapes one Resource DTO

The shortest useful explanation is enough here: the handler receives a typed resource, fills named presentation fields, and Twig renders that finished contract.

Handler receives a typed resource

The payload declares `responseWith`, so the handler gets a concrete Resource DTO instead of assembling loose arrays.

Handler fills named fields

Presentation data is pushed through explicit `with*()` methods before Twig sees anything.

Twig renders the finished contract

The template reads one stable response object instead of reformatting raw business data on its own.

Resource field	Why the handler sets it
`title`	Page heading already shaped for the template.
`summary`	Intro copy prepared in the handler, not reconstructed in Twig.
`highlights`	Structured view data ready for repeated rendering blocks.
`resultPreviewData`	Nested preview state passed as one explicit resource field.

typed view data auto render

Verified against Semitexa Ultimate 2026.09.19.1020

Resource DTOs

A Resource DTO is the typed presentation boundary between handler code and templates. Real separation means templates receive one explicit response object, not loose arrays and last-minute data surgery.

How it works

The payload declares responseWith, so the handler gets a concrete Resource DTO instead of assembling loose arrays.
Presentation data is pushed through explicit with*() methods before Twig sees anything.
The template reads one stable response object instead of reformatting raw business data on its own.

The rules

The Resource DTO is the response contract for templates, not a passive bucket for whatever data happened to be nearby.
Handlers should populate presentation fields deliberately through named with*() methods.
Twig should render data, not reinterpret domain state or normalize arrays on the fly.
Once the resource is complete, auto-rendering can stay mechanical and reliable.

Key mechanisms

#[AsResource] — declares the template and render handle directly on the response DTO.
with*() methods — create one explicit vocabulary for everything the template is allowed to consume.
HtmlResponse — provides render context accumulation and automatic template rendering after the handler pipeline.

Fields prepared by the handler

Field	Purpose
`title`	Page heading already shaped for the template
`summary`	Intro copy prepared in the handler, not reconstructed in Twig
`highlights`	Structured view data ready for repeated rendering blocks
`resultPreviewData`	Nested preview state passed as one explicit resource field

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/product/showcase.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/product/showcase.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);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: ProductPagePayload::class, resource: ProductShowcaseResource::class)]12final class ProductShowcaseHandler implements TypedHandlerInterface13{14    #[InjectAsReadonly]15    protected CatalogReadRepositoryInterface $catalog;1617    public function handle(ProductPagePayload $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: ProductPagePayload::class, resource: ProductShowcaseResource::class)]
final class ProductShowcaseHandler implements TypedHandlerInterface
{
    #[InjectAsReadonly]
    protected CatalogReadRepositoryInterface $catalog;

    public function handle(ProductPagePayload $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'],
            ]);
    }
}

Response Canon

One object shapes the whole page

The resource should be the canonical language of the view layer. Templates stay declarative because the response object already did the hard work of choosing names, formatting fields, and defining the available structure.

The Resource DTO is the response contract for templates, not a passive bucket for whatever data happened to be nearby.

Handlers should populate presentation fields deliberately through named with*() methods.

Twig should render data, not reinterpret domain state or normalize arrays on the fly.

Once the resource is complete, auto-rendering can stay mechanical and reliable.

Resource concern	What the DTO makes explicit
#[AsResource]	Declares the template and render handle directly on the response DTO.
with*() methods	Create one explicit vocabulary for everything the template is allowed to consume.
HtmlResponse	Provides render context accumulation and automatic template rendering after the handler pipeline.

How it works

Why it matters

Key concepts

#[AsResource]: Declares the template and render handle for a typed response DTO.
HtmlResponse: Base SSR response that stores render context and auto-renders the declared template.
with*() methods: Explicit resource methods that define the vocabulary of data allowed to reach the template.