# Events

DBM Framework's EventDispatcher provides explicit in-process event/listener dispatch. It does not auto-discover listeners or provide a durable external message broker.

# Register listeners

Create event objects and listeners, then map them in bootstrap/events.php:

use App\Events\UserRegistered;
use App\Listeners\SendWelcomeEmail;

return [
    UserRegistered::class => [SendWelcomeEmail::class],
];

EventServiceProvider::register($dispatcher) loads this map. In DBM Platform, bootstrap/app.php obtains the dispatcher and registers the provider. A listener can be a callable, object, or class name. Class names are resolved through the dependency container when dispatched; listeners can implement ListenerInterface::handle(object $event): void.

# Synchronous dispatch

$dispatcher->dispatch(new UserRegistered($userId, $email));

dispatch() immediately calls listeners registered for that event's exact class. Exceptions from listeners can propagate to the caller and the HTTP/console exception boundary.

# Queued dispatch

$dispatcher->dispatchAsync(new UserRegistered($userId, $email));
// Later, from a worker or scheduled task:
$dispatcher->processQueue();

The current EventQueue serializes event objects into storage/events/dbm_event_queue.json. processQueue() pulls and removes the stored queue before dispatching the events. This is a small file-backed queue, not a transactional or retrying job system: a process failure during handling may lose queued work. The queue calls PHP unserialize(), so only trusted application code should be able to write to its queue file. Use a proper message broker for durable, concurrent, retryable delivery.

# Security events

SecurityEvent and EventSecurityLogger provide a path for recording security-related activity. Register listeners explicitly and avoid putting credentials, tokens, or other secrets in event payloads or logs.