PHPackages headsnet/domain-events-bundle - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. headsnet/domain-events-bundle ActiveSymfony-bundle[Utility & Helpers](/categories/utility) headsnet/domain-events-bundle ============================= Integrates domain events into your Symfony application v0.4.5(11mo ago)4216.8k↑75%4[2 issues](https://github.com/headsnet/domain-events-bundle/issues)MITPHPPHP ^8.1CI failing Since Mar 14Pushed 11mo ago1 watchersCompare [ Source](https://github.com/headsnet/domain-events-bundle)[ Packagist](https://packagist.org/packages/headsnet/domain-events-bundle)[ Docs](https://github.com/headsnet/domain-event-bundle)[ RSS](/packages/headsnet-domain-events-bundle/feed)WikiDiscussions main Synced yesterday READMEChangelog (10)Dependencies (13)Versions (25)Used By (0) Domain Event Bundle =================== [](#domain-event-bundle) [![Build Status](https://github.com/headsnet/domain-events-bundle/actions/workflows/ci.yml/badge.svg)](https://github.com/headsnet/domain-events-bundle/actions/workflows/ci.yml/badge.svg)[![Latest Stable Version](https://camo.githubusercontent.com/eec65644d83798c0ab5c1a1ec2498d057e90467eda16eb0873479d4911b4e95f/68747470733a2f2f706f7365722e707567782e6f72672f68656164736e65742f646f6d61696e2d6576656e74732d62756e646c652f76)](//packagist.org/packages/headsnet/domain-events-bundle)[![Total Downloads](https://camo.githubusercontent.com/1cd5f92c461f91cd2056af5d4a2f206131863764688019e451209792f6c879cd/68747470733a2f2f706f7365722e707567782e6f72672f68656164736e65742f646f6d61696e2d6576656e74732d62756e646c652f646f776e6c6f616473)](//packagist.org/packages/headsnet/domain-events-bundle)[![License](https://camo.githubusercontent.com/ffda8ff1c95bf1c6a0da514b6f8c27c775b710d9d04dc29472596214293ae170/68747470733a2f2f706f7365722e707567782e6f72672f68656164736e65742f646f6d61696e2d6576656e74732d62756e646c652f6c6963656e7365)](//packagist.org/packages/headsnet/domain-events-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 5.4 or higher.* ### Installation [](#installation) ``` composer require headsnet/domain-events-bundle ``` (see [Messenger Component](#messenger-component) below for prerequisites) ### The Domain Event Class [](#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. ``` use Headsnet\DomainEventsBundle\Domain\Model\DomainEvent; use Headsnet\DomainEventsBundle\Domain\Model\Traits\DomainEventTrait; final class DiscountWasApplied implements DomainEvent { use DomainEventTrait; public function __construct(string $aggregateRootId) { $this->aggregateRootId = $aggregateRootId; $this->occurredOn = (new \DateTimeImmutable)->format(DateTime::ATOM); } } ``` ### Recording Events [](#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. ``` use Headsnet\DomainEventsBundle\Domain\Model\ContainsEvents; use Headsnet\DomainEventsBundle\Domain\Model\RecordsEvents; use Headsnet\DomainEventsBundle\Domain\Model\Traits\EventRecorderTrait; class MyEntity implements ContainsEvents, RecordsEvents { use EventRecorderTrait; public function __construct(PropertyId $uuid) { $this->uuid = $uuid; // Record a domain event $this->record( new DiscountWasApplied($uuid->asString()) ); } } ``` 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 [](#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: ``` use App\Entity\User; use Headsnet\DomainEventsBundle\Doctrine\Event\PreAppendEvent; use Symfony\Component\EventDispatcher\EventSubscriberInterface; use Symfony\Component\Security\Core\Security; final class AssignDomainEventUser implements EventSubscriberInterface { private Security $security; public function __construct(Security $security) { $this->security = $security; } public static function getSubscribedEvents(): array { return [ PreAppendEvent::class => 'onPreAppend' ]; } public function onPreAppend(PreAppendEvent $event): void { $domainEvent = $event->getDomainEvent(); if (null === $domainEvent->getActorId()) { $user = $this->security->getUser(); if ($user instanceof User) { $domainEvent->setActorId($user->getId()); } } } } ``` ### Deferring Events Into The Future [](#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 [](#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 [](#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: ``` services: headsnet_domain_events.domain_event_dispatcher_service: class: App\Infrastructure\DomainEventDispatcher ``` ``` class PersonCreated implements DomainEvent, AuditableEvent { … } ``` ``` class DomainEventDispatcher implements \Headsnet\DomainEventsBundle\EventSubscriber\DomainEventDispatcher { private MessageBusInterface $eventBus; public function __construct(MessageBusInterface $eventBus) { $this->eventBus = $eventBus; } public function dispatch(DomainEvent $event): void { if ($event instanceof AuditableEvent) { $this->eventBus->dispatch( new Envelope($event, [new AuditStamp()]) ); } else { $this->eventBus->dispatch($event); } } } ``` ### Messenger Component [](#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](#default-configuration). ``` framework: messenger: … buses: messenger.bus.event: # Optional default_middleware: allow_no_handlers ``` [Symfony Messenger/Multiple Buses](https://symfony.com/doc/current/messenger/multiple_buses.html) ### Doctrine [](#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. ### Transaction Safety [](#transaction-safety) Events are only published when no database transaction is active. If the `kernel.TERMINATE` event fires while a database transaction is still open (including nested transactions), event publishing will be deferred until all transactions are committed. This prevents events from being published for data that might be rolled back, maintaining the integrity of the outbox pattern. ### Legacy Events Classes [](#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). ``` bin/console headsnet:domain-events:name-check ``` You can then define the `legacy_map` configuration parameter, to map old, legacy event class names to their new replacements. ``` headsnet_domain_events: legacy_map: App\Namespace\Event\YourLegacyEvent1: App\Namespace\Event\YourNewEvent1 App\Namespace\Event\YourLegacyEvent2: App\Namespace\Event\YourNewEvent2 ``` 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 [](#default-configuration) ``` headsnet_domain_events: message_bus: name: messenger.bus.event persistence: table_name: event legacy_map: [] ``` ### Contributing [](#contributing) Contributions are welcome. Please submit pull requests with one fix/feature per pull request. Composer scripts are configured for your convenience: ``` > composer test # Run test suite > composer cs # Run coding standards checks > composer cs-fix # Fix coding standards violations > composer static # Run static analysis with Phpstan ``` ### Health Score 45 — FairBetter than 91% of packages Maintenance49 Moderate activity, may be stable Popularity36 Limited adoption so far Community11 Small or concentrated contributor base Maturity69 Established project with proven stability Bus Factor1 Top contributor holds 83.1% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~100 days Recently: every ~53 days Total 24 Last Release 353d ago PHP version history (3 changes)v0.0.1PHP >=7.2 v0.2.0PHP ^7.4 || ^8.0.2 || ^8.1 v0.3.0PHP ^8.1 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/2156742?v=4)[Ben Roberts](/maintainers/benr77)[@benr77](https://github.com/benr77) --- Top Contributors [![benr77](https://avatars.githubusercontent.com/u/2156742?v=4)](https://github.com/benr77 "benr77 (69 commits)")[![wazum](https://avatars.githubusercontent.com/u/146727?v=4)](https://github.com/wazum "wazum (14 commits)") --- Tags bundledddobserver patterndomain-event ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StyleECS Type Coverage Yes ### Embed Badge ![Health badge](/badges/headsnet-domain-events-bundle/health.svg) ``` [![Health](https://phpackages.com/badges/headsnet-domain-events-bundle/health.svg)](https://phpackages.com/packages/headsnet-domain-events-bundle) ``` ### Alternatives [easycorp/easyadmin-bundle Admin generator for Symfony applications 4.3k17.9M388](/packages/easycorp-easyadmin-bundle)[open-dxp/opendxp Content & Product Management Framework (CMS/PIM) 9421.6k61](/packages/open-dxp-opendxp)[pimcore/pimcore Content & Product Management Framework (CMS/PIM/E-Commerce) 3.8k3.8M508](/packages/pimcore-pimcore)[prestashop/prestashop PrestaShop is an Open Source e-commerce platform, committed to providing the best shopping cart experience for both merchants and customers. 9.1k17.8k](/packages/prestashop-prestashop)[sylius/sylius E-Commerce platform for PHP, based on Symfony framework. 8.5k5.9M737](/packages/sylius-sylius)[2lenet/crudit-bundle The easy like Crud'it Bundle. 1616.4k14](/packages/2lenet-crudit-bundle) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)