Merge branch 'release/0.6.0'

CHANGELOG.md

@@ -3,6 +3,35 @@
 All notable changes to this project will be documented in this file. This project adheres to
 [Semantic Versioning](http://semver.org/) and [this changelog format](http://keepachangelog.com/).
 
+## Unreleased
+
+## [0.6.0] - 2024-02-07
+
+### Added
+
+- New `DeferredDispatcher` class for dispatching domain events when not using a unit of work.
+- New UUID factory interface and class, that wraps the `ramsey/uuid` factory to return UUID identifiers.
+- GUIDs that wrap UUIDs can now be created via the static `Guid::fromUuid()` method.
+- New `SetupBeforeDispatch` and `TearDownAfterDispatch` bus middleware, that can be used either to setup (and optionally
+  tear down) application state around the dispatching of a message, or to just do tear down work.
+- The `EventBus` namespace now has a working implementation for publishing integration events.
+- Can now provide a closure to the `ListOfErrorsInterface::first()` method to find the first matching error.
+- Added the following methods to the `ListOfErrorsInterface`:
+    - `contains()` - determines whether the list contains a matching error.
+    - `codes()` - returns an array containing the unique error codes in the list.
+- Added an `ErrorInterface::is()` method to determine whether an error matches a given code.
+
+### Changed
+
+- **BREAKING** - renamed the domain event `Dispatcher` class to `UnitOfWorkAwareDispatcher`.
+- **BREAKING** - removed the `IntegrationEvents` namespace and moved to the `Infrastructure\EventBus` namespace.
+- **BREAKING** - the `IntegrationEventInterface` now expects the UUID to be an identifier UUID, not a Ramsey UUID.
+- The UUID factory from the `ramsey/uuid` package is now used when creating new UUID identifiers.
+
+### Fixed
+
+- The unit of work manager now correctly handles re-attempts so that deferred events are not dispatched multiple times.
+
 ## [0.5.0] - 2023-12-02
 
 ### Added

README.md

@@ -1,2 +1,23 @@
 # Domain Driven Design Modules
 
+**Write highly encapsulated and loosely coupled modules, for domain-centric architecture.**
+
+## Documentation
+
+This package provides a common PHP toolset for writing these modules.
+
+**It can be tempting to dive straight into the code - you'll need to resist that temptation!**
+
+The key to achieving highly encapsulated and loosely coupled modules is _how you use the tools in this package_. That is
+described in the [documentation](https://github.com/cloudcreativity/ddd-modules/wiki) - so ensure you read the docs
+before using these tools.
+
+## Installation
+
+```bash
+composer require cloudcreativity/ddd-modules
+```
+
+## License
+
+DDD Modules is open-sourced software licensed under the [Apache 2.0 License](./LICENSE).

composer.json

@@ -23,7 +23,7 @@
     "require": {
         "php": "^8.1",
         "ext-json": "*",
-        "psr/log": "^3.0",
+        "psr/log": "^1.0.1 || ^2.0 || ^3.0",
         "ramsey/uuid": "^4.7"
     },
     "require-dev": {

src/Bus/CommandDispatcher.php

@@ -1,6 +1,6 @@
 <?php
 /*
- * Copyright 2023 Cloud Creativity Limited
+ * Copyright 2024 Cloud Creativity Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/Bus/CommandDispatcherInterface.php

@@ -1,6 +1,6 @@
 <?php
 /*
- * Copyright 2023 Cloud Creativity Limited
+ * Copyright 2024 Cloud Creativity Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/Bus/CommandHandler.php

@@ -1,6 +1,6 @@
 <?php
 /*
- * Copyright 2023 Cloud Creativity Limited
+ * Copyright 2024 Cloud Creativity Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/Bus/CommandHandlerContainer.php

@@ -1,6 +1,6 @@
 <?php
 /*
- * Copyright 2023 Cloud Creativity Limited
+ * Copyright 2024 Cloud Creativity Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/Bus/CommandHandlerContainerInterface.php

@@ -1,6 +1,6 @@
 <?php
 /*
- * Copyright 2023 Cloud Creativity Limited
+ * Copyright 2024 Cloud Creativity Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/Bus/CommandHandlerInterface.php

@@ -1,6 +1,6 @@
 <?php
 /*
- * Copyright 2023 Cloud Creativity Limited
+ * Copyright 2024 Cloud Creativity Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/Bus/CommandInterface.php

@@ -1,6 +1,6 @@
 <?php
 /*
- * Copyright 2023 Cloud Creativity Limited
+ * Copyright 2024 Cloud Creativity Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/Bus/DispatchThroughMiddleware.php

@@ -1,6 +1,6 @@
 <?php
 /*
- * Copyright 2023 Cloud Creativity Limited
+ * Copyright 2024 Cloud Creativity Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -24,7 +24,7 @@ interface DispatchThroughMiddleware
     /**
      * Get the middleware for the command or query.
      *
-     * @return array<int,callable|string>
+     * @return array<callable|string>
      */
     public function middleware(): array;
 }

src/Bus/MessageInterface.php

@@ -1,6 +1,6 @@
 <?php
 /*
- * Copyright 2023 Cloud Creativity Limited
+ * Copyright 2024 Cloud Creativity Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/Bus/Middleware/CommandMiddlewareInterface.php

@@ -1,6 +1,6 @@
 <?php
 /*
- * Copyright 2023 Cloud Creativity Limited
+ * Copyright 2024 Cloud Creativity Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -29,7 +29,7 @@ interface CommandMiddlewareInterface
      * Handle the command.
      *
      * @param CommandInterface $command
-     * @param Closure $next
+     * @param Closure(CommandInterface): ResultInterface<mixed> $next
      * @return ResultInterface<mixed>
      */
     public function __invoke(CommandInterface $command, Closure $next): ResultInterface;

src/Bus/Middleware/ExecuteInUnitOfWork.php

@@ -1,6 +1,6 @@
 <?php
 /*
- * Copyright 2023 Cloud Creativity Limited
+ * Copyright 2024 Cloud Creativity Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/Bus/Middleware/FlushDeferredEvents.php

@@ -0,0 +1,59 @@
+<?php
+/*
+ * Copyright 2024 Cloud Creativity Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+namespace CloudCreativity\Modules\Bus\Middleware;
+
+use Closure;
+use CloudCreativity\Modules\Bus\MessageInterface;
+use CloudCreativity\Modules\Infrastructure\DomainEventDispatching\DeferredDispatcherInterface;
+use CloudCreativity\Modules\Toolkit\Result\ResultInterface;
+use Throwable;
+
+final class FlushDeferredEvents implements MessageMiddlewareInterface
+{
+    /**
+     * FlushDeferredEvents constructor.
+     *
+     * @param DeferredDispatcherInterface $dispatcher
+     */
+    public function __construct(private readonly DeferredDispatcherInterface $dispatcher)
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function __invoke(MessageInterface $message, Closure $next): ResultInterface
+    {
+        try {
+            $result = $next($message);
+        } catch (Throwable $ex) {
+            $this->dispatcher->forget();
+            throw $ex;
+        }
+
+        if ($result->didSucceed()) {
+            $this->dispatcher->flush();
+        } else {
+            $this->dispatcher->forget();
+        }
+
+        return $result;
+    }
+}

src/Bus/Middleware/LogMessageDispatch.php

@@ -1,6 +1,6 @@
 <?php
 /*
- * Copyright 2023 Cloud Creativity Limited
+ * Copyright 2024 Cloud Creativity Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/Bus/Middleware/MessageMiddlewareInterface.php

@@ -1,6 +1,6 @@
 <?php
 /*
- * Copyright 2023 Cloud Creativity Limited
+ * Copyright 2024 Cloud Creativity Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -29,7 +29,7 @@ interface MessageMiddlewareInterface
      * Handle the message.
      *
      * @param MessageInterface $message
-     * @param Closure $next
+     * @param Closure(MessageInterface): ResultInterface<mixed> $next
      * @return ResultInterface<mixed>
      */
     public function __invoke(MessageInterface $message, Closure $next): ResultInterface;

src/Bus/Middleware/QueryMiddlewareInterface.php

@@ -1,6 +1,6 @@
 <?php
 /*
- * Copyright 2023 Cloud Creativity Limited
+ * Copyright 2024 Cloud Creativity Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -29,7 +29,7 @@ interface QueryMiddlewareInterface
      * Handle the query.
      *
      * @param QueryInterface $query
-     * @param Closure $next
+     * @param Closure(QueryInterface): ResultInterface<mixed> $next
      * @return ResultInterface<mixed>
      */
     public function __invoke(QueryInterface $query, Closure $next): ResultInterface;

src/Bus/Middleware/SetupBeforeDispatch.php

@@ -0,0 +1,57 @@
+<?php
+/*
+ * Copyright 2024 Cloud Creativity Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+namespace CloudCreativity\Modules\Bus\Middleware;
+
+use Closure;
+use CloudCreativity\Modules\Bus\MessageInterface;
+use CloudCreativity\Modules\Toolkit\Result\ResultInterface;
+
+final class SetupBeforeDispatch implements MessageMiddlewareInterface
+{
+    /**
+     * SetupBeforeDispatch constructor.
+     *
+     * @param Closure(): ?Closure(): void $callback
+     */
+    public function __construct(private readonly Closure $callback)
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function __invoke(MessageInterface $message, Closure $next): ResultInterface
+    {
+        $tearDown = ($this->callback)();
+
+        assert(
+            $tearDown === null || $tearDown instanceof Closure,
+            'Expecting setup function to return null or a teardown closure.',
+        );
+
+        try {
+            return $next($message);
+        } finally {
+            if ($tearDown) {
+                $tearDown();
+            }
+        }
+    }
+}

src/Bus/Middleware/TearDownAfterDispatch.php

@@ -0,0 +1,48 @@
+<?php
+/*
+ * Copyright 2024 Cloud Creativity Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+namespace CloudCreativity\Modules\Bus\Middleware;
+
+use Closure;
+use CloudCreativity\Modules\Bus\MessageInterface;
+use CloudCreativity\Modules\Toolkit\Result\ResultInterface;
+
+final class TearDownAfterDispatch implements MessageMiddlewareInterface
+{
+    /**
+     * TearDownAfterDispatch constructor.
+     *
+     * @param Closure(): void $callback
+     */
+    public function __construct(private readonly Closure $callback)
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function __invoke(MessageInterface $message, Closure $next): ResultInterface
+    {
+        try {
+            return $next($message);
+        } finally {
+            ($this->callback)();
+        }
+    }
+}

src/Bus/Middleware/ValidateCommand.php

@@ -1,6 +1,6 @@
 <?php
 /*
- * Copyright 2023 Cloud Creativity Limited
+ * Copyright 2024 Cloud Creativity Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/Bus/Middleware/ValidateQuery.php

@@ -1,6 +1,6 @@
 <?php
 /*
- * Copyright 2023 Cloud Creativity Limited
+ * Copyright 2024 Cloud Creativity Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.