START HERE FEATURE
Module Structure
Start with the smallest useful module shape, then expand the system around it instead of hiding the request path under the product shell.
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 minimal Semitexa module is a typed HTTP spine of payload, handler, resource, and template.
File tree: a contact form module example
Each file points to the page that explains that concern in more detail.
packages/semitexa-demo/src/Application/
├── Payload/
│ └── Request/
│ └── ContactFormPayload.php
├── Handler/
│ └── PayloadHandler/
│ └── ContactFormHandler.php
├── Resource/
│ └── Response/
│ └── ContactFormResource.php
└── View/
└── templates/
└── pages/
└── contact-form.html.twigRead it as the smallest useful path: request boundary, use case, response, presentation.
Verified against Semitexa Ultimate 2026.10.03.1952
Module Structure
A Semitexa module begins with one minimal HTTP spine:
- payload
- handler
- resource
- template
Everything else extends that path. Nothing replaces it.
Responsibility split
Payload
Owns the route contract and inbound data boundary.
Handler
Owns the use case and orchestration.
Resource
Owns response data, metadata, and render context.
Template
Owns presentation only.
Why this matters
First-time readers should be able to explain a module in one sentence before they learn the whole catalog. The small typed spine keeps the request path legible while the product shell can grow around it.
Canonical folder layout
A project module lives in src/modules/<Module>/. Its PHP code is under src/modules/<Module>/src/, in the namespace App\Modules\<Module>\. LocalModuleAutoloadRegistrar maps that namespace at boot, so a new module needs no composer dump-autoload and no registry entry. bin/semitexa make:module --name=<Module> --target=custom --write creates the skeleton. The starter Hello module in a new project is a working example.
All paths below are relative to src/modules/<Module>/src/.
Payload: Application/Payload/{Type}/
| Subfolder | Purpose | Attribute / usage |
|---|---|---|
| Request | HTTP request DTOs (route + methods) | #[AsPublicPayload(path, methods, responseWith)] (or #[AsProtectedPayload] / #[AsServicePayload]); discovered from the attribute, no registration step |
| Session | Session segment DTOs | #[SessionSegment('name')]; SessionInterface::getPayload() / setPayload() |
| Event | Event DTOs for dispatch | Used with EventDispatcher::create(EventClass::class, [...]) and dispatch() |
| Part | Reusable payload traits | #[AsPayloadPart] |
Namespaces: App\Modules\{Module}\Application\Payload\Request\, ...\Payload\Session\, ...\Payload\Event\.
Do not put these in Application/Session/ or other ad-hoc folders. Use Application/Payload/Request/, Payload/Session/, Payload/Event/, Payload/Part/ only.
Request DTOs declare access through one of #[AsPublicPayload] / #[AsProtectedPayload] / #[AsServicePayload], and finer requirements through #[RequiresPermission('name')] or #[RequiresCapability('name')].
Handler: Application/Handler/{Type}/
| Subfolder | Purpose | Attribute |
|---|---|---|
| PayloadHandler | HTTP handlers (payload → resource) | #[AsPayloadHandler(payload: ..., resource: ...)] |
| SlotHandler | Logic for a page slot | #[AsSlotHandler(slot: ...)] |
| DomainListener | Domain event listeners (sync/async/queued) | #[AsEventListener(event: ..., execution: ...)] |
Pipeline listeners (#[AsPipelineListener]) and Swoole server lifecycle listeners (#[AsServerLifecycleListener]) are services, not handlers: put them under Application/Service/, for example Application/Service/Server/Lifecycle/.
Full layout
src/modules/<Module>/
├── composer.json # optional
├── tests/
└── src/
└── Application/
├── Payload/
│ ├── Request/ # HTTP request DTOs
│ ├── Session/ # Session segment DTOs
│ ├── Event/ # Event DTOs
│ └── Part/ # Payload part traits
├── Handler/
│ ├── PayloadHandler/ # HTTP handlers
│ ├── SlotHandler/ # Slot handlers
│ └── DomainListener/ # Domain event listeners
├── Resource/
│ ├── Response/ # Response DTOs
│ └── Slot/ # Slot resources
├── Service/ # optional; also pipeline and server lifecycle listeners
├── Console/Command/ # optional; console commands
├── Static/ # optional; css/, js/, assets.json
└── View/
├── locales/
└── templates/
src/Domain/ sits next to src/Application/ for models, repository interfaces and domain services. The complete allowlist, which ai:verify enforces, is in the module-structure reference (MODULE_STRUCTURE.md in semitexa/docs).