Merge branch 'release/3.2.0'

Author: lindyhopchris

CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file. This projec
 
 ## Unreleased
 
+## [3.2.0] - 2024-04-19
+
+### Added
+
+- New `ApplicationException` for errors originating from the application layer.
+- Can now pass a closure to the `Contracts::assert()` method for the message. The closure is only invoked if the
+  precondition fails.
+
+### Fixed
+
+- Make the `id` property on the `IsEntity` trait readonly. This is considered non-breaking because the `IsEntity` trait
+  is expected to be used on an entity that always has an identifier, so the id should be set via the constructor. This
+  fixes a bug where the trait could not be used on a readonly class.
+
 ## [3.1.0] - 2025-02-15
 
 ### Added
@@ -402,6 +416,8 @@ All notable changes to this project will be documented in this file. This projec
 
 Initial release.
 
+[3.2.0]: https://github.com/cloudcreativity/ddd-modules/compare/v3.1.0...v3.2.0
+
 [3.1.0]: https://github.com/cloudcreativity/ddd-modules/compare/v3.0.0...v3.1.0
 
 [3.0.0]: https://github.com/cloudcreativity/ddd-modules/compare/v3.0.0-rc.2...v3.0.0

composer.json

@@ -27,10 +27,10 @@
         "ramsey/uuid": "^4.7"
     },
     "require-dev": {
+        "deptrac/deptrac": "^3.0",
         "laravel/pint": "^1.19",
         "phpstan/phpstan": "^2.1",
-        "phpunit/phpunit": "^10.5",
-        "qossmic/deptrac": "^2.0"
+        "phpunit/phpunit": "^10.5"
     },
     "autoload": {
         "psr-4": {

phpstan.neon

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

pint.json

@@ -6,5 +6,8 @@
             "elements": ["arguments", "arrays", "match", "parameters"]
         },
         "nullable_type_declaration": true
-    }
-}
+    },
+    "notPath": [
+        "tests/Unit/Domain/TestReadOnlyEntity.php"
+    ]
+}

src/Application/ApplicationException.php

@@ -0,0 +1,19 @@
+<?php
+
+/*
+ * Copyright 2025 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
+ * https://opensource.org/licenses/MIT.
+ */
+
+declare(strict_types=1);
+
+namespace CloudCreativity\Modules\Application;
+
+use RuntimeException;
+
+class ApplicationException extends RuntimeException
+{
+}

src/Domain/IsEntity.php

@@ -20,7 +20,7 @@ trait IsEntity
     /**
      * @var Identifier
      */
-    private Identifier $id;
+    private readonly Identifier $id;
 
     /**
      * @inheritDoc

src/Toolkit/Contracts.php

@@ -12,20 +12,22 @@
 
 namespace CloudCreativity\Modules\Toolkit;
 
+use Closure;
+
 final class Contracts
 {
     /**
      * Assert that the provided precondition is true.
      *
      * @param bool $precondition
-     * @param string $message
+     * @param string|Closure(): string $message
      * @return void
      * @phpstan-assert true $precondition
      */
-    public static function assert(bool $precondition, string $message = ''): void
+    public static function assert(bool $precondition, string|Closure $message = ''): void
     {
         if ($precondition === false) {
-            throw new ContractException($message);
+            throw new ContractException(is_string($message) ? $message : $message());
         }
     }
 

tests/Unit/Application/ApplicationExceptionTest.php

@@ -0,0 +1,26 @@
+<?php
+
+/*
+ * Copyright 2025 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
+ * https://opensource.org/licenses/MIT.
+ */
+
+declare(strict_types=1);
+
+namespace CloudCreativity\Modules\Tests\Unit\Application;
+
+use CloudCreativity\Modules\Application\ApplicationException;
+use PHPUnit\Framework\TestCase;
+use RuntimeException;
+
+class ApplicationExceptionTest extends TestCase
+{
+    public function test(): void
+    {
+        $ex = new ApplicationException();
+        $this->assertInstanceOf(RuntimeException::class, $ex);
+    }
+}

tests/Unit/Domain/EntityTest.php

@@ -15,6 +15,7 @@
 use CloudCreativity\Modules\Contracts\Domain\Entity;
 use CloudCreativity\Modules\Contracts\Toolkit\Identifiers\Identifier;
 use CloudCreativity\Modules\Toolkit\Identifiers\Guid;
+use CloudCreativity\Modules\Toolkit\Identifiers\IntegerId;
 use PHPUnit\Framework\TestCase;
 
 class EntityTest extends TestCase
@@ -97,4 +98,17 @@ public function testItIsDifferentClass(): void
         $this->assertFalse($a->is($b));
         $this->assertTrue($a->isNot($b));
     }
+
+    public function testItCanUseTraitOnReadonlyClass(): void
+    {
+        if (PHP_VERSION_ID < 80200) {
+            $this->markTestSkipped('This test requires PHP 8.2 or higher.');
+        }
+
+        $id = new IntegerId(123);
+        $entity = new TestReadOnlyEntity($id, 'Bob');
+
+        $this->assertSame($id, $entity->getId());
+        $this->assertSame('Bob', $entity->getName());
+    }
 }

tests/Unit/Domain/TestReadOnlyEntity.php

@@ -0,0 +1,44 @@
+<?php
+
+/*
+ * Copyright 2025 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
+ * https://opensource.org/licenses/MIT.
+ */
+
+declare(strict_types=1);
+
+namespace CloudCreativity\Modules\Tests\Unit\Domain;
+
+use CloudCreativity\Modules\Contracts\Domain\Entity;
+use CloudCreativity\Modules\Contracts\Toolkit\Identifiers\Identifier;
+use CloudCreativity\Modules\Domain\IsEntity;
+
+/**
+ * @TODO remove when dropping PHP 8.1 and update `TestEntity` to be `readonly`.
+ */
+final readonly class TestReadOnlyEntity implements Entity
+{
+    use IsEntity;
+
+    /**
+     * TestReadOnlyEntity constructor
+     *
+     * @param Identifier $id
+     * @param string $name
+     */
+    public function __construct(Identifier $id, private string $name)
+    {
+        $this->id = $id;
+    }
+
+    /**
+     * @return string
+     */
+    public function getName(): string
+    {
+        return $this->name;
+    }
+}