Merge branch 'release/5.0.0-rc.2'

Author: lindyhopchris

CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project will be documented in this file. This projec
 
 ## Unreleased
 
+## [5.0.0-rc.2] - 2025-10-14
+
+### Added
+
+- Added a static `tryFrom()` method to the `IntegerId`, `StringId` and `Uuid` identifier classes. This method
+  returns `null` if the value provided cannot be cast to the identifier type.
+- The static `from()` method on all the identifier classes now accepts `null` but throws in this scenario. This allows
+  it to be used where the value you are casting is possibly null.
+- New methods on the `ListOfErrors` interface:
+    - `find()` to find the first matching error.
+    - `sole()` to get the first error, but only if exactly one error exists.
+    - `any()` to determine if any of the errors match.
+    - `every()` to determine if every error matches.
+    - `filter()` to get a new list containing only matching errors.
+- The `FailedResultException` now has a message when the result has an error code but no error message.
+- The `FakeExceptionReporter` now has `none()` and `expect()` helper methods, to prevent exceptions from being swallowed
+  in tests.
+- **BREAKING**: Changes to the result interface to support the following features. Although technically breaking, this
+  will not affect the majority of implementations are the concrete result class provided by this package has been
+  updated.
+    - Can now pass a default value to the `Result::error()` method. This default value can either be a string or a
+      closure that receives the error code. (Errors always have codes if they do not have messages.)
+    - Added `Result::code()` method to get the first error code in the result's errors.
+
+### Deprecated
+
+- The `ListOfErrors::contains()` method is deprecated and will be removed in 6.0. Use the new `any()` method instead.
+- Calling the `ListOfErrors::first()` method with arguments is deprecated and will be removed in 6.0. Use the new
+  `find()` method instead.
+
 ## [5.0.0-rc.1] - 2025-10-09
 
 ### Added
@@ -500,6 +530,8 @@ All notable changes to this project will be documented in this file. This projec
 
 Initial release.
 
+[5.0.0-rc.2]: https://github.com/cloudcreativity/ddd-modules/compare/v5.0.0-rc.1...v5.0.0-rc.2
+
 [5.0.0-rc.1]: https://github.com/cloudcreativity/ddd-modules/compare/v4.1.0...v5.0.0-rc.1
 
 [4.1.0]: https://github.com/cloudcreativity/ddd-modules/compare/v4.0.0...v4.1.0

deptrac.yaml

@@ -38,14 +38,18 @@ deptrac:
           value: ^Deprecated$
   ruleset:
     Toolkit:
+      - Attributes
     Domain:
       - Toolkit
+      - Attributes
     Application:
       - Toolkit
       - Domain
       - PSR Log
+      - Attributes
     Infrastructure:
       - Toolkit
       - Domain
       - Application
       - PSR Log
+      - Attributes

phpunit.xml

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

src/Contracts/Toolkit/Loggable/ContextFactory.php

@@ -21,7 +21,7 @@ interface ContextFactory
      * Make log context for the provided object.
      *
      * @param Message|Result<mixed> $object
-     * @return array<array-key, mixed>
+     * @return array<string, mixed>
      */
     public function make(Message|Result $object): array;
 }

src/Contracts/Toolkit/Result/ListOfErrors.php

@@ -24,17 +24,51 @@ interface ListOfErrors extends ListIterator
     /**
      * Get the first error in the list, or the first matching error.
      *
-     * @param Closure(Error): bool|UnitEnum|null $matcher
+     * @param (Closure(Error): bool)|UnitEnum|null $matcher
      */
     public function first(Closure|UnitEnum|null $matcher = null): ?Error;
 
+    /**
+     * Find the first matching error in the list.
+     *
+     * @param (Closure(Error): bool)|UnitEnum $matcher
+     */
+    public function find(Closure|UnitEnum $matcher): ?Error;
+
+    /**
+     * Get the first error in the list, but only if exactly one error exists. Otherwise, throw an exception.
+     *
+     * @param (Closure(Error): bool)|UnitEnum|null $matcher
+     */
+    public function sole(Closure|UnitEnum|null $matcher = null): Error;
+
     /**
      * Does the list contain a matching error?
      *
-     * @param Closure(Error): bool|UnitEnum $matcher
+     * @param (Closure(Error): bool)|UnitEnum $matcher
+     * @deprecated 6.0 use any() instead.
      */
     public function contains(Closure|UnitEnum $matcher): bool;
 
+    /**
+     * Does the list contain at least one matching error?
+     *
+     * @param (Closure(Error): bool)|UnitEnum $matcher
+     */
+    public function any(Closure|UnitEnum $matcher): bool;
+
+    /**
+     * Do all errors in the list match the provided matcher?
+     *
+     * @param (Closure(Error): bool)|UnitEnum $matcher
+     */
+    public function every(Closure|UnitEnum $matcher): bool;
+
+    /**
+     * @param (Closure(Error): bool)|UnitEnum $matcher
+     */
+    public function filter(Closure|UnitEnum $matcher): self;
+
     /**
      * Get all the unique error codes in the list.
      *

src/Contracts/Toolkit/Result/Result.php

@@ -12,17 +12,25 @@
 
 namespace CloudCreativity\Modules\Contracts\Toolkit\Result;
 
+use Closure;
 use CloudCreativity\Modules\Contracts\Toolkit\Result\ListOfErrors as IListOfErrors;
 use CloudCreativity\Modules\Toolkit\Result\FailedResultException;
 use CloudCreativity\Modules\Toolkit\Result\Meta;
+use UnitEnum;
 
 /**
  * @template-covariant TValue
  */
 interface Result
 {
+    /**
+     * Is the result a success?
+     */
     public function didSucceed(): bool;
 
+    /**
+     * Is the result a failure?
+     */
     public function didFail(): bool;
 
     /**
@@ -53,9 +61,17 @@ public function safe(): mixed;
     public function errors(): IListOfErrors;
 
     /**
-     * Get an error message string.
+     * Get the first error message, if there is one.
+     *
+     * @param (Closure(UnitEnum): non-empty-string)|non-empty-string|null $default the default value to use if there is no error message.
+     * @return ($default is Closure|string ? non-empty-string : null)
+     */
+    public function error(Closure|string|null $default = null): ?string;
+
+    /**
+     * Get the first error code, if there is one.
      */
-    public function error(): ?string;
+    public function code(): ?UnitEnum;
 
     /**
      * Get the result meta.

src/Testing/FakeDomainEventDispatcher.php

@@ -35,7 +35,7 @@ public function count(): int
     }
 
     /**
-     * Expect a single event to be dispatched and return it.
+     * Get the first event in the list, but only if exactly one event exists. Otherwise, throw an exception.
      */
     public function sole(): DomainEvent
     {

src/Testing/FakeExceptionReporter.php

@@ -24,11 +24,46 @@ final class FakeExceptionReporter implements ExceptionReporter, Countable
      */
     public array $reported = [];
 
+    private ?int $expected = null;
+
     public function report(Throwable $ex): void
     {
+        if ($this->expected === count($this->reported)) {
+            throw $ex;
+        }
+
         $this->reported[] = $ex;
     }
 
+    /**
+     * Expect no exceptions to be reported.
+     *
+     * Useful in tests where you do not expect any exceptions to be reported.
+     * This will cause the fake reporter to re-throw any exceptions rather
+     * than swallowing them.
+     */
+    public function none(): void
+    {
+        $this->expect(0);
+    }
+
+    /**
+     * Set the amount of exceptions expected.
+     *
+     * This will cause the fake reporter to re-throw any exceptions
+     * once the expected amount has been reported. This is primarily
+     * useful for debugging, because if your test causes too many
+     * exceptions, you will see the first unexpected exception.
+     *
+     * Note that this does not help if the reporter receives less
+     * exceptions than expected. You should use assertions
+     * in your test to verify the count of reported exceptions.
+     */
+    public function expect(int $count): void
+    {
+        $this->expected = $count;
+    }
+
     public function count(): int
     {
         return count($this->reported);

src/Toolkit/Contracts.php

@@ -19,7 +19,7 @@ final class Contracts
     /**
      * Assert that the provided precondition is true.
      *
-     * @param Closure(): string|string $message
+     * @param (Closure(): string)|string $message
      * @phpstan-assert true $precondition
      */
     public static function assert(bool $precondition, Closure|string $message = ''): void

src/Toolkit/Identifiers/Guid.php

@@ -25,7 +25,7 @@
 {
     use IsIdentifier;
 
-    public static function from(Identifier $value): self
+    public static function from(?Identifier $value): self
     {
         if ($value instanceof self) {
             return $value;
@@ -34,6 +34,15 @@ public static function from(Identifier $value): self
         throw new ContractException('Unexpected identifier type, received: ' . get_debug_type($value));
     }
 
+    public static function tryFrom(?Identifier $value): ?self
+    {
+        if ($value instanceof self) {
+            return $value;
+        }
+
+        return null;
+    }
+
     /**
      * Create a GUID with an integer id.
      */