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

Events decouple side effects from handlers. Dispatch an event and listeners react — notifications, cache invalidation, analytics.

How it works

EventDispatcher::create() builds the event, dispatch() triggers all registered listeners, and propagated events can also be mirrored into Semitexa Ledger for cross-node delivery. #[AsEventListener] marks listener classes. Default execution is synchronous in the same coroutine.

Why it matters

Events let handlers focus on the main task. Side effects belong in listeners, keeping handler code clean and each concern independently testable.

Key concepts

#[AsEventListener]: Registers a class as a listener for a specific event type.
#[Propagated]: Marks an event for ledger persistence and cross-node propagation when the ledger runtime is enabled.
EventDispatcher: Core service for creating and dispatching domain events.

Inline Dispatch

Fire an event in the current request

No event fired yet. Submit the form to dispatch DemoItemCreated.

#[AsEvent] EventExecution::Sync EventDispatcherInterface

Verified against Semitexa Ultimate 2026.09.19.1020

Sync Events

Synchronous listeners execute inline before the response is sent. When you dispatch an event in sync mode, every registered listener completes its work before the HTTP response is returned to the client.

Event execution modes

How it works

The event dispatcher calls each sync listener in registration order within the current request lifecycle. The response is not flushed until all sync listeners have returned.

Why this matters

Sync execution guarantees that listener side effects are complete before the client sees the response. This is the right choice for validation side effects, required audit writes, or any work the response depends on. When the ledger runtime is enabled, propagated events are also written to the node ledger after sync listener execution.

1<?php23declare(strict_types=1);45namespace App\Application\Event;67use Semitexa\Core\Attribute\AsEvent;89#[AsEvent]10final class DemoItemCreated11{12    public function __construct(13        public readonly string $itemId,14        public readonly string $itemName,15        public readonly string $section,16    ) {}17}18

<?php

declare(strict_types=1);

namespace App\Application\Event;

use Semitexa\Core\Attribute\AsEvent;

#[AsEvent]
final class DemoItemCreated
{
    public function __construct(
        public readonly string $itemId,
        public readonly string $itemName,
        public readonly string $section,
    ) {}
}

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::Sync)]12final class DemoItemCreatedListener13{14    public function handle(DemoItemCreated $event): void15    {16        // Update in-request projections, metrics, or audit context immediately.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::Sync)]
final class DemoItemCreatedListener
{
    public function handle(DemoItemCreated $event): void
    {
        // Update in-request projections, metrics, or audit context immediately.
    }
}

1<?php23declare(strict_types=1);45namespace App\Application\Handler\Events;67use App\Application\Event\DemoItemCreated;8use App\Application\Payload\Events\CreateDemoItemPayload;9use App\Application\Resource\Page\DemoItemResource;10use Semitexa\Core\Attribute\AsPayloadHandler;11use Semitexa\Core\Attribute\InjectAsReadonly;12use Semitexa\Core\Contract\TypedHandlerInterface;13use Semitexa\Core\Event\EventDispatcherInterface;1415#[AsPayloadHandler(payload: CreateDemoItemPayload::class, resource: DemoItemResource::class)]16final class SyncEventHandler implements TypedHandlerInterface17{18    #[InjectAsReadonly]19    protected ?EventDispatcherInterface $eventDispatcher = null;2021    public function handle(CreateDemoItemPayload $payload, DemoItemResource $resource): DemoItemResource22    {23        $event = new DemoItemCreated($payload->getId(), $payload->getName(), 'catalog');24        if ($this->eventDispatcher === null) {25            return $resource->withStatus('not_dispatched');26        }2728        $this->eventDispatcher->dispatch($event);29        return $resource->withStatus('dispatched');30    }31}32

<?php

declare(strict_types=1);

namespace App\Application\Handler\Events;

use App\Application\Event\DemoItemCreated;
use App\Application\Payload\Events\CreateDemoItemPayload;
use App\Application\Resource\Page\DemoItemResource;
use Semitexa\Core\Attribute\AsPayloadHandler;
use Semitexa\Core\Attribute\InjectAsReadonly;
use Semitexa\Core\Contract\TypedHandlerInterface;
use Semitexa\Core\Event\EventDispatcherInterface;

#[AsPayloadHandler(payload: CreateDemoItemPayload::class, resource: DemoItemResource::class)]
final class SyncEventHandler implements TypedHandlerInterface
{
    #[InjectAsReadonly]
    protected ?EventDispatcherInterface $eventDispatcher = null;

    public function handle(CreateDemoItemPayload $payload, DemoItemResource $resource): DemoItemResource
    {
        $event = new DemoItemCreated($payload->getId(), $payload->getName(), 'catalog');
        if ($this->eventDispatcher === null) {
            return $resource->withStatus('not_dispatched');
        }

        $this->eventDispatcher->dispatch($event);
        return $resource->withStatus('dispatched');
    }
}

How it works

Why it matters

Events let handlers focus on the main task. Side effects belong in listeners, keeping handler code clean and each concern independently testable.

Key concepts

#[AsEventListener]: Registers a class as a listener for a specific event type.
#[Propagated]: Marks an event for ledger persistence and cross-node propagation when the ledger runtime is enabled.
EventDispatcher: Core service for creating and dispatching domain events.