Merge branch 'release/4.0.0'

Author: lindyhopchris

.github/workflows/tests.yml

@@ -14,7 +14,7 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        php: [ 8.1, 8.2, 8.3, 8.4 ]
+        php: [ 8.2, 8.3, 8.4 ]
 
     steps:
       - name: Checkout Code

CHANGELOG.md

@@ -5,6 +5,43 @@ All notable changes to this project will be documented in this file. This projec
 
 ## Unreleased
 
+## [4.0.0] - 2025-09-12
+
+### Added
+
+- **BREAKING**: Added `code()` method to the `ListOfErrors` interface. This returns the first error code in the list, or
+  `null` if there are no error codes.
+
+### Changed
+
+- **BREAKING**: The constructor argument order for the `Error` class has changed. The new order is `code`, `message`,
+  `key`. Previously it was `key`, `message`, `code` because code was added later. However, in most instances `code` is
+  the most important property as it is used to programmatically detect specific error scenarios. This hopefully will not
+  be breaking, as the docs specified that named arguments should be used when constructing error objects.
+- **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
+  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
+  use a string id.
+- **BREAKING**: Updated the `GuidTypeMap` class so that it now supports enum aliases, enum types, and UUID identifiers.
+  This means the `type()` method now returns a string or enum, whereas previously it returned just a string.
+- Object log context now casts Ramsey UUIDs and enums to strings.
+
+### Removed
+
+- Package no longer supports PHP 8.1. The minimum supported version is now PHP 8.2.
+- **BREAKING**: Removed the `Guid::type()` method - use `enum_value($guid->type)` or `enum_string($guid->type)` instead.
+- Removed the following classes that were deprecated in 3.4:
+    - `LazyListOfGuids`
+    - `LazyListOfIdentifiers`
+    - `LazyListOfIntegerIds`
+    - `LazyListOfStringIds`
+    - `LazyListOfUuids`
+    - `ListOfIdentifiers`
+
 ## [3.4.0] - 2025-09-09
 
 ### Deprecated
@@ -445,6 +482,12 @@ All notable changes to this project will be documented in this file. This projec
 
 Initial release.
 
+[4.0.0]: https://github.com/cloudcreativity/ddd-modules/compare/v3.4.0...v4.0.0
+
+[3.4.0]: https://github.com/cloudcreativity/ddd-modules/compare/v3.3.1...v3.4.0
+
+[3.3.1]: https://github.com/cloudcreativity/ddd-modules/compare/v3.3.0...v3.3.1
+
 [3.3.0]: https://github.com/cloudcreativity/ddd-modules/compare/v3.2.0...v3.3.0
 
 [3.2.0]: https://github.com/cloudcreativity/ddd-modules/compare/v3.1.0...v3.2.0

composer.json

@@ -21,17 +21,17 @@
         }
     ],
     "require": {
-        "php": "^8.1",
+        "php": "^8.2",
         "ext-json": "*",
-        "psr/log": "^1.0.1 || ^2.0 || ^3.0",
+        "psr/log": "^2.0 || ^3.0",
         "ramsey/uuid": "^4.7",
         "symfony/polyfill-php84": "^1.33"
     },
     "require-dev": {
-        "deptrac/deptrac": "^3.0",
+        "deptrac/deptrac": "^4.2",
         "laravel/pint": "^1.19",
         "phpstan/phpstan": "^2.1",
-        "phpunit/phpunit": "^10.5"
+        "phpunit/phpunit": "^11.5"
     },
     "autoload": {
         "files": [
@@ -61,8 +61,8 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-develop": "3.x-dev",
-            "dev-next": "4.x-dev"
+            "dev-develop": "4.x-dev",
+            "dev-next": "5.x-dev"
         }
     },
     "minimum-stability": "stable",

deptrac.yaml

@@ -38,7 +38,6 @@ deptrac:
           value: ^Deprecated$
   ruleset:
     Toolkit:
-      - Attributes
     Domain:
       - Toolkit
     Application:

docs/guide/toolkit/results.md

@@ -125,12 +125,12 @@ Alternatively, you can provide the `failed()` method with an error object or a l
 
 The error object provided by this package has the following properties:
 
+- `code`: an enum that identifies the error and can be used to programmatically detect and handle specific errors. It
+  is intentionally an enum, because to programmatically detect specific errors, the codes need to be a defined list of
+  values.
 - `message`: a string message that describes the error.
-- `code`: a backed enum that identifies error and can be used to programmatically detect and handle specific errors. It
-  is intentionally an enum, because if you need to detect specific errors, the codes need to be a defined list of
-  values - which is an enum.
-- `key`: optionally, a key for the error. This can be used to group errors by keys, for example to group errors by
-   properties that exist on a command message.
+- `key`: optionally, a key for the error. Use this to group errors by keys, for example to group errors by
+  properties that exist on a command message. The key can be a string or enum.
 
 Error objects _must_ be instantiated with either a code or a message. They are immutable, so you cannot change their
 properties after they have been created.
@@ -181,7 +181,7 @@ The error list class is iterable, countable and has `isEmpty()` and `isNotEmpty(
 ### Keyed Error Sets
 
 If you are using the `key` property on error objects, we provide a keyed set of errors class that groups errors by their
-key.
+key. Keys can be strings or enums.
 
 To create one, provide error objects to its constructor:
 
@@ -243,6 +243,16 @@ if ($errors->contains(CancelAttendeeTicketError::AlreadyCancelled)) {
 }
 ```
 
+If you only want to handle one error code at once, use the `code()` method on the errors list. This will return the first error code, or `null` if there are no error codes.
+
+```php
+$explanation = match ($errors->code()) {
+    CancelAttendeeTicketError::AlreadyCancelled => 'The ticket has already been cancelled.',
+    CancelAttendeeTicketError::NotFound => 'The ticket was not found.',
+    default => null,
+};
+```
+
 ## Exception
 
 We provide a `FailedResultException` that you can use to throw a result object:

phpstan.neon

@@ -3,6 +3,4 @@ parameters:
     paths:
         - src
         - tests
-    excludePaths:
-        - tests/Unit/Domain/TestReadOnlyEntity.php
     treatPhpDocTypesAsCertain: false

phpunit.xml

@@ -11,7 +11,7 @@
          cacheDirectory=".phpunit.cache"
          backupStaticProperties="false"
          failOnWarning="true"
-         failOnDeprecation="false"
+         failOnDeprecation="true"
          failOnNotice="true"
 >
     <coverage/>

pint.json

@@ -1,13 +1,37 @@
 {
     "preset": "psr12",
     "rules": {
+        "array_syntax": true,
+        "assign_null_coalescing_to_coalesce_equal": true,
+        "clean_namespace": true,
         "declare_strict_types": true,
+        "list_syntax": true,
+        "no_empty_phpdoc": true,
+        "no_superfluous_elseif": true,
+        "no_superfluous_phpdoc_tags": {
+            "remove_inheritdoc": true
+        },
+        "no_unneeded_braces": true,
+        "no_useless_nullsafe_operator": true,
+        "no_whitespace_before_comma_in_array": true,
+        "normalize_index_brace": true,
+        "nullable_type_declaration": true,
+        "nullable_type_declaration_for_default_null_value": true,
+        "ordered_attributes": true,
+        "ordered_traits": true,
+        "ordered_types": {
+            "null_adjustment": "always_last"
+        },
+        "phpdoc_summary": true,
+        "phpdoc_trim": true,
+        "phpdoc_types": true,
+        "phpdoc_types_order": {
+            "null_adjustment": "always_last"
+        },
+        "simple_to_complex_string_variable": true,
+        "ternary_to_null_coalescing": true,
         "trailing_comma_in_multiline": {
             "elements": ["arguments", "arrays", "match", "parameters"]
-        },
-        "nullable_type_declaration": true
-    },
-    "notPath": [
-        "tests/Unit/Domain/TestReadOnlyEntity.php"
-    ]
-}
+        }
+    }
+}

src/Application/Bus/CommandDispatcher.php

@@ -23,16 +23,10 @@
 class CommandDispatcher implements ICommandDispatcher
 {
     /**
-     * @var array<string|callable>
+     * @var array<callable|string>
      */
     private array $pipes = [];
 
-    /**
-     * CommandDispatcher constructor.
-     *
-     * @param CommandHandlerContainer $handlers
-     * @param PipeContainer|null $middleware
-     */
     public function __construct(
         private readonly CommandHandlerContainer $handlers,
         private readonly ?PipeContainer $middleware = null,
@@ -42,8 +36,7 @@ public function __construct(
     /**
      * Dispatch messages through the provided pipes.
      *
-     * @param array<string|callable> $pipes
-     * @return void
+     * @param array<callable|string> $pipes
      */
     public function through(array $pipes): void
     {
@@ -52,9 +45,6 @@ public function through(array $pipes): void
         $this->pipes = $pipes;
     }
 
-    /**
-     * @inheritDoc
-     */
     public function dispatch(Command $command): Result
     {
         $pipeline = PipelineBuilder::make($this->middleware)
@@ -71,7 +61,6 @@ public function dispatch(Command $command): Result
     }
 
     /**
-     * @param Command $command
      * @return Result<mixed>
      */
     private function execute(Command $command): Result

src/Application/Bus/CommandHandler.php

@@ -17,20 +17,12 @@
 use CloudCreativity\Modules\Contracts\Toolkit\Messages\Command;
 use CloudCreativity\Modules\Contracts\Toolkit\Result\Result;
 
-final class CommandHandler implements ICommandHandler
+final readonly class CommandHandler implements ICommandHandler
 {
-    /**
-     * CommandHandler constructor.
-     *
-     * @param object $handler
-     */
-    public function __construct(private readonly object $handler)
+    public function __construct(private object $handler)
     {
     }
 
-    /**
-     * @inheritDoc
-     */
     public function __invoke(Command $command): Result
     {
         assert(method_exists($this->handler, 'execute'), sprintf(
@@ -46,9 +38,6 @@ public function __invoke(Command $command): Result
         return $result;
     }
 
-    /**
-     * @inheritDoc
-     */
     public function middleware(): array
     {
         if ($this->handler instanceof DispatchThroughMiddleware) {