Rename guard parameter (#66)

* Rename guard parameter * Update docs --------- Co-authored-by: Christian Kolb <[email protected]>
digital-craftsman-de · Jun 11, 2024 · 3d6f05d · 3d6f05d
1 parent e3f5230
commit 3d6f05d
Show file tree

Hide file tree

Showing 6 changed files with 66 additions and 58 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.2.0
+
+- Renamed parameter `$exception` to `$otherwiseThrow` in the guard methods of `Id` and `IdList` to make it more clear what the parameter does when using named parameters.
+
 ## 1.1.0
 
 - Added option to supply a custom exception to the guard methods of `Id` and `IdList`. This allows for more specific exceptions when the guard fails.

diff --git a/UPGRADE.md b/UPGRADE.md
@@ -1,5 +1,9 @@
 # Upgrade guide
 
+## From 1.1.0 to 1.2.0
+
+Nothing to do.
+
 ## From 1.0.0 to 1.1.0
 
 Nothing to do.

diff --git a/src/ValueObject/Id.php b/src/ValueObject/Id.php
@@ -48,35 +48,35 @@ public function isNotEqualTo(self $id): bool
     // Guards
 
     /**
-     * @param ?callable(): \Throwable $exception
+     * @param ?callable(): \Throwable $otherwiseThrow
      *
      * @throws \Throwable
      * @throws Exception\IdNotEqual
      */
     public function mustBeEqualTo(
         self $id,
-        ?callable $exception = null,
+        ?callable $otherwiseThrow = null,
     ): void {
         if ($this->isNotEqualTo($id)) {
-            throw $exception !== null
-                ? $exception()
+            throw $otherwiseThrow !== null
+                ? $otherwiseThrow()
                 : new Exception\IdNotEqual($this, $id);
         }
     }
 
     /**
-     * @param ?callable(): \Throwable $exception
+     * @param ?callable(): \Throwable $otherwiseThrow
      *
      * @throws \Throwable
      * @throws Exception\IdEqual
      */
     public function mustNotBeEqualTo(
         self $id,
-        ?callable $exception = null,
+        ?callable $otherwiseThrow = null,
     ): void {
         if ($this->isEqualTo($id)) {
-            throw $exception !== null
-                ? $exception()
+            throw $otherwiseThrow !== null
+                ? $otherwiseThrow()
                 : new Exception\IdEqual($this, $id);
         }
     }

diff --git a/src/ValueObject/IdList.php b/src/ValueObject/IdList.php
@@ -415,172 +415,172 @@ public function idsAsStringList(): array
 
     /**
      * @param T                       $id
-     * @param ?callable(): \Throwable $exception
+     * @param ?callable(): \Throwable $otherwiseThrow
      *
      * @throws \Throwable
      * @throws Exception\IdListDoesNotContainId
      */
     public function mustContainId(
         Id $id,
-        ?callable $exception = null,
+        ?callable $otherwiseThrow = null,
     ): void {
         if ($this->notContainsId($id)) {
-            throw $exception !== null
-                ? $exception()
+            throw $otherwiseThrow !== null
+                ? $otherwiseThrow()
                 : new Exception\IdListDoesNotContainId($id);
         }
     }
 
     /**
      * @param T                       $id
-     * @param ?callable(): \Throwable $exception
+     * @param ?callable(): \Throwable $otherwiseThrow
      *
      * @throws \Throwable
      * @throws Exception\IdListDoesContainId
      */
     public function mustNotContainId(
         Id $id,
-        ?callable $exception = null,
+        ?callable $otherwiseThrow = null,
     ): void {
         if ($this->containsId($id)) {
-            throw $exception !== null
-                ? $exception()
+            throw $otherwiseThrow !== null
+                ? $otherwiseThrow()
                 : new Exception\IdListDoesContainId($id);
         }
     }
 
     /**
-     * @param ?callable(): \Throwable $exception
+     * @param ?callable(): \Throwable $otherwiseThrow
      *
      * @throws \Throwable
      * @throws Exception\IdListDoesNotContainEveryId
      */
     public function mustContainEveryId(
         self $idList,
-        ?callable $exception = null,
+        ?callable $otherwiseThrow = null,
     ): void {
         if (!$this->containsEveryId($idList)) {
-            throw $exception !== null
-                ? $exception()
+            throw $otherwiseThrow !== null
+                ? $otherwiseThrow()
                 : new Exception\IdListDoesNotContainEveryId();
         }
     }
 
     /**
-     * @param ?callable(): \Throwable $exception
+     * @param ?callable(): \Throwable $otherwiseThrow
      *
      * @throws \Throwable
      * @throws Exception\IdListDoesContainEveryId
      */
     public function mustNotContainEveryId(
         self $idList,
-        ?callable $exception = null,
+        ?callable $otherwiseThrow = null,
     ): void {
         if (!$this->notContainsEveryId($idList)) {
-            throw $exception !== null
-                ? $exception()
+            throw $otherwiseThrow !== null
+                ? $otherwiseThrow()
                 : new Exception\IdListDoesContainEveryId();
         }
     }
 
     /**
-     * @param ?callable(): \Throwable $exception
+     * @param ?callable(): \Throwable $otherwiseThrow
      *
      * @throws \Throwable
      * @throws Exception\IdListDoesNotContainSomeIds
      */
     public function mustContainSomeIds(
         self $idList,
-        ?callable $exception = null,
+        ?callable $otherwiseThrow = null,
     ): void {
         if (!$this->containsSomeIds($idList)) {
-            throw $exception !== null
-                ? $exception()
+            throw $otherwiseThrow !== null
+                ? $otherwiseThrow()
                 : new Exception\IdListDoesNotContainSomeIds();
         }
     }
 
     /**
-     * @param ?callable(): \Throwable $exception
+     * @param ?callable(): \Throwable $otherwiseThrow
      *
      * @throws \Throwable
      * @throws Exception\IdListDoesContainNoneIds
      */
     public function mustContainNoneIds(
         self $idList,
-        ?callable $exception = null,
+        ?callable $otherwiseThrow = null,
     ): void {
         if (!$this->containsNoneIds($idList)) {
-            throw $exception !== null
-                ? $exception()
+            throw $otherwiseThrow !== null
+                ? $otherwiseThrow()
                 : new Exception\IdListDoesContainNoneIds();
         }
     }
 
     /**
-     * @param ?callable(): \Throwable $exception
+     * @param ?callable(): \Throwable $otherwiseThrow
      *
      * @throws \Throwable
      * @throws Exception\IdListIsNotEmpty
      */
     public function mustBeEmpty(
-        ?callable $exception = null,
+        ?callable $otherwiseThrow = null,
     ): void {
         if ($this->isNotEmpty()) {
-            throw $exception !== null
-                ? $exception()
+            throw $otherwiseThrow !== null
+                ? $otherwiseThrow()
                 : new Exception\IdListIsNotEmpty();
         }
     }
 
     /**
-     * @param ?callable(): \Throwable $exception
+     * @param ?callable(): \Throwable $otherwiseThrow
      *
      * @throws \Throwable
      * @throws Exception\IdListIsEmpty
      */
     public function mustNotBeEmpty(
-        ?callable $exception = null,
+        ?callable $otherwiseThrow = null,
     ): void {
         if ($this->isEmpty()) {
-            throw $exception !== null
-                ? $exception()
+            throw $otherwiseThrow !== null
+                ? $otherwiseThrow()
                 : new Exception\IdListIsEmpty();
         }
     }
 
     /**
      * @param static                  $idList
-     * @param ?callable(): \Throwable $exception
+     * @param ?callable(): \Throwable $otherwiseThrow
      *
      * @throws \Throwable
      * @throws Exception\IdListsMustBeEqual
      */
     public function mustBeEqualTo(
         self $idList,
-        ?callable $exception = null,
+        ?callable $otherwiseThrow = null,
     ): void {
         if ($this->isNotEqualTo($idList)) {
-            throw $exception !== null
-                ? $exception()
+            throw $otherwiseThrow !== null
+                ? $otherwiseThrow()
                 : new Exception\IdListsMustBeEqual();
         }
     }
 
     /**
      * @param static                  $idList
-     * @param ?callable(): \Throwable $exception
+     * @param ?callable(): \Throwable $otherwiseThrow
      *
      * @throws \Throwable
      * @throws Exception\IdListsMustNotBeEqual
      */
     public function mustNotBeEqualTo(
         self $idList,
-        ?callable $exception = null,
+        ?callable $otherwiseThrow = null,
     ): void {
         if ($this->isEqualTo($idList)) {
-            throw $exception !== null
-                ? $exception()
+            throw $otherwiseThrow !== null
+                ? $otherwiseThrow()
                 : new Exception\IdListsMustNotBeEqual();
         }
     }

diff --git a/tests/ValueObject/IdListTest.php b/tests/ValueObject/IdListTest.php
@@ -797,7 +797,7 @@ public function id_list_must_contain_throws_custom_exception(): void
         // -- Act
         $idsOfEnabledUsers->mustContainId(
             $idMarkus,
-            static fn () => new UserIsNotEnabled(),
+            otherwiseThrow: static fn () => new UserIsNotEnabled(),
         );
     }
 
@@ -846,7 +846,7 @@ public function id_list_must_not_contain_throws_custom_exception(): void
         // -- Act
         $idsOfDisabledUsers->mustNotContainId(
             $idAnton,
-            static fn () => new UserIsDisabled(),
+            otherwiseThrow: static fn () => new UserIsDisabled(),
         );
     }
 
@@ -903,7 +903,7 @@ public function id_list_must_contain_every_id_throws_custom_exception(): void
         // -- Act
         $idsOfEnabledUsers->mustContainEveryId(
             $idsOfAllUsers,
-            static fn () => new NotAllUsersAreEnabled(),
+            otherwiseThrow: static fn () => new NotAllUsersAreEnabled(),
         );
     }
 
@@ -986,7 +986,7 @@ public function id_list_must_not_contain_every_id_throws_custom_exception(): voi
         // -- Act
         $idsOfEnabledUsers->mustNotContainEveryId(
             $idsOfDisabledUsers,
-            static fn () => new NotAllUsersAreDisabled(),
+            otherwiseThrow: static fn () => new NotAllUsersAreDisabled(),
         );
     }
 
@@ -1073,7 +1073,7 @@ public function id_list_must_contain_some_ids_throws_custom_exception(): void
         // -- Act
         $idsOfUserWithAccess->mustContainSomeIds(
             $idsOfUsersToPerformAction,
-            static fn () => new NoUserCanPerformAction(),
+            otherwiseThrow: static fn () => new NoUserCanPerformAction(),
         );
     }
 
@@ -1165,7 +1165,7 @@ public function id_list_must_contain_none_ids_throws_custom_exception(): void
         // -- Act
         $idsOfEnabledUsers->mustContainNoneIds(
             $idsOfUserToEnable,
-            static fn () => new SomeUsersAreAlreadyEnabled(),
+            otherwiseThrow: static fn () => new SomeUsersAreAlreadyEnabled(),
         );
     }
 
@@ -1251,7 +1251,7 @@ public function id_list_must_be_empty_throws_custom_exception_when_not_empty():
 
         // -- Act
         $idsOfUsersWithOutstandingIssues->mustBeEmpty(
-            static fn () => new ThereAreStillUsersWithIssues(),
+            otherwiseThrow: static fn () => new ThereAreStillUsersWithIssues(),
         );
     }
 
@@ -1307,7 +1307,7 @@ public function id_list_must_not_be_empty_throws_custom_exception_when_empty():
 
         // -- Act
         $idsOfUserWithAccess->mustNotBeEmpty(
-            static fn () => new ThereMustBeAtLeastOneUserWithAccess(),
+            otherwiseThrow: static fn () => new ThereMustBeAtLeastOneUserWithAccess(),
         );
     }
 

diff --git a/tests/ValueObject/IdTest.php b/tests/ValueObject/IdTest.php
@@ -141,7 +141,7 @@ public function user_id_must_be_equal_fails_with_custom_exception(): void
         // -- Act
         $userId1->mustBeEqualTo(
             $userId2,
-            static fn () => new NotTheSameUser(),
+            otherwiseThrow: static fn () => new NotTheSameUser(),
         );
     }
 
@@ -180,7 +180,7 @@ public function user_id_must_not_be_equal_fails_with_custom_exception(): void
         // -- Act
         $userId1->mustNotBeEqualTo(
             $userId2,
-            static fn () => new SameUser(),
+            otherwiseThrow: static fn () => new SameUser(),
         );
     }
 }