Merge branch 'develop' into next

Author: lindyhopchris

CHANGELOG.md

@@ -12,6 +12,18 @@ All notable changes to this project will be documented in this file. This projec
 
 ## Unreleased
 
+## [5.2.0] - 2026-01-05
+
+### Added
+
+- New domain event dispatcher features:
+    - Can now use a PSR container for the domain event dispatcher to resolve both handlers and middleware. Inject the
+      service container via the first constructor argument. This works for all three domain event dispatchers.
+    - Domain events can now be mapped to handlers on a domain event dispatcher class via the `ListonTo` attribute.
+    - Middleware can now be added to a domain event dispatcher via the `Through` attribute.
+- The unit of work domain event dispatcher will now log debug messages when deferring and executing listeners. To enable
+  this, inject an optional logger instance via the constructor.
+
 ## [5.1.0] - 2026-01-01
 
 ### Added
@@ -612,6 +624,10 @@ All notable changes to this project will be documented in this file. This projec
 
 Initial release.
 
+[5.2.0]: https://github.com/cloudcreativity/ddd-modules/compare/v5.1.0...v5.2.0
+
+[5.1.0]: https://github.com/cloudcreativity/ddd-modules/compare/v5.0.0...v5.1.0
+
 [5.0.0]: https://github.com/cloudcreativity/ddd-modules/compare/v5.0.0-rc.4...v5.0.0
 
 [5.0.0-rc.4]: https://github.com/cloudcreativity/ddd-modules/compare/v5.0.0-rc.3...v5.0.0-rc.4

src/Application/DomainEventDispatching/Dispatcher.php

@@ -16,14 +16,22 @@
 use CloudCreativity\Modules\Contracts\Application\DomainEventDispatching\ListenerContainer as IListenerContainer;
 use CloudCreativity\Modules\Contracts\Domain\Events\DomainEvent;
 use CloudCreativity\Modules\Contracts\Domain\Events\DomainEventDispatcher;
-use CloudCreativity\Modules\Contracts\Toolkit\Pipeline\PipeContainer;
+use CloudCreativity\Modules\Contracts\Toolkit\Pipeline\PipeContainer as IPipeContainer;
 use CloudCreativity\Modules\Toolkit\Pipeline\MiddlewareProcessor;
+use CloudCreativity\Modules\Toolkit\Pipeline\PipeContainer;
 use CloudCreativity\Modules\Toolkit\Pipeline\PipelineBuilder;
+use CloudCreativity\Modules\Toolkit\Pipeline\Through;
 use Generator;
 use InvalidArgumentException;
+use Psr\Container\ContainerInterface;
+use ReflectionClass;
 
 class Dispatcher implements DomainEventDispatcher
 {
+    private readonly IListenerContainer $listeners;
+
+    private readonly ?IPipeContainer $middleware;
+
     /**
      * @var array<string, array<callable|string>>
      */
@@ -35,9 +43,18 @@ class Dispatcher implements DomainEventDispatcher
     private array $pipes = [];
 
     public function __construct(
-        private readonly IListenerContainer $listeners = new ListenerContainer(),
-        private readonly ?PipeContainer $middleware = null,
+        ContainerInterface|IListenerContainer $listeners = new ListenerContainer(),
+        ?IPipeContainer $middleware = null,
     ) {
+        $this->listeners = $listeners instanceof ContainerInterface ?
+            new ListenerContainer($listeners) :
+            $listeners;
+
+        $this->middleware = $middleware === null && $listeners instanceof ContainerInterface ?
+            new PipeContainer($listeners) :
+            $middleware;
+
+        $this->autowire();
     }
 
     /**
@@ -135,4 +152,18 @@ private function canAttach(mixed $listener): bool
 
         return is_string($listener) && !empty($listener);
     }
+
+    private function autowire(): void
+    {
+        $reflection = new ReflectionClass($this);
+
+        foreach ($reflection->getAttributes(ListenTo::class) as $attribute) {
+            $instance = $attribute->newInstance();
+            $this->listen($instance->event, $instance->listeners);
+        }
+
+        foreach ($reflection->getAttributes(Through::class) as $attribute) {
+            $this->pipes = $attribute->newInstance()->pipes;
+        }
+    }
 }

src/Application/DomainEventDispatching/EventHandler.php

@@ -16,20 +16,26 @@
 use CloudCreativity\Modules\Contracts\Application\UnitOfWork\DispatchAfterCommit;
 use CloudCreativity\Modules\Contracts\Application\UnitOfWork\DispatchBeforeCommit;
 use CloudCreativity\Modules\Contracts\Domain\Events\DomainEvent;
+use Stringable;
 
-final readonly class EventHandler
+final readonly class EventHandler implements Stringable
 {
     public function __construct(private object $listener)
     {
         assert(
             !($this->listener instanceof DispatchBeforeCommit && $this->listener instanceof DispatchAfterCommit),
             sprintf(
-                'Listener "%s" cannot be dispatched both before and after a unit of work is committed..',
+                'Listener "%s" cannot be dispatched both before and after a unit of work is committed.',
                 get_debug_type($this->listener),
             ),
         );
     }
 
+    public function __toString(): string
+    {
+        return $this->listener::class;
+    }
+
     /**
      * Should the handler be executed before the transaction is committed?
      */

src/Application/DomainEventDispatching/ListenTo.php

@@ -0,0 +1,28 @@
+<?php
+
+/*
+ * Copyright 2026 Cloud Creativity Limited
+ *
+ * Use of this source code is governed by an MIT-style
+ * license that can be found in the LICENSE file or at
+ * https://opensource.org/licenses/MIT.
+ */
+
+declare(strict_types=1);
+
+namespace CloudCreativity\Modules\Application\DomainEventDispatching;
+
+use Attribute;
+use CloudCreativity\Modules\Contracts\Domain\Events\DomainEvent;
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+final readonly class ListenTo
+{
+    /**
+     * @param class-string<DomainEvent> $event
+     * @param list<non-empty-string>|non-empty-string $listeners
+     */
+    public function __construct(public string $event, public array|string $listeners)
+    {
+    }
+}

src/Application/DomainEventDispatching/ListenerContainer.php

@@ -15,35 +15,51 @@
 use Closure;
 use CloudCreativity\Modules\Application\ApplicationException;
 use CloudCreativity\Modules\Contracts\Application\DomainEventDispatching\ListenerContainer as IListenerContainer;
+use Psr\Container\ContainerInterface;
 
 final class ListenerContainer implements IListenerContainer
 {
     /**
-     * @var array<non-empty-string,Closure>
+     * @var array<non-empty-string, Closure|string>
      */
     private array $bindings = [];
 
+    public function __construct(private readonly ?ContainerInterface $container = null)
+    {
+    }
+
     /**
      * Bind a listener factory into the container.
      *
      * @param non-empty-string $listenerName
-     * @param Closure():object $binding
+     * @param (Closure():object)|non-empty-string $binding
      */
-    public function bind(string $listenerName, Closure $binding): void
+    public function bind(string $listenerName, Closure|string $binding): void
     {
+        if (is_string($binding) && $this->container === null) {
+            throw new ApplicationException('Cannot use a string listener binding without a PSR container.');
+        }
+
         $this->bindings[$listenerName] = $binding;
     }
 
     public function get(string $listenerName): object
     {
-        $factory = $this->bindings[$listenerName] ?? null;
+        $binding = $this->bindings[$listenerName] ?? null;
 
-        if ($factory) {
-            $listener = $factory();
+        if ($binding instanceof Closure) {
+            $listener = $binding();
             assert(is_object($listener), "Listener binding for {$listenerName} must return an object.");
             return $listener;
         }
 
+        if ($this->container) {
+            $target = $binding ?? $listenerName;
+            $listener = $this->container->get($target);
+            assert(is_object($listener), "PSR container listener binding {$target} is not an object.");
+            return $listener;
+        }
+
         throw new ApplicationException('Unrecognised listener name: ' . $listenerName);
     }
 }

src/Application/DomainEventDispatching/UnitOfWorkAwareDispatcher.php

@@ -17,13 +17,16 @@
 use CloudCreativity\Modules\Contracts\Domain\Events\DomainEvent;
 use CloudCreativity\Modules\Contracts\Domain\Events\OccursImmediately;
 use CloudCreativity\Modules\Contracts\Toolkit\Pipeline\PipeContainer;
+use Psr\Container\ContainerInterface;
+use Psr\Log\LoggerInterface;
 
 class UnitOfWorkAwareDispatcher extends Dispatcher
 {
     public function __construct(
         private readonly UnitOfWorkManager $unitOfWorkManager,
-        IListenerContainer $listeners = new ListenerContainer(),
+        ContainerInterface|IListenerContainer $listeners = new ListenerContainer(),
         ?PipeContainer $middleware = null,
+        private readonly ?LoggerInterface $logger = null,
     ) {
         parent::__construct($listeners, $middleware);
     }
@@ -46,14 +49,30 @@ public function dispatch(DomainEvent $event): void
     protected function execute(DomainEvent $event, EventHandler $listener): void
     {
         if ($listener->beforeCommit()) {
-            $this->unitOfWorkManager->beforeCommit(static function () use ($event, $listener): void {
+            $this->logger?->debug('Deferring listener to be handled before commit.', [
+                'event' => $event::class,
+                'listener' => (string) $listener,
+            ]);
+            $this->unitOfWorkManager->beforeCommit(function () use ($event, $listener): void {
+                $this->logger?->debug('Executing listener before commit.', [
+                    'event' => $event::class,
+                    'listener' => (string) $listener,
+                ]);
                 $listener($event);
             });
             return;
         }
 
         if ($listener->afterCommit()) {
-            $this->unitOfWorkManager->afterCommit(static function () use ($event, $listener): void {
+            $this->logger?->debug('Deferring listener to be handled after commit.', [
+                'event' => $event::class,
+                'listener' => (string) $listener,
+            ]);
+            $this->unitOfWorkManager->afterCommit(function () use ($event, $listener): void {
+                $this->logger?->debug('Executing listener after commit.', [
+                    'event' => $event::class,
+                    'listener' => (string) $listener,
+                ]);
                 $listener($event);
             });
             return;

tests/Integration/Application/DomainEventDispatching/MathDomainEventDispatcher.php

@@ -0,0 +1,28 @@
+<?php
+
+/*
+ * Copyright 2026 Cloud Creativity Limited
+ *
+ * Use of this source code is governed by an MIT-style
+ * license that can be found in the LICENSE file or at
+ * https://opensource.org/licenses/MIT.
+ */
+
+declare(strict_types=1);
+
+namespace CloudCreativity\Modules\Tests\Integration\Application\DomainEventDispatching;
+
+use CloudCreativity\Modules\Application\DomainEventDispatching\ListenTo;
+use CloudCreativity\Modules\Application\DomainEventDispatching\Middleware\LogDomainEventDispatch;
+use CloudCreativity\Modules\Application\DomainEventDispatching\UnitOfWorkAwareDispatcher;
+use CloudCreativity\Modules\Toolkit\Pipeline\Through;
+
+#[ListenTo(NumbersAdded::class, TestDomainListener::class)]
+#[ListenTo(NumbersSubtracted::class, [
+    TestDomainListener::class,
+    TestDomainListener::class,
+])]
+#[Through(LogDomainEventDispatch::class)]
+final class MathDomainEventDispatcher extends UnitOfWorkAwareDispatcher
+{
+}

tests/Integration/Application/DomainEventDispatching/MathDomainEventDispatcherTest.php

@@ -0,0 +1,51 @@
+<?php
+
+/*
+ * Copyright 2026 Cloud Creativity Limited
+ *
+ * Use of this source code is governed by an MIT-style
+ * license that can be found in the LICENSE file or at
+ * https://opensource.org/licenses/MIT.
+ */
+
+declare(strict_types=1);
+
+namespace CloudCreativity\Modules\Tests\Integration\Application\DomainEventDispatching;
+
+use CloudCreativity\Modules\Application\DomainEventDispatching\Middleware\LogDomainEventDispatch;
+use CloudCreativity\Modules\Application\UnitOfWork\UnitOfWorkManager;
+use CloudCreativity\Modules\Testing\FakeContainer;
+use PHPUnit\Framework\TestCase;
+
+class MathDomainEventDispatcherTest extends TestCase
+{
+    public function test(): void
+    {
+        $container = new FakeContainer();
+        $listener = new TestDomainListener();
+        $unitOfWorkManager = new UnitOfWorkManager($container->unitOfWork);
+
+        $container->bind(TestDomainListener::class, fn () => $listener);
+        $container->bind(LogDomainEventDispatch::class, fn () => new LogDomainEventDispatch($container->logger));
+
+        $dispatcher = new MathDomainEventDispatcher(
+            unitOfWorkManager: $unitOfWorkManager,
+            listeners: $container,
+        );
+
+        $add = new NumbersAdded(1, 2, 3);
+        $subtract = new NumbersSubtracted(5, 4, 1);
+
+        $unitOfWorkManager->execute(function () use ($add, $subtract, $dispatcher) {
+            $dispatcher->dispatch($add);
+            $dispatcher->dispatch($subtract);
+        });
+
+        $this->assertSame([
+            $add,
+            $subtract,
+            $subtract,
+        ], $listener->events);
+        $this->assertCount(4, $container->logger);
+    }
+}

tests/Integration/Application/DomainEventDispatching/NumbersAdded.php

@@ -0,0 +1,34 @@
+<?php
+
+/*
+ * Copyright 2026 Cloud Creativity Limited
+ *
+ * Use of this source code is governed by an MIT-style
+ * license that can be found in the LICENSE file or at
+ * https://opensource.org/licenses/MIT.
+ */
+
+declare(strict_types=1);
+
+namespace CloudCreativity\Modules\Tests\Integration\Application\DomainEventDispatching;
+
+use CloudCreativity\Modules\Contracts\Domain\Events\DomainEvent;
+use CloudCreativity\Modules\Toolkit\Contracts;
+use DateTimeImmutable;
+
+final readonly class NumbersAdded implements DomainEvent
+{
+    public function __construct(
+        public int $a,
+        public int $b,
+        public int $sum,
+        public DateTimeImmutable $calculatedAt = new DateTimeImmutable(),
+    ) {
+        Contracts::assert($sum === ($a + $b), 'The sum must be equal to a plus b.');
+    }
+
+    public function getOccurredAt(): DateTimeImmutable
+    {
+        return $this->calculatedAt;
+    }
+}