Merge branch 'release/2.0.0-rc.1'

.github/workflows/tests.yml

@@ -2,9 +2,9 @@ name: Tests
 
 on:
   push:
-    branches: [ main, develop ]
+    branches: [ main, develop, next ]
   pull_request:
-    branches: [ main, develop ]
+    branches: [ main, develop, next ]
 
 jobs:
   build:

CHANGELOG.md

@@ -5,6 +5,75 @@ All notable changes to this project will be documented in this file. This projec
 
 ## Unreleased
 
+### [2.0.0-rc.1] - 2024-05-07
+
+**Refer to the [Upgrade Guide.](./docs/guide/upgrade.md)**
+
+### Added
+
+- **BREAKING** The command bus interface now has a `queue()` method. Our command dispatcher implementation has been
+  updated to accept a queue factory closure as its third constructor argument. This is an optional argument, so this
+  change only breaks your implementation if you have manually implemented the command dispatch interface.
+- The `FailedResultException` now implements `ContextProvider` to get log context from the exception's
+  result object. In Laravel applications, this means the exception context will automatically be logged.
+- The `Result` interface has a new `abort()` method. This throws a `FailedResultException` if the result is not
+  successful.
+- The inbound integration event handler container now accepts an optional factory for a default handler. This can be
+  used to swallow inbound events that the bounded context does not need to consume. We have also added
+  a `SwallowInboundEvent` handler that can be used in this scenario.
+
+### Changed
+
+- **BREAKING** Package now uses a _hexagonal architecture_ approach, which helps clarify the relationship between the
+  application and infrastructure layers. This means a number of interfaces have been moved to
+  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** 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.
+- **BREAKING** The event bus implementation has been split into an inbound event bus (in the application layer) and an
+  outbound event bus (in the infrastructure layer). With the new hexagonal architecture, this changes was required
+  because inbound events are received via a driving port, while outbound events are published via a driven port.
+- **BREAKING** Refactored the queue implementation so that commands are queued. The queue implementation was previously
+  not documented. There is now complete documentation in
+  the [Asynchronous Processing chapter](docs/guide/application/asynchronous-processing.md) Refer to that documentation
+  to upgrade your implementation.
+- **BREAKING** For clarity, the following classes have had their `pipeline` constructor argument renamed
+  to `middleware`. You will need to update the construction of these classes if you are using named arguments:
+    - `Application\Bus\CommandDispatcher`
+    - `Application\Bus\QueryDispatcher`
+    - `Application\InboundEventBus\EventDispatcher`
+    - `Application\DomainEventDispatching\Dispatcher`
+    - `Application\DomainEventDispatching\DeferredDispatcher`
+    - `Application\DomainEventDispatching\UnitOfWorkAwareDispatcher`
+- **BREAKING** The command and query validators have been merged into a single class - `Application\Bus\Validator`. This
+  is because there was no functional difference between the two, so this tidies up the implementation.
+- **BREAKING** Renamed the bus `MessageMiddleware` interface to `BusMiddleware` interface. Also changed the type-hint
+  for the message from `Message` to `Command|Query`. This makes this interface clearer about its purpose, as it is
+  intended only for use with commands and queries - i.e. not integration event messages.
+- **BREAKING** the `ResultContext` and `ObjectContext` helper classes have been moved to the `Toolkit\Loggable`
+  namespace.
+- **BREAKING** The `Result::value()` method now throws a `FailedResultException` if the result is not successful.
+  Previously it threw a `ContractException`.
+- **BREAKING** The unit of work implementation has been moved to the `Application\UnitOfWork` namespace. Previously it
+  was in `Infrastructure\Persistence`. This reflects the fact that the unit of work manager is an application concern.
+  The unit of work interface is now a driven port.
+
+### Removed
+
+- **BREAKING** The pipeline builder factory was no longer required, so the following classes/interfaces have been
+  deleted. Although breaking, this is unlikely to affect your implementation as these classes were only used internal
+  within our bus and dispatch implementations.
+    - `Toolkit\Pipeline\PipelineBuilderFactoryInterface`
+    - `Toolkit\Pipeline\PipelineBuilderFactory`
+- **BREAKING** Removed the following previously deprecated event bus middleware:
+    - `LogOutboundIntegrationEvent` - use `Infrastructure\OutboundEventBus\Middleware\LogOutboundEvent` instead.
+    - `LogInboundIntegrationEvent` - use `Application\InboundEventBus\Middleware\LogInboundEvent` instead.
+- **BREAKING** Removed the `Infrastructure::assert()` helper. This was not documented so is unlikely to be breaking.
+
 ## [1.2.0] - 2024-04-05
 
 ### Added

composer.json

@@ -56,7 +56,8 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-develop": "1.x-dev"
+            "dev-develop": "2.x-dev",
+            "dev-next": "3.x-dev"
         }
     },
     "minimum-stability": "stable",

deptrac.yaml

@@ -4,34 +4,44 @@ deptrac:
   layers:
     - name: Toolkit
       collectors:
+        - type: className
+          value: CloudCreativity\\Modules\\Contracts\\Toolkit\\*
         - type: className
           value: CloudCreativity\\Modules\\Toolkit\\*
         - type: className
           value: Ramsey\\Uuid\\*
     - name: Domain
       collectors:
+        - type: className
+          value: CloudCreativity\\Modules\\Contracts\\Domain\\*
         - type: className
           value: CloudCreativity\\Modules\\Domain\\*
-    - name: Infrastructure
+    - name: Application
       collectors:
         - type: className
-          value: CloudCreativity\\Modules\\Infrastructure\\*
+          value: CloudCreativity\\Modules\\Contracts\\Application\\*
         - type: className
-          value: Psr\\Log\\*
-    - name: Application
+          value: CloudCreativity\\Modules\\Application\\*
+    - name: Infrastructure
       collectors:
         - type: className
-          value: CloudCreativity\\Modules\\Bus\\*
+          value: CloudCreativity\\Modules\\Contracts\\Infrastructure\\*
         - type: className
-          value: CloudCreativity\\Modules\\EventBus\\*
+          value: CloudCreativity\\Modules\\Infrastructure\\*
+    - name: PSR Log
+      collectors:
+        - type: className
+          value: Psr\\Log\\*
   ruleset:
     Toolkit:
     Domain:
       - Toolkit
-    Infrastructure:
+    Application:
       - Toolkit
       - Domain
-    Application:
+      - PSR Log
+    Infrastructure:
       - Toolkit
       - Domain
-      - Infrastructure
+      - Application
+      - PSR Log

docs/.vitepress/config.mts

@@ -22,6 +22,7 @@ export default defineConfig({
                     items: [
                         {text: 'What is DDD Modules?', link: '/guide/'},
                         {text: 'Installation', link: '/guide/installation'},
+                        {text: 'Upgrading', link: '/guide/upgrade'},
                     ],
                 },
                 {
@@ -32,7 +33,7 @@ export default defineConfig({
                         {text: 'Bounded Contexts', link: '/guide/concepts/bounded-contexts'},
                         {text: 'Layers', link: '/guide/concepts/layers'},
                         {text: 'Encapsulation', link: '/guide/concepts/encapsulation'},
-                        {text: 'Modularisation', link: '/guide/concepts/modularisation'},
+                        {text: 'Modularisation & Structure', link: '/guide/concepts/modularisation'},
                     ],
                 },
                 {
@@ -41,27 +42,32 @@ export default defineConfig({
                     items: [
                         {text: 'Entities & Aggregates', link: '/guide/domain/entities'},
                         {text: 'Value Objects', link: '/guide/domain/value-objects'},
-                        {text: 'Domain Events', link: '/guide/domain/events'},
+                        {text: 'Events', link: '/guide/domain/events'},
                         {text: 'Services', link: '/guide/domain/services'},
                     ],
                 },
-                {
-                    text: 'Infrastructure Layer',
-                    collapsed: true,
-                    items: [
-                        {text: 'Asynchronous Processing', link: '/guide/infrastructure/queues'},
-                        {text: 'Outbox & Inbox', link: '/guide/infrastructure/outbox-inbox'},
-                        {text: 'Persistence', link: '/guide/infrastructure/persistence'},
-                        {text: 'Units of Work', link: '/guide/infrastructure/units-of-work'},
-                    ],
-                },
                 {
                     text: 'Application Layer',
                     collapsed: false,
                     items: [
                         {text: 'Commands', link: '/guide/application/commands'},
                         {text: 'Queries', link: '/guide/application/queries'},
                         {text: 'Integration Events', link: '/guide/application/events'},
+                        {text: 'Domain Events', link: '/guide/application/domain-events'},
+                        {text: 'Units of Work', link: '/guide/application/units-of-work'},
+                        {text: 'Asynchronous Processing', link: '/guide/application/asynchronous-processing'},
+                    ],
+                },
+                {
+                    text: 'Infrastructure Layer',
+                    collapsed: false,
+                    items: [
+                        {text: 'Dependency Injection', link: '/guide/infrastructure/dependency-injection'},
+                        {text: 'Exception Reporting', link: '/guide/infrastructure/exception-reporting'},
+                        {text: 'Persistence', link: '/guide/infrastructure/persistence'},
+                        {text: 'Publishing Events', link: '/guide/infrastructure/publishing-events'},
+                        {text: 'Transactional Outbox', link: '/guide/infrastructure/outbox'},
+                        {text: 'Queues', link: '/guide/infrastructure/queues'},
                     ],
                 },
                 {