Download the PHP package headsnet/domain-events-bundle without Composer

Domain Event Bundle

DDD Domain Events for Symfony, with a Doctrine based event store.

This package allows you to dispatch domain events from within your domain model, so that they are persisted in the same transaction as your aggregate.

These events are then published using a Symfony event listener in the kernel.TERMINATE event.

This ensures transactional consistency and guaranteed delivery via the Outbox pattern.

Requires Symfony 4.4 or higher

Installation

(see Messenger Component below for prerequisites)

The Domain Event Class

A domain event class must be instantiated with an aggregate root ID.

You can add other parameters to the constructor as required.

Recording Events

Domain events should be dispatched from within your domain model - i.e. from directly inside your entities.

Here we record a domain event for entity creation. It is then automatically persisted to the Doctrine event database table in the same database transaction as the main entity is persisted.

Then, in kernel.TERMINATE event, a listener automatically publishes the domain event on to the messenger.bus.event event bus for consumption elsewhere.

Amending domain events

Even though events should be treated as immutable, it might be convenient to add or change meta data before adding them to the event store.

Before a domain event is appended to the event store, the standard Doctrine event store emits a PreAppendEvent Symfony event, which can be used e.g. to set the actor ID as in the following example:

Deferring Events Into The Future

If you specify a future date for the DomainEvent::occurredOn the event will not be published until this date.

This allows scheduling of tasks directly from within the domain model.

Replaceable Future Events

If an event implements ReplaceableDomainEvent instead of DomainEvent, recording multiple instances of the same event for the same aggregate root will overwrite previous recordings of the event, as long as it is not yet published.

For example, say you have an aggregate Booking, which has a future ReminderDue event. If the booking is then modified to have a different date/time, the reminder must also be modified. By implementing ReplaceableDomainEvent, you can simply record a new ReminderDue event, and providing that the previous ReminderDue event had not been published, it will be removed and superseded by the new ReminderDue event.

Event dispatching

By default only the DomainEvent is dispatched to the configured event bus.

You can overwrite the default event dispatcher with your own implementation to annotate the message before dispatching it, e.g. to add an envelope with custom stamps.

Example:

Messenger Component

By default, the bundle expects a message bus called messenger.bus.event to be available. This can be configured using the bundle configuration - see Default Configuration.

Symfony Messenger/Multiple Buses

Doctrine

The bundle will create a database table called event to persist the events before dispatch. This allows a permanent record of all events raised.

The database table name can be configured - see Default Configuration below.

The StoredEvent entity also tracks whether each event has been published to the bus or not.

Finally, a Doctrine DBAL custom type called datetime_immutable_microseconds is automatically registered. This allows the StoredEvent entity to persist events with microsecond accuracy. This ensures that events are published in the exact same order they are recorded.

Legacy Events Classes

During refactorings, you may well move or rename event classes. This will result in legacy class names being stored in the database.

There is a console command, which will report on these legacy event classes that do not match an existing, current class in the codebase (based on the Composer autoloading).

You can then define the legacy_map configuration parameter, to map old, legacy event class names to their new replacements.

Then you can re-run the console command with the --fix option. This will then update the legacy class names in the database with their new references.

There is also a --delete option which will remove all legacy events from the database if they are not found in the legacy map. THIS IS A DESTRUCTIVE COMMAND PLEASE USE WITH CAUTION.

Default Configuration

Contributing

Contributions are welcome. Please submit pull requests with one fix/feature per pull request.

Composer scripts are configured for your convenience: