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

Payloads are the shield from external data: hydration happens first, and each setter owns the normalization and guard logic for its own field before the handler runs.

How it works

PayloadHydrator maps request input into the payload via typed setters. Each setter can normalize its value and throw a field-aware ValidationException when the input is invalid, which keeps the boundary close to the field itself.

Why it matters

This keeps the transport boundary explicit without forcing one DTO-wide validation method to know every field. The payload owns the input truth, the handler owns the use case, and additional fields can be added by payload parts without reopening a central validate() method.

Key concepts

PayloadHydrator: Hydrates payload DTOs from HTTP input by calling typed setters.
ValidationException: Field-aware exception that a setter can throw when the incoming value is not acceptable.
setter-owned validation: The field that owns the data also owns its normalization and guard logic.

Trusted Input Boundary

Payloads turn raw HTTP into application-grade data

The payload is not a passive DTO. It is the shield between external input and the use case: hydration, type casting, and validation happen first, and only then does business code run.

What usually goes wrong

Raw request arrays make controllers mix transport parsing, validation, and business rules in one method.
The same checks get repeated across handlers because there is no single boundary object that owns input truth.
When invalid data slips through, the handler must keep defending itself instead of focusing on the business action.

1 trusted boundary object

422 automatic invalid-input rejection

0 transport checks left in the handler

Step 1

Hydrate

PayloadHydrator maps request input into one payload object via typed setters.

Step 2

Normalize

Setter code trims, casts, and shapes the input for the field it owns.

Step 3

Guard

Setter-level checks throw a field-aware ValidationException before invalid data can reach the handler.

Step 4

Handle

Business code receives a trusted DTO and can focus on intent, not defensive parsing.

Scattered Responsibility

Raw request in the handler

Input extraction, branching, validation errors, and business rules all compete in one controller method.

The boundary is blurry, so every handler keeps re-checking input just in case.

Single Source Of Truth

Payload as the shield

The payload owns hydration and field guards, so the handler receives clean data it can trust.

Single responsibility becomes obvious: setters guard input, handler executes the use case.

setter guards 422 before handler

Verified against Semitexa Ultimate 2026.09.19.1020

Payload As A Shield

Payloads are the shield from external data: hydration happens first, and each setter owns the normalization and guard logic for its own field before the handler runs.

How it works

Why this matters

1<?php23declare(strict_types=1);45final class LegacyCheckoutController6{7    public function create(Request $request): Response8    {9        $email = trim((string) $request->input('email', ''));10        $coupon = trim((string) $request->input('coupon', ''));11        $agreeToTerms = (bool) $request->input('agree_to_terms', false);1213        if ($email === '') {14            return Response::json(['errors' => ['email' => ['Email is required.']]], 422);15        }1617        if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {18            return Response::json(['errors' => ['email' => ['Email is invalid.']]], 422);19        }2021        if ($agreeToTerms !== true) {22            return Response::json(['errors' => ['agree_to_terms' => ['Terms must be accepted.']]], 422);23        }2425        return $this->checkoutService->create(26            email: $email,27            coupon: $coupon !== '' ? strtoupper($coupon) : null,28            agreeToTerms: $agreeToTerms,29        );30    }31}32

<?php

declare(strict_types=1);

final class LegacyCheckoutController
{
    public function create(Request $request): Response
    {
        $email = trim((string) $request->input('email', ''));
        $coupon = trim((string) $request->input('coupon', ''));
        $agreeToTerms = (bool) $request->input('agree_to_terms', false);

        if ($email === '') {
            return Response::json(['errors' => ['email' => ['Email is required.']]], 422);
        }

        if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
            return Response::json(['errors' => ['email' => ['Email is invalid.']]], 422);
        }

        if ($agreeToTerms !== true) {
            return Response::json(['errors' => ['agree_to_terms' => ['Terms must be accepted.']]], 422);
        }

        return $this->checkoutService->create(
            email: $email,
            coupon: $coupon !== '' ? strtoupper($coupon) : null,
            agreeToTerms: $agreeToTerms,
        );
    }
}

1<?php23declare(strict_types=1);45use Semitexa\Core\Attribute\AsPublicPayload;6use Semitexa\Core\Exception\ValidationException;78#[AsPublicPayload(9    path: '/checkout',10    methods: ['POST'],11    responseWith: CheckoutResultResource::class,12)]13final class CreateCheckoutPayload14{15    protected string $email = '';16    protected ?string $coupon = null;17    protected bool $agreeToTerms = false;1819    public function getEmail(): string20    {21        return $this->email;22    }2324    public function setEmail(string $email): void25    {26        $email = trim($email);2728        if ($email === '') {29            throw new ValidationException(['email' => ['Email is required.']]);30        }3132        if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {33            throw new ValidationException(['email' => ['Email must be valid.']]);34        }3536        $this->email = $email;37    }3839    public function getCoupon(): ?string40    {41        return $this->coupon;42    }4344    public function setCoupon(string $coupon): void45    {46        $coupon = strtoupper(trim($coupon));47        $this->coupon = $coupon !== '' ? $coupon : null;48    }4950    public function hasAcceptedTerms(): bool51    {52        return $this->agreeToTerms;53    }5455    public function setAgreeToTerms(bool $agreeToTerms): void56    {57        if ($agreeToTerms !== true) {58            throw new ValidationException(['agreeToTerms' => ['Terms must be accepted.']]);59        }6061        $this->agreeToTerms = $agreeToTerms;62    }63}64

<?php

declare(strict_types=1);

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

#[AsPublicPayload(
    path: '/checkout',
    methods: ['POST'],
    responseWith: CheckoutResultResource::class,
)]
final class CreateCheckoutPayload
{
    protected string $email = '';
    protected ?string $coupon = null;
    protected bool $agreeToTerms = false;

    public function getEmail(): string
    {
        return $this->email;
    }

    public function setEmail(string $email): void
    {
        $email = trim($email);

        if ($email === '') {
            throw new ValidationException(['email' => ['Email is required.']]);
        }

        if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
            throw new ValidationException(['email' => ['Email must be valid.']]);
        }

        $this->email = $email;
    }

    public function getCoupon(): ?string
    {
        return $this->coupon;
    }

    public function setCoupon(string $coupon): void
    {
        $coupon = strtoupper(trim($coupon));
        $this->coupon = $coupon !== '' ? $coupon : null;
    }

    public function hasAcceptedTerms(): bool
    {
        return $this->agreeToTerms;
    }

    public function setAgreeToTerms(bool $agreeToTerms): void
    {
        if ($agreeToTerms !== true) {
            throw new ValidationException(['agreeToTerms' => ['Terms must be accepted.']]);
        }

        $this->agreeToTerms = $agreeToTerms;
    }
}

1<?php23declare(strict_types=1);45use Examples\Routing\PayloadShield\CheckoutServiceInterface;6use Semitexa\Core\Attribute\AsPayloadHandler;7use Semitexa\Core\Attribute\InjectAsReadonly;8use Semitexa\Core\Contract\TypedHandlerInterface;910#[AsPayloadHandler(payload: CreateCheckoutPayload::class, resource: CheckoutResultResource::class)]11final class CreateCheckoutHandler implements TypedHandlerInterface12{13    #[InjectAsReadonly]14    protected CheckoutServiceInterface $checkoutService;1516    public function handle(CreateCheckoutPayload $payload, CheckoutResultResource $resource): CheckoutResultResource17    {18        $checkout = $this->checkoutService->create(19            email: $payload->getEmail(),20            coupon: $payload->getCoupon(),21            agreeToTerms: $payload->hasAcceptedTerms(),22        );2324        $resource->fromCheckout($checkout);2526        return $resource;27    }28}29

<?php

declare(strict_types=1);

use Examples\Routing\PayloadShield\CheckoutServiceInterface;
use Semitexa\Core\Attribute\AsPayloadHandler;
use Semitexa\Core\Attribute\InjectAsReadonly;
use Semitexa\Core\Contract\TypedHandlerInterface;

#[AsPayloadHandler(payload: CreateCheckoutPayload::class, resource: CheckoutResultResource::class)]
final class CreateCheckoutHandler implements TypedHandlerInterface
{
    #[InjectAsReadonly]
    protected CheckoutServiceInterface $checkoutService;

    public function handle(CreateCheckoutPayload $payload, CheckoutResultResource $resource): CheckoutResultResource
    {
        $checkout = $this->checkoutService->create(
            email: $payload->getEmail(),
            coupon: $payload->getCoupon(),
            agreeToTerms: $payload->hasAcceptedTerms(),
        );

        $resource->fromCheckout($checkout);

        return $resource;
    }
}

Single Responsibility

One place to trust, one place to act

This is the architectural payoff: payloads own the external boundary, handlers own the use case. The split is visible in code review and stays stable across the whole application.

The payload is the single place where external data becomes internal application data.

Setter signatures define the accepted shape, and setter code defines the accepted business constraints.

If the payload is invalid, the request ends before the handler is called.

Handlers should read like use cases, not like defensive transport parsers.

Boundary concern	What Semitexa does with it
Hydration	PayloadHydrator calls typed setters on the payload DTO.
Field guards	Setters throw field-aware exceptions when incoming values are not acceptable.
Trust boundary	Once the handler runs, the payload should already be safe to consume.

How it works

Why it matters

Key concepts

PayloadHydrator: Hydrates payload DTOs from HTTP input by calling typed setters.
ValidationException: Field-aware exception that a setter can throw when the incoming value is not acceptable.
setter-owned validation: The field that owns the data also owns its normalization and guard logic.