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

Async events run after the response is sent — via Swoole::defer() or a queue transport.

How it works

Set execution mode to Async or Queued on the listener attribute. Async defers to the event loop. Queued publishes to the configured queue transport for background processing.

Why it matters

Heavy side effects (email, external API calls) should not block the response. Async/queued execution keeps response times fast while ensuring side effects complete.

Key concepts

EventExecution::Async: Defers listener execution via Swoole::defer() — runs after response.
EventExecution::Queued: Publishes the event to a queue transport for background processing.

Post-Response Execution

Same worker, later in the lifecycle

Async listeners are scheduled with Swoole defer, so the client gets the response before the listener runs.

Mode	When it runs	Survives restart	Best for
`Sync`	Before response	N/A	Validation, required side-effects
`Async`	After response	No	Email, cache bust, audit log
`Queued`	Worker picks up	Yes	Heavy jobs, retry logic, cross-worker

Swoole\\Event::defer() post-response non-blocking

Verified against Semitexa Ultimate 2026.09.19.1020

Deferred Handler

Async listeners run after the response via Swoole defer in the same worker. The client receives the HTTP response immediately while the listener completes its work in the background.

How it works

The container schedules the listener using Swoole's defer mechanism. The HTTP response is flushed first, then the listener runs in the same worker process. This avoids delaying the current response, but heavy deferred work can still reduce throughput on that worker.

Why this matters

Long-running side effects — email, cache invalidation, audit logging — do not need to delay the response. Marking a listener EventExecution::Async gives users instant feedback while still guaranteeing the work runs. The tradeoff is that deferred work does not survive a worker restart, which is why durable side effects belong in the queued tier instead.

Execution mode comparison

Mode	When it runs	Survives restart	Best for
Sync	Before response	N/A	Validation, required side-effects
Async	After response	No	Email, cache bust, audit log
Queued	Worker picks up	Yes	Heavy jobs, retry logic, cross-worker

1<?php23declare(strict_types=1);45namespace App\Application\Listener;67use App\Application\Event\DemoItemCreated;8use Semitexa\Core\Attribute\AsEventListener;9use Semitexa\Core\Event\EventExecution;1011#[AsEventListener(event: DemoItemCreated::class, execution: EventExecution::Async)]12final class DemoNotificationListener13{14    public function handle(DemoItemCreated $event): void15    {16        // Send mail, write audit output, or refresh projections after the response.17    }18}19

<?php

declare(strict_types=1);

namespace App\Application\Listener;

use App\Application\Event\DemoItemCreated;
use Semitexa\Core\Attribute\AsEventListener;
use Semitexa\Core\Event\EventExecution;

#[AsEventListener(event: DemoItemCreated::class, execution: EventExecution::Async)]
final class DemoNotificationListener
{
    public function handle(DemoItemCreated $event): void
    {
        // Send mail, write audit output, or refresh projections after the response.
    }
}

1<?php23declare(strict_types=1);45namespace App\Application\Handler\Events;67use App\Application\Payload\Events\NotifyAfterResponsePayload;8use App\Application\Resource\Page\AsyncStatusResource;9use App\Domain\Notifications\NotificationSchedulerInterface;10use Semitexa\Core\Attribute\AsPayloadHandler;11use Semitexa\Core\Attribute\InjectAsReadonly;12use Semitexa\Core\Contract\TypedHandlerInterface;1314#[AsPayloadHandler(payload: NotifyAfterResponsePayload::class, resource: AsyncStatusResource::class)]15final class DeferredHandler implements TypedHandlerInterface16{17    #[InjectAsReadonly]18    protected NotificationSchedulerInterface $scheduler;1920    public function handle(NotifyAfterResponsePayload $payload, AsyncStatusResource $resource): AsyncStatusResource21    {22        $this->scheduler->scheduleDeferredNotification($payload->getUserId());2324        return $resource->withMode('async');25    }26}27

<?php

declare(strict_types=1);

namespace App\Application\Handler\Events;

use App\Application\Payload\Events\NotifyAfterResponsePayload;
use App\Application\Resource\Page\AsyncStatusResource;
use App\Domain\Notifications\NotificationSchedulerInterface;
use Semitexa\Core\Attribute\AsPayloadHandler;
use Semitexa\Core\Attribute\InjectAsReadonly;
use Semitexa\Core\Contract\TypedHandlerInterface;

#[AsPayloadHandler(payload: NotifyAfterResponsePayload::class, resource: AsyncStatusResource::class)]
final class DeferredHandler implements TypedHandlerInterface
{
    #[InjectAsReadonly]
    protected NotificationSchedulerInterface $scheduler;

    public function handle(NotifyAfterResponsePayload $payload, AsyncStatusResource $resource): AsyncStatusResource
    {
        $this->scheduler->scheduleDeferredNotification($payload->getUserId());

        return $resource->withMode('async');
    }
}

How it works

Set execution mode to Async or Queued on the listener attribute. Async defers to the event loop. Queued publishes to the configured queue transport for background processing.

Why it matters

Heavy side effects (email, external API calls) should not block the response. Async/queued execution keeps response times fast while ensuring side effects complete.

Key concepts

EventExecution::Async: Defers listener execution via Swoole::defer() — runs after response.
EventExecution::Queued: Publishes the event to a queue transport for background processing.