Merge branch 'release/5.1.0'

Author: lindyhopchris

CHANGELOG.md

@@ -5,6 +5,53 @@ All notable changes to this project will be documented in this file. This projec
 
 ## Unreleased
 
+## [5.1.0] - 2026-01-01
+
+### Added
+
+- New command bus features:
+    - Can now use a PSR container for the command bus to resolve both handlers and middleware. Inject the service
+      container via the first constructor argument.
+    - Commands can now be mapped to handlers on a command bus class via the `WithCommand` attribute.
+    - Middleware can now be added to a command bus via the `Through` attribute.
+- New query bus features:
+    - Can now use a PSR container for the query bus to resolve both handlers and middleware. Inject the service
+      container via the first constructor argument.
+    - Queries can now be mapped to handlers on a query bus class via the `WithQuery` attribute.
+    - Middleware can now be added to a query bus via the `Through` attribute.
+- New inbound event bus features:
+    - Can now use a PSR container for the inbound event bus to resolve both handlers and middleware. Inject the service
+      container via the first constructor argument.
+    - Integration events can now be mapped to handlers on an inbound event bus class via the `WithEvent` attribute.
+    - The default handler can be set on the inbound event bus via the `WithDefault` attribute.
+    - Middleware can now be added to an inbound event bus via the `Through` attribute.
+- New outbound event bus features, when using the component publisher:
+    - Can now use a PSR container for the outbound event bus to resolve both publishers and middleware. Inject the
+      service container via the constructor.
+    - Integration events can now be mapped to publishers on a publisher handler container class via the `Publishes`
+      attribute.
+    - The default publisher can be set on the outbound event publisher via the `DefaultPublisher` attribute.
+    - Middleware can now be added to an outbound event publisher via the `Through` attribute.
+- New queue features, when using the component queue:
+    - Can now use a PSR container for the queue to resolve both enqueuers and middleware. Inject the service container
+      via the constructor.
+    - Commands can now be mapped to enqueuers on a publisher handler container class via the `Queues` attribute.
+    - The default enqueuer can be set on the outbound event publisher via the `DefaultEnqueuer` attribute.
+    - Middleware can now be added to the queue via the `Through` attribute.
+- In the Application layer, the `QueryHandlerContainer`, `CommandHandlerContainer` and `EventHandlerContainer` classes
+  can now fall back to resolving handlers from a PSR service container. Inject the service container via their
+  constructors.
+- In the Infrastructure layer, the `PublisherHandlerContainer` and `EnqueuerContainer` can now fall back to resolving
+  handlers/enqueuers from a PSR service container. Inject the service container via the constructor.
+- The outbound event bus `ClosurePublisher` and the `ClosureQueue` classes now both accept a PSR container for their
+  middleware. Additionally, middleware can be set on instances of closure publishers via the `Through` attribute.
+- The pipeline `PipeContainer` class can now fall back to resolving pipes from a PSR service container. Inject the
+  service container via the pipe container's only constructor argument.
+- The `FakeUnitOfWork` class now has integer properties for the number of attempts, commits and rollbacks.
+- New `FakeContainer` class for faking a PSR container in tests.
+- Added `UuidV4` and `UuidV7` identifiers, for use by implementations that need to enforce use of specific UUID
+  versions.
+
 ## [5.0.0] - 2025-12-09
 
 ### Added
@@ -97,7 +144,7 @@ All notable changes to this project will be documented in this file. This projec
 - **BREAKING** The error and error list interfaces now accept `UnitEnum` instead of `BackedEnum` for error codes.
   Although technically breaking, this will only affect your implementation if you have implemented these interfaces. All
   concrete classes provided by this package have been updated.
-- **BREAKING**: The key of an error can now be a enum - previously only strings were accepted. This is only breaking if
+- **BREAKING**: The key of an error can now be an enum - previously only strings were accepted. This is only breaking if
   you have implemented the interface yourself.
 - Updated `KeyedSetOfErrors` to handle error keys now being strings or enums.
 - **BREAKING**: The `Guid::make()` method will now convert a string that is a UUID to a UUID GUID. Previously it would
@@ -306,8 +353,8 @@ All notable changes to this project will be documented in this file. This projec
   the `Contracts\Application\Ports` namespace, with them differentiated between driving and driven ports.
 - **BREAKING** As a number of interfaces had to be moved to a `Ports` namespace, we've tidied them all up by removing
   the `Interface` suffix and moving them to a `Contracts` namespace.
-- **BREAKING** We've also removed the `Trait` suffix from traits. To avoid collisions with interfaces, we've use `Is` a
-  prefix where it makes sense. For example, `EntityTrait` has become `IsEntity`.
+- **BREAKING** We've also removed the `Trait` suffix from traits. To avoid collisions with interfaces, we've used an
+  `Is` prefix where it makes sense. For example, `EntityTrait` has become `IsEntity`.
 - **BREAKING** The `DomainEventDispatching` namespace has been moved from `Infrastructure` to `Application`. This was
   needed for the new hexagonal architecture approach, but also makes it a lot clearer that domain events are the way the
   domain layer communicates with the application layer.
@@ -558,6 +605,8 @@ All notable changes to this project will be documented in this file. This projec
 
 Initial release.
 
+[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
 
 [5.0.0-rc.3]: https://github.com/cloudcreativity/ddd-modules/compare/v5.0.0-rc.2...v5.0.0-rc.3

composer.json

@@ -23,9 +23,11 @@
     "require": {
         "php": "^8.2",
         "ext-json": "*",
+        "psr/container": "^2.0",
         "psr/log": "^2.0 || ^3.0",
         "ramsey/uuid": "^4.7",
-        "symfony/polyfill-php84": "^1.33"
+        "symfony/polyfill-php84": "^1.33",
+        "symfony/polyfill-php85": "^1.33"
     },
     "require-dev": {
         "deptrac/deptrac": "^4.4",

deptrac.yaml

@@ -28,6 +28,10 @@ deptrac:
           value: CloudCreativity\\Modules\\Contracts\\Infrastructure\\*
         - type: classLike
           value: CloudCreativity\\Modules\\Infrastructure\\*
+    - name: PSR Container
+      collectors:
+        - type: classLike
+          value: Psr\\Container\\*
     - name: PSR Log
       collectors:
         - type: classLike
@@ -39,17 +43,20 @@ deptrac:
   ruleset:
     Toolkit:
       - Attributes
+      - PSR Container
     Domain:
       - Toolkit
       - Attributes
     Application:
       - Toolkit
       - Domain
+      - PSR Container
       - PSR Log
       - Attributes
     Infrastructure:
       - Toolkit
       - Domain
       - Application
+      - PSR Container
       - PSR Log
       - Attributes

phpunit.xml

@@ -19,6 +19,9 @@
         <testsuite name="Unit">
             <directory suffix="Test.php">./tests/Unit/</directory>
         </testsuite>
+        <testsuite name="Integration">
+            <directory suffix="Test.php">./tests/Integration/</directory>
+        </testsuite>
     </testsuites>
     <php>
         <ini name="error_reporting" value="E_ALL"/>

src/Application/ApplicationException.php

@@ -1,7 +1,7 @@
 <?php
 
 /*
- * Copyright 2025 Cloud Creativity Limited
+ * 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

src/Application/Bus/CommandDispatcher.php

@@ -1,7 +1,7 @@
 <?php
 
 /*
- * Copyright 2025 Cloud Creativity Limited
+ * 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
@@ -12,25 +12,42 @@
 
 namespace CloudCreativity\Modules\Application\Bus;
 
-use CloudCreativity\Modules\Contracts\Application\Bus\CommandHandlerContainer;
+use CloudCreativity\Modules\Contracts\Application\Bus\CommandHandlerContainer as ICommandHandlerContainer;
 use CloudCreativity\Modules\Contracts\Application\Ports\Driving\CommandDispatcher as ICommandDispatcher;
 use CloudCreativity\Modules\Contracts\Toolkit\Messages\Command;
-use CloudCreativity\Modules\Contracts\Toolkit\Pipeline\PipeContainer;
+use CloudCreativity\Modules\Contracts\Toolkit\Pipeline\PipeContainer as IPipeContainer;
 use CloudCreativity\Modules\Contracts\Toolkit\Result\Result;
 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 Psr\Container\ContainerInterface;
+use ReflectionClass;
 
 class CommandDispatcher implements ICommandDispatcher
 {
+    private readonly ICommandHandlerContainer $handlers;
+
+    private readonly ?IPipeContainer $middleware;
+
     /**
      * @var array<callable|string>
      */
     private array $pipes = [];
 
     public function __construct(
-        private readonly CommandHandlerContainer $handlers,
-        private readonly ?PipeContainer $middleware = null,
+        ContainerInterface|ICommandHandlerContainer $handlers,
+        ?IPipeContainer $middleware = null,
     ) {
+        $this->handlers = $handlers instanceof ContainerInterface ?
+            new CommandHandlerContainer($handlers) :
+            $handlers;
+
+        $this->middleware = $middleware === null && $handlers instanceof ContainerInterface
+            ? new PipeContainer($handlers)
+            : $middleware;
+
+        $this->autowire();
     }
 
     /**
@@ -77,4 +94,21 @@ private function execute(Command $command): Result
 
         return $result;
     }
+
+    private function autowire(): void
+    {
+        $reflection = new ReflectionClass($this);
+
+        if ($this->handlers instanceof CommandHandlerContainer) {
+            foreach ($reflection->getAttributes(WithCommand::class) as $attribute) {
+                $instance = $attribute->newInstance();
+                $this->handlers->bind($instance->command, $instance->handler);
+            }
+        }
+
+        foreach ($reflection->getAttributes(Through::class) as $attribute) {
+            $instance = $attribute->newInstance();
+            $this->pipes = $instance->pipes;
+        }
+    }
 }

src/Application/Bus/CommandHandler.php

@@ -1,7 +1,7 @@
 <?php
 
 /*
- * Copyright 2025 Cloud Creativity Limited
+ * 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
@@ -12,13 +12,15 @@
 
 namespace CloudCreativity\Modules\Application\Bus;
 
+use CloudCreativity\Modules\Application\Messages\HandlesMessages;
 use CloudCreativity\Modules\Contracts\Application\Bus\CommandHandler as ICommandHandler;
-use CloudCreativity\Modules\Contracts\Application\Messages\DispatchThroughMiddleware;
 use CloudCreativity\Modules\Contracts\Toolkit\Messages\Command;
 use CloudCreativity\Modules\Contracts\Toolkit\Result\Result;
 
 final readonly class CommandHandler implements ICommandHandler
 {
+    use HandlesMessages;
+
     public function __construct(private object $handler)
     {
     }
@@ -37,13 +39,4 @@ public function __invoke(Command $command): Result
 
         return $result;
     }
-
-    public function middleware(): array
-    {
-        if ($this->handler instanceof DispatchThroughMiddleware) {
-            return $this->handler->middleware();
-        }
-
-        return [];
-    }
 }

src/Application/Bus/CommandHandlerContainer.php

@@ -1,7 +1,7 @@
 <?php
 
 /*
- * Copyright 2025 Cloud Creativity Limited
+ * 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
@@ -16,33 +16,48 @@
 use CloudCreativity\Modules\Application\ApplicationException;
 use CloudCreativity\Modules\Contracts\Application\Bus\CommandHandlerContainer as ICommandHandlerContainer;
 use CloudCreativity\Modules\Contracts\Toolkit\Messages\Command;
+use Psr\Container\ContainerInterface;
 
 final class CommandHandlerContainer implements ICommandHandlerContainer
 {
     /**
-     * @var array<class-string<Command>, Closure>
+     * @var array<class-string<Command>, class-string|Closure>
      */
     private array $bindings = [];
 
+    public function __construct(private readonly ?ContainerInterface $container = null)
+    {
+    }
+
     /**
      * Bind a command handler into the container.
      *
      * @param class-string<Command> $commandClass
-     * @param Closure(): object $binding
+     * @param class-string|(Closure(): object) $binding
      */
-    public function bind(string $commandClass, Closure $binding): void
+    public function bind(string $commandClass, Closure|string $binding): void
     {
+        if (is_string($binding) && $this->container === null) {
+            throw new ApplicationException('Cannot use a string command handler binding without a PSR container.');
+        }
+
         $this->bindings[$commandClass] = $binding;
     }
 
     public function get(string $commandClass): CommandHandler
     {
-        $factory = $this->bindings[$commandClass] ?? null;
+        $binding = $this->bindings[$commandClass] ?? null;
+
+        if ($binding instanceof Closure) {
+            $instance = $binding();
+            assert(is_object($instance), "Command handler binding for {$commandClass} must return an object.");
+            return new CommandHandler($instance);
+        }
 
-        if ($factory) {
-            $innerHandler = $factory();
-            assert(is_object($innerHandler), "Command handler binding for {$commandClass} must return an object.");
-            return new CommandHandler($innerHandler);
+        if (is_string($binding)) {
+            $instance = $this->container?->get($binding);
+            assert(is_object($instance), "PSR container command handler binding {$binding} is not an object.");
+            return new CommandHandler($instance);
         }
 
         throw new ApplicationException('No command handler bound for command class: ' . $commandClass);

src/Application/Bus/CommandQueuer.php

@@ -1,7 +1,7 @@
 <?php
 
 /*
- * Copyright 2025 Cloud Creativity Limited
+ * 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

src/Application/Bus/Exceptions/AbortOnFailureException.php

@@ -1,7 +1,7 @@
 <?php
 
 /*
- * Copyright 2025 Cloud Creativity Limited
+ * 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