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

A payload can be extended by another module without reopening the original route class, so one transport boundary can stay singular while modules stay additive.

How it works

A base module declares the payload with #[AsPayload]. Another module contributes a trait marked with #[AsPayloadPart(base: ...)]. At runtime PayloadFactory composes a wrapper class that extends the base payload and uses all matching traits, so the added trait can own setters and guards for its own extra fields.

Why it matters

This solves a painful modularity problem: extra request concerns do not force a fork of the original payload and do not leak into untyped arrays. The handler still receives one trusted DTO, and each added concern can validate its own field without a central validate() choke point.

Key concepts

#[AsPayloadPart]: Marks a trait as an additive extension of an existing payload class.
PayloadFactory: Builds the runtime wrapper class that extends the base payload and mixes in discovered payload-part traits.
trait composition: Lets separate modules add typed setters, getters, and local guards to the same request boundary without modifying the base payload source.

Modular Route Contract

One payload, more than one module

The route stays declared once, but extra request fields can be composed in by another module through a typed trait instead of a fork.

The base module owns the route path and the main transport contract.

A second module adds its own request concerns, such as tracking or preview flags, with #[AsPayloadPart] on a trait, and the trait can own the setter-level guards for those fields.

Module A and Module B handlers now receive the same composed payload instance, so both can read the mixed contract without a payload fork.

Concern	Without payload parts	With #[AsPayloadPart]
Base route ownership	Fork or reopen the original payload class	Base payload stays untouched
Module-specific query fields	Ad-hoc arrays or handler glue	Typed trait methods on the same payload
Handler input	Scattered conditionals	One composed payload DTO

The important part is not the trait itself. The important part is that both modules still work with one payload boundary after composition, while each added field keeps its own normalization and guard logic.

module extension field-level guards

Verified against Semitexa Ultimate 2026.09.19.1020

Payload Parts

A payload can be extended by another module without reopening the original route class, so one transport boundary can stay singular while modules stay additive.

How it works

A base module declares the payload with one of the access attributes (#[AsPublicPayload], #[AsProtectedPayload], or #[AsServicePayload]). Another module contributes a trait marked with #[AsPayloadPart(base: ...)]. At runtime PayloadFactory composes a wrapper class that extends the base payload and uses all matching traits, so the added trait can own setters and guards for its own extra fields.

Why this matters

1<?php23declare(strict_types=1);45namespace App\Catalog\Application\Payload\Request;67use Semitexa\Core\Attribute\AsPublicPayload;8use Semitexa\Core\Exception\ValidationException;910#[AsPublicPayload(11    path: '/search',12    methods: ['GET'],13    responseWith: SearchPageResource::class,14)]15final class SearchPayload16{17    protected string $query = '';1819    public function getQuery(): string20    {21        return $this->query;22    }2324    public function setQuery(string $query): void25    {26        $query = trim($query);2728        if ($query === '') {29            throw new ValidationException(['query' => ['Search query is required.']]);30        }3132        if (strlen($query) > 120) {33            throw new ValidationException(['query' => ['Search query must stay below 120 characters.']]);34        }3536        $this->query = $query;37    }38}39

<?php

declare(strict_types=1);

namespace App\Catalog\Application\Payload\Request;

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

#[AsPublicPayload(
    path: '/search',
    methods: ['GET'],
    responseWith: SearchPageResource::class,
)]
final class SearchPayload
{
    protected string $query = '';

    public function getQuery(): string
    {
        return $this->query;
    }

    public function setQuery(string $query): void
    {
        $query = trim($query);

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

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

        $this->query = $query;
    }
}

1<?php23declare(strict_types=1);45namespace App\Catalog\Application\Handler;67use App\Catalog\Application\Payload\Request\SearchPayload;8use Semitexa\Core\Attribute\AsPayloadHandler;9use Semitexa\Core\Contract\TypedHandlerInterface;1011#[AsPayloadHandler(payload: SearchPayload::class, resource: SearchPageResource::class)]12final class SearchPageHandler implements TypedHandlerInterface13{14    public function handle(SearchPayload $payload, SearchPageResource $resource): SearchPageResource15    {16        return $resource17            ->withQuery($payload->getQuery())18            ->withCampaign($payload->getCampaign())19            ->withPreview($payload->isPreview());20    }21}22

<?php

declare(strict_types=1);

namespace App\Catalog\Application\Handler;

use App\Catalog\Application\Payload\Request\SearchPayload;
use Semitexa\Core\Attribute\AsPayloadHandler;
use Semitexa\Core\Contract\TypedHandlerInterface;

#[AsPayloadHandler(payload: SearchPayload::class, resource: SearchPageResource::class)]
final class SearchPageHandler implements TypedHandlerInterface
{
    public function handle(SearchPayload $payload, SearchPageResource $resource): SearchPageResource
    {
        return $resource
            ->withQuery($payload->getQuery())
            ->withCampaign($payload->getCampaign())
            ->withPreview($payload->isPreview());
    }
}

1<?php23declare(strict_types=1);45namespace App\Insights\Application\Payload\Part;67use App\Catalog\Application\Payload\Request\SearchPayload;8use Semitexa\Core\Attribute\AsPayloadPart;9use Semitexa\Core\Exception\ValidationException;1011#[AsPayloadPart(base: SearchPayload::class)]12trait SearchTrackingPart13{14    protected ?string $campaign = null;15    protected bool $preview = false;1617    public function getCampaign(): ?string18    {19        return $this->campaign;20    }2122    public function setCampaign(?string $campaign): void23    {24        $campaign = $campaign !== null ? trim($campaign) : null;2526        if ($campaign !== null && strlen($campaign) > 64) {27            throw new ValidationException(['campaign' => ['Campaign code must stay below 64 characters.']]);28        }2930        $this->campaign = $campaign !== '' ? $campaign : null;31    }3233    public function isPreview(): bool34    {35        return $this->preview;36    }3738    public function setPreview(bool $preview): void39    {40        $this->preview = $preview;41    }42}43

<?php

declare(strict_types=1);

namespace App\Insights\Application\Payload\Part;

use App\Catalog\Application\Payload\Request\SearchPayload;
use Semitexa\Core\Attribute\AsPayloadPart;
use Semitexa\Core\Exception\ValidationException;

#[AsPayloadPart(base: SearchPayload::class)]
trait SearchTrackingPart
{
    protected ?string $campaign = null;
    protected bool $preview = false;

    public function getCampaign(): ?string
    {
        return $this->campaign;
    }

    public function setCampaign(?string $campaign): void
    {
        $campaign = $campaign !== null ? trim($campaign) : null;

        if ($campaign !== null && strlen($campaign) > 64) {
            throw new ValidationException(['campaign' => ['Campaign code must stay below 64 characters.']]);
        }

        $this->campaign = $campaign !== '' ? $campaign : null;
    }

    public function isPreview(): bool
    {
        return $this->preview;
    }

    public function setPreview(bool $preview): void
    {
        $this->preview = $preview;
    }
}

1<?php23declare(strict_types=1);45namespace App\Insights\Application\Handler;67use App\Catalog\Application\Payload\Request\SearchPayload;8use Semitexa\Core\Attribute\AsPayloadHandler;9use Semitexa\Core\Contract\TypedHandlerInterface;1011#[AsPayloadHandler(payload: SearchPayload::class, resource: SearchAuditResource::class)]12final class SearchAuditHandler implements TypedHandlerInterface13{14    public function handle(SearchPayload $payload, SearchAuditResource $resource): SearchAuditResource15    {16        return $resource17            ->withQuery($payload->getQuery())18            ->withCampaign($payload->getCampaign())19            ->withPreview($payload->isPreview());20    }21}22

<?php

declare(strict_types=1);

namespace App\Insights\Application\Handler;

use App\Catalog\Application\Payload\Request\SearchPayload;
use Semitexa\Core\Attribute\AsPayloadHandler;
use Semitexa\Core\Contract\TypedHandlerInterface;

#[AsPayloadHandler(payload: SearchPayload::class, resource: SearchAuditResource::class)]
final class SearchAuditHandler implements TypedHandlerInterface
{
    public function handle(SearchPayload $payload, SearchAuditResource $resource): SearchAuditResource
    {
        return $resource
            ->withQuery($payload->getQuery())
            ->withCampaign($payload->getCampaign())
            ->withPreview($payload->isPreview());
    }
}

How it works

Why it matters

Key concepts

#[AsPayloadPart]: Marks a trait as an additive extension of an existing payload class.
PayloadFactory: Builds the runtime wrapper class that extends the base payload and mixes in discovered payload-part traits.
trait composition: Lets separate modules add typed setters, getters, and local guards to the same request boundary without modifying the base payload source.