ASYNC FEATURE
Queued Handler
Events survive restarts and scale across workers — backed by a durable message queue.
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
Queued events move side effects into a durable transport, so processing can survive restarts and scale beyond the current worker.
How it works
A listener marked with EventExecution::Queued serializes the event into the configured queue transport. Dedicated workers consume that transport, apply retry rules, and can route poison messages into a DLQ.
Why it matters
This is the boundary for heavy, failure-prone, or cross-worker work. The request stays fast, retries become explicit, and operational control moves out of the web request lifecycle.
Key concepts
- EventExecution::Queued
- Publishes listener work into a queue transport instead of running inline.
- DLQ
- Dead-letter queue for messages that keep failing and need operator review.
- durable transport
- A queue backend that keeps the message outside the worker memory lifecycle.
Durable Transport
Push the listener to a queue
Queued listeners survive restarts because the event payload is serialized into the transport instead of staying in worker memory.
#[AsEventListener(
event: DemoItemCreated::class,
execution: EventExecution::Queued,
queue: 'demo.notifications',
)]
final class DemoNotificationListener
{
public function handle(DemoItemCreated $event): void { ... }
}| Feature | Supported |
|---|---|
| Automatic retry on failure | Yes |
| Dead-letter queue (DLQ) | Yes |
| Cross-worker delivery | Yes |
| Priority queues | Yes |
| Survives worker restart | Yes |
Verified against Semitexa Ultimate 2026.09.19.1020
Queued Handler
Queued listeners are serialized into a durable transport and processed by separate workers. The event payload leaves worker memory and enters the queue, so the work survives restarts and can scale horizontally.
How it works
When an event is dispatched with EventExecution::Queued, the dispatcher serializes the event and pushes it to the configured transport (NATS by default). A queue worker picks it up independently of the originating request or worker process.
Why this matters
Async deferred execution runs in the same worker and is lost on restart. Queued execution survives crashes, scales across worker pools, and supports retry and dead-letter queue (DLQ) semantics. Use queued listeners for any work that must not be lost: payment processing, third-party webhook calls, import jobs, and similar durable side effects.
Queue feature support
- Automatic retry on failure
- Dead-letter queue (DLQ)
- Cross-worker delivery
- Priority queues
- Survives worker restart
How it works
A listener marked with EventExecution::Queued serializes the event into the configured queue transport. Dedicated workers consume that transport, apply retry rules, and can route poison messages into a DLQ.
Why it matters
This is the boundary for heavy, failure-prone, or cross-worker work. The request stays fast, retries become explicit, and operational control moves out of the web request lifecycle.
Key concepts
- EventExecution::Queued
- Publishes listener work into a queue transport instead of running inline.
- DLQ
- Dead-letter queue for messages that keep failing and need operator review.
- durable transport
- A queue backend that keeps the message outside the worker memory lifecycle.