dsantang/domain-events-doctrine

Package that provides an integration with Doctrine ORM to automatically dispatch Domain Events.

v0.10.0 2023-01-04 18:00 UTC

Requires

• php: ^8.1
• doctrine/dbal: ^3.5
• doctrine/orm: ^2.8
• dsantang/domain-events: ^0.5
• ramsey/uuid: ^4.1
• symfony/event-dispatcher: ^5.2
• symfony/event-dispatcher-contracts: ^2.4

Requires (Dev)

• doctrine/coding-standard: ^9.0
• infection/infection: ^0.26
• maglnet/composer-require-checker: ^3.2
• ocramius/package-versions: ^2.7
• phpstan/phpstan: ^1.8
• phpstan/phpstan-phpunit: ^1.1
• phpstan/phpstan-strict-rules: ^1.4
• phpunit/phpunit: ^9.5
• squizlabs/php_codesniffer: ^3.6

Suggests

• symfony/event-dispatcher: To be able to dispatch domain events via a Symfony's EventDispatcherInterface.

MIT

• Davide Santangelo

• orm
• doctrine
• dispatcher
• Domain Driven Design
• domain event

README

This package is meant to be used in conjunction with dsantang/domain-events,
which provides the basic building blocks needed in order to create your application's domain events.
This package provides an integration with Doctrine ORM,
in order to automatically dispatch the recorded domain events once the ORM's flush() operation is successful.
Events are dispatched via a Symfony's EventDispatcherInterface.

Installation

The suggested installation method is via composer:

php composer.phar require dsantang/domain-events-doctrine

Configuration

In order to automagically dispatch your domain events, you first need to add two event listeners to your Doctrine's EventManager. These Doctrine's listeners will be listening to Doctrine's lifecycle events, and, only once the transaction has successfully been made, they'll dispatch your domain events.

use Dsantang\DomainEventsDoctrine\EventsRecorder\DoctrineEventsRecorder;
use Dsantang\DomainEventsDoctrine\Dispatcher\DoctrineEventsDispatcher;
use Symfony\Component\EventDispatcher\EventDispatcher;
use Doctrine\Common\EventManager;

// ...

$evm = new EventManager();

$dispatcher = new EventDispatcher();

// You can register here your domain event listeners to your dispatcher...

$tracker = new EventsTracker();

// Make sure they share the same `EventsTracker` instance.
$evm->addEventListener([Events::onFlush], new DoctrineEventsRecorder($tracker));
$evm->addEventListener([Events::postFlush], new DoctrineEventsDispatcher($tracker, $dispatcher));

// Remember to correctly wire this EventManager to your ORM.

That's it! You're all set! Now you can add as many Symfony's listeners as you need to your $dispatcher,
and you'll be able to react to the domain events raised by your application.

Outbox pattern

This library also provides support for the Outbox pattern implementation.
The idea behind the implementation is to be able to add entities to an "ongoing" transaction by hooking into Doctrine's onFlush event, creating "outbox" entries based on the application's domain events, and safely store them using the same DB transaction.

In order to enrich your Domain Event and be able to set all the data required by the Outbox entity, you need to create a Converter class (by implementing Dsantang\DomainEventsDoctrine\Outbox\Converter interface) An example of an outbox event is as follows:

use Dsantang\DomainEvents\DomainEvent;
use Dsantang\DomainEventsDoctrine\Outbox\Converter;
use Dsantang\DomainEventsDoctrine\Outbox\OutboxEntry;
use Ramsey\Uuid\Uuid;
use Ramsey\Uuid\UuidInterface;

final class YourOutboxConverter implements Converter
{
    public function convert(DomainEvent $domainEvent) : OutboxEntry
    {
        return new YourOutboxEntry($domainEvent);
    }
}

final class YourOutboxEntry implements OutboxEntry
{
    /** @var DomainEvent */
    private $domainEvent;

    public function __construct(DomainEvent $domainEvent)
    {
        $this->domainEvent = $domainEvent;
    }
    
    public function getName() : string
    {
        return 'OrderDispatched';
    }

    public function getAggregateId() : UuidInterface
    {
        return Uuid::fromString('d1702762-548b-11e9-8647-d663bd873d93');
    }

    public function getAggregateType() : string
    {
        return 'Order';
    }

    public function getPayloadType() : string
    {
        return 'OrderStructure';
    }

    public function getMessageKey() : string
    {
        return 'd663bd873d93';
    }

    public function getMessageRoute() : string
    {
        return 'aggregate.order';
    }

    public function getMessageType() : string
    {
        return 'OrderCreated';
    }

    public function getPayload() : string
    {
        return json_encode($this->domainEvent)
    }

    public function getSchemaVersion() : int
    {
        return 1;
    }
}    

In order to persist your Outbox entries, you must create a Doctrine Entity class inside your application that extends Dsantang\DomainEventsDoctrine\Outbox\OutboxMappedSuperclass.
Please note that this approach uses Doctrine's Inheritance Mapping:

Here is an example of an Outbox Entity class:

namespace YourNamespace;

use Doctrine\ORM\Mapping as ORM;
use Dsantang\DomainEventsDoctrine\Outbox\OutboxMappedSuperclass;

/**
 * @ORM\Entity()
 * @ORM\Table
 */
class YourOutboxEntity extends OutboxMappedSuperclass
{
    /**
     * @ORM\Column(type="string")
     *
     * @var string
     */
    private $someAdditionalField;
}

And an example of the required configuration as is follows:
Warning: this solution assumes that you're using Dsantang\DomainEvents\DomainEvent in order to raise your domain events.

use Dsantang\DomainEventsDoctrine\Outbox\MapBased;
use Dsantang\DomainEventsDoctrine\Outbox\OutboxMappedSuperclass;

// Your class must extend OutboxMappedSuperclass
$yourOutboxEntity = new YourOutboxEntity();

$mapBased = new MapBased($yourOutboxEntity);
$mapBased->addConverter('YouNamespace\YourDomainEvent', new YourOutboxConverter());

// Always use with OnFlush event
$evm->addEventListener([Events::onFlush], $mapBased);