Rename When to LogicCond

henriquemoody · henriquemoody · commit 1d6e75ec4b57 · 2026-01-11T09:49:25.000+01:00
The name `When` was ambiguous and didn't clearly convey its purpose
as a conditional validator. The new name `LogicCond` clearly indicates
this is a logical conditional operation (if-then-else) where validation
follows different paths based on whether a condition passes or fails.

This rename is part of a broader effort to improve the naming of
composite rules in version 3.0, making them more intuitive and
reducing potential confusion when implementing validation logic.
diff --git a/docs/feature-guide.md b/docs/feature-guide.md
@@ -40,7 +40,7 @@ Respect\Validation offers over 150 validators, many of which are designed to add
 - Validating **Arrays**: [Key](validators/Key.md), [KeyOptional](validators/KeyOptional.md), [KeyExists](validators/KeyExists.md).
 - Validating **Array structures**: [KeySet](validators/KeySet.md).
 - Validating **Object properties**: [Property](validators/Property.md), [PropertyOptional](validators/PropertyOptional.md), [PropertyExists](validators/PropertyExists.md).
-- Using **Conditional validation**: [NullOr](validators/NullOr.md), [UndefOr](validators/UndefOr.md), [When](validators/When.md).
+- Using **Conditional validation**: [NullOr](validators/NullOr.md), [UndefOr](validators/UndefOr.md), [LogicCond](validators/LogicCond.md).
 - Using **Logical validation**: [LogicAnd](validators/LogicAnd.md), [LogicOr](validators/LogicOr.md), [LogicNor](validators/LogicNor.md), [LogicXor](validators/LogicXor.md)
 - Validating **Each** value in the input: [Each](validators/Each.md).
 - Validating the **Length** of the input: [Length](validators/Length.md).
diff --git a/docs/list-of-validators-by-category.md b/docs/list-of-validators-by-category.md
@@ -67,8 +67,8 @@
 ## Conditions
 
 - [Circuit](validators/Circuit.md)
+- [LogicCond](validators/LogicCond.md)
 - [Not](validators/Not.md)
-- [When](validators/When.md)
 
 ## Core
 
@@ -147,6 +147,7 @@
 ## Logical
 
 - [LogicAnd](validators/LogicAnd.md)
+- [LogicCond](validators/LogicCond.md)
 - [LogicNor](validators/LogicNor.md)
 - [LogicOr](validators/LogicOr.md)
 - [LogicXor](validators/LogicXor.md)
@@ -181,6 +182,7 @@
 - [KeySet](validators/KeySet.md)
 - [Lazy](validators/Lazy.md)
 - [LogicAnd](validators/LogicAnd.md)
+- [LogicCond](validators/LogicCond.md)
 - [LogicNor](validators/LogicNor.md)
 - [LogicOr](validators/LogicOr.md)
 - [LogicXor](validators/LogicXor.md)
@@ -189,7 +191,6 @@
 - [Property](validators/Property.md)
 - [PropertyOptional](validators/PropertyOptional.md)
 - [UndefOr](validators/UndefOr.md)
-- [When](validators/When.md)
 
 ## Numbers
 
@@ -398,6 +399,7 @@
 - [LessThan](validators/LessThan.md)
 - [LessThanOrEqual](validators/LessThanOrEqual.md)
 - [LogicAnd](validators/LogicAnd.md)
+- [LogicCond](validators/LogicCond.md)
 - [LogicNor](validators/LogicNor.md)
 - [LogicOr](validators/LogicOr.md)
 - [LogicXor](validators/LogicXor.md)
@@ -467,6 +469,5 @@
 - [Version](validators/Version.md)
 - [VideoUrl](validators/VideoUrl.md)
 - [Vowel](validators/Vowel.md)
-- [When](validators/When.md)
 - [Writable](validators/Writable.md)
 - [Xdigit](validators/Xdigit.md)
diff --git a/docs/validators/AlwaysInvalid.md b/docs/validators/AlwaysInvalid.md
@@ -45,4 +45,4 @@ v::alwaysInvalid()->isValid('whatever'); // false
 See also:
 
 - [AlwaysValid](AlwaysValid.md)
-- [When](When.md)
+- [LogicCond](LogicCond.md)
diff --git a/docs/validators/Circuit.md b/docs/validators/Circuit.md
@@ -17,7 +17,7 @@ v::circuit(
 ```
 
 You need a valid country code to create a [SubdivisionCode](SubdivisionCode.md), so it makes sense only to validate the
-subdivision code only if the country code is valid. In this case, you could also have used [When](When.md), but you
+subdivision code only if the country code is valid. In this case, you could also have used [LogicCond](LogicCond.md), but you
 would then have to write `v::key('countryCode', v::countryCode())` twice in your chain.
 
 ## Templates
@@ -42,8 +42,8 @@ See also:
 
 - [Lazy](Lazy.md)
 - [LogicAnd](LogicAnd.md)
+- [LogicCond](LogicCond.md)
 - [LogicNor](LogicNor.md)
 - [LogicOr](LogicOr.md)
 - [LogicXor](LogicXor.md)
 - [SubdivisionCode](SubdivisionCode.md)
-- [When](When.md)
diff --git a/docs/validators/LogicAnd.md b/docs/validators/LogicAnd.md
@@ -52,7 +52,7 @@ Used when all validators have failed.
 See also:
 
 - [Circuit](Circuit.md)
+- [LogicCond](LogicCond.md)
 - [LogicNor](LogicNor.md)
 - [LogicOr](LogicOr.md)
 - [LogicXor](LogicXor.md)
-- [When](When.md)
diff --git a/docs/validators/LogicCond.md b/docs/validators/LogicCond.md
@@ -1,19 +1,18 @@
-# When
+# LogicCond
 
-- `When(Validator $if, Validator $then)`
-- `When(Validator $if, Validator $then, Validator $else)`
+- `LogicCond(Validator $if, Validator $then)`
+- `LogicCond(Validator $if, Validator $then, Validator $else)`
 
-A ternary validator that accepts three parameters.
+A conditional validator that applies logic based on the validation results.
 
-When the `$if` validates, returns validation for `$then`.
-When the `$if` doesn't validate, returns validation for `$else`, if defined.
+If the `$if` validator passes, it applies the `$then` validator. If the `$if` validator fails, it applies the `$else` validator (if provided); otherwise, validation fails.
 
 ```php
-v::when(v::intVal(), v::positive(), v::notBlank())->isValid(1); // true
-v::when(v::intVal(), v::positive(), v::notBlank())->isValid('non-blank string'); // true
+v::logicCond(v::intVal(), v::positive(), v::notBlank())->isValid(1); // true
+v::logicCond(v::intVal(), v::positive(), v::notBlank())->isValid('non-blank string'); // true
 
-v::when(v::intVal(), v::positive(), v::notBlank())->isValid(-1); // false
-v::when(v::intVal(), v::positive(), v::notBlank())->isValid(''); // false
+v::logicCond(v::intVal(), v::positive(), v::notBlank())->isValid(-1); // false
+v::logicCond(v::intVal(), v::positive(), v::notBlank())->isValid(''); // false
 ```
 
 In the sample above, if `$input` is an integer, then it must be positive.
@@ -31,14 +30,16 @@ When `$else` is not defined use [AlwaysInvalid](AlwaysInvalid.md)
 ## Categorization
 
 - Conditions
+- Logical
 - Nesting
 
 ## Changelog
 
 | Version | Description                         |
 | ------: | ----------------------------------- |
+|   3.0.0 | Renamed to `LogicCond`              |
 |   0.8.0 | Allow to use validator without else |
-|   0.3.9 | Created                             |
+|   0.3.9 | Created as `When`                   |
 
 ---
 
diff --git a/docs/validators/LogicNor.md b/docs/validators/LogicNor.md
@@ -58,7 +58,7 @@ See also:
 
 - [Circuit](Circuit.md)
 - [LogicAnd](LogicAnd.md)
+- [LogicCond](LogicCond.md)
 - [LogicOr](LogicOr.md)
 - [LogicXor](LogicXor.md)
 - [Not](Not.md)
-- [When](When.md)
diff --git a/docs/validators/LogicOr.md b/docs/validators/LogicOr.md
@@ -48,6 +48,6 @@ See also:
 - [Circuit](Circuit.md)
 - [ContainsAny](ContainsAny.md)
 - [LogicAnd](LogicAnd.md)
+- [LogicCond](LogicCond.md)
 - [LogicNor](LogicNor.md)
 - [LogicXor](LogicXor.md)
-- [When](When.md)
diff --git a/docs/validators/LogicXor.md b/docs/validators/LogicXor.md
@@ -59,6 +59,6 @@ See also:
 
 - [Circuit](Circuit.md)
 - [LogicAnd](LogicAnd.md)
+- [LogicCond](LogicCond.md)
 - [LogicNor](LogicNor.md)
 - [LogicOr](LogicOr.md)
-- [When](When.md)
diff --git a/library/Mixins/AllBuilder.php b/library/Mixins/AllBuilder.php
@@ -197,6 +197,8 @@ public static function allLogicAnd(
         Validator ...$validators,
     ): Chain;
 
+    public static function allLogicCond(Validator $logicCond, Validator $then, Validator|null $else = null): Chain;
+
     public static function allLogicNor(
         Validator $validator1,
         Validator $validator2,
@@ -329,8 +331,6 @@ public static function allVideoUrl(string|null $service = null): Chain;
 
     public static function allVowel(string ...$additionalChars): Chain;
 
-    public static function allWhen(Validator $when, Validator $then, Validator|null $else = null): Chain;
-
     public static function allWritable(): Chain;
 
     public static function allXdigit(string ...$additionalChars): Chain;
diff --git a/library/Mixins/AllChain.php b/library/Mixins/AllChain.php
@@ -193,6 +193,8 @@ public function allLessThanOrEqual(mixed $compareTo): Chain;
 
     public function allLogicAnd(Validator $validator1, Validator $validator2, Validator ...$validators): Chain;
 
+    public function allLogicCond(Validator $logicCond, Validator $then, Validator|null $else = null): Chain;
+
     public function allLogicNor(Validator $validator1, Validator $validator2, Validator ...$validators): Chain;
 
     public function allLogicOr(Validator $validator1, Validator $validator2, Validator ...$validators): Chain;
@@ -317,8 +319,6 @@ public function allVideoUrl(string|null $service = null): Chain;
 
     public function allVowel(string ...$additionalChars): Chain;
 
-    public function allWhen(Validator $when, Validator $then, Validator|null $else = null): Chain;
-
     public function allWritable(): Chain;
 
     public function allXdigit(string ...$additionalChars): Chain;
diff --git a/library/Mixins/Builder.php b/library/Mixins/Builder.php
@@ -217,6 +217,8 @@ public static function lessThanOrEqual(mixed $compareTo): Chain;
 
     public static function logicAnd(Validator $validator1, Validator $validator2, Validator ...$validators): Chain;
 
+    public static function logicCond(Validator $logicCond, Validator $then, Validator|null $else = null): Chain;
+
     public static function logicNor(Validator $validator1, Validator $validator2, Validator ...$validators): Chain;
 
     public static function logicOr(Validator $validator1, Validator $validator2, Validator ...$validators): Chain;
@@ -356,8 +358,6 @@ public static function videoUrl(string|null $service = null): Chain;
 
     public static function vowel(string ...$additionalChars): Chain;
 
-    public static function when(Validator $when, Validator $then, Validator|null $else = null): Chain;
-
     public static function writable(): Chain;
 
     public static function xdigit(string ...$additionalChars): Chain;
diff --git a/library/Mixins/Chain.php b/library/Mixins/Chain.php
@@ -220,6 +220,8 @@ public function lessThanOrEqual(mixed $compareTo): Chain;
 
     public function logicAnd(Validator $validator1, Validator $validator2, Validator ...$validators): Chain;
 
+    public function logicCond(Validator $logicCond, Validator $then, Validator|null $else = null): Chain;
+
     public function logicNor(Validator $validator1, Validator $validator2, Validator ...$validators): Chain;
 
     public function logicOr(Validator $validator1, Validator $validator2, Validator ...$validators): Chain;
@@ -359,8 +361,6 @@ public function videoUrl(string|null $service = null): Chain;
 
     public function vowel(string ...$additionalChars): Chain;
 
-    public function when(Validator $when, Validator $then, Validator|null $else = null): Chain;
-
     public function writable(): Chain;
 
     public function xdigit(string ...$additionalChars): Chain;
diff --git a/library/Mixins/KeyBuilder.php b/library/Mixins/KeyBuilder.php
@@ -207,6 +207,13 @@ public static function keyLogicAnd(
         Validator ...$validators,
     ): Chain;
 
+    public static function keyLogicCond(
+        int|string $key,
+        Validator $logicCond,
+        Validator $then,
+        Validator|null $else = null,
+    ): Chain;
+
     public static function keyLogicNor(
         int|string $key,
         Validator $validator1,
@@ -346,13 +353,6 @@ public static function keyVideoUrl(int|string $key, string|null $service = null)
 
     public static function keyVowel(int|string $key, string ...$additionalChars): Chain;
 
-    public static function keyWhen(
-        int|string $key,
-        Validator $when,
-        Validator $then,
-        Validator|null $else = null,
-    ): Chain;
-
     public static function keyWritable(int|string $key): Chain;
 
     public static function keyXdigit(int|string $key, string ...$additionalChars): Chain;
diff --git a/library/Mixins/KeyChain.php b/library/Mixins/KeyChain.php
@@ -207,6 +207,13 @@ public function keyLogicAnd(
         Validator ...$validators,
     ): Chain;
 
+    public function keyLogicCond(
+        int|string $key,
+        Validator $logicCond,
+        Validator $then,
+        Validator|null $else = null,
+    ): Chain;
+
     public function keyLogicNor(
         int|string $key,
         Validator $validator1,
@@ -346,8 +353,6 @@ public function keyVideoUrl(int|string $key, string|null $service = null): Chain
 
     public function keyVowel(int|string $key, string ...$additionalChars): Chain;
 
-    public function keyWhen(int|string $key, Validator $when, Validator $then, Validator|null $else = null): Chain;
-
     public function keyWritable(int|string $key): Chain;
 
     public function keyXdigit(int|string $key, string ...$additionalChars): Chain;
diff --git a/library/Mixins/NotBuilder.php b/library/Mixins/NotBuilder.php
@@ -209,6 +209,8 @@ public static function notLogicAnd(
         Validator ...$validators,
     ): Chain;
 
+    public static function notLogicCond(Validator $logicCond, Validator $then, Validator|null $else = null): Chain;
+
     public static function notLogicNor(
         Validator $validator1,
         Validator $validator2,
@@ -345,8 +347,6 @@ public static function notVideoUrl(string|null $service = null): Chain;
 
     public static function notVowel(string ...$additionalChars): Chain;
 
-    public static function notWhen(Validator $when, Validator $then, Validator|null $else = null): Chain;
-
     public static function notWritable(): Chain;
 
     public static function notXdigit(string ...$additionalChars): Chain;
diff --git a/library/Mixins/NotChain.php b/library/Mixins/NotChain.php
@@ -205,6 +205,8 @@ public function notLessThanOrEqual(mixed $compareTo): Chain;
 
     public function notLogicAnd(Validator $validator1, Validator $validator2, Validator ...$validators): Chain;
 
+    public function notLogicCond(Validator $logicCond, Validator $then, Validator|null $else = null): Chain;
+
     public function notLogicNor(Validator $validator1, Validator $validator2, Validator ...$validators): Chain;
 
     public function notLogicOr(Validator $validator1, Validator $validator2, Validator ...$validators): Chain;
@@ -333,8 +335,6 @@ public function notVideoUrl(string|null $service = null): Chain;
 
     public function notVowel(string ...$additionalChars): Chain;
 
-    public function notWhen(Validator $when, Validator $then, Validator|null $else = null): Chain;
-
     public function notWritable(): Chain;
 
     public function notXdigit(string ...$additionalChars): Chain;
diff --git a/library/Mixins/NullOrBuilder.php b/library/Mixins/NullOrBuilder.php
@@ -213,6 +213,8 @@ public static function nullOrLogicAnd(
         Validator ...$validators,
     ): Chain;
 
+    public static function nullOrLogicCond(Validator $logicCond, Validator $then, Validator|null $else = null): Chain;
+
     public static function nullOrLogicNor(
         Validator $validator1,
         Validator $validator2,
@@ -353,8 +355,6 @@ public static function nullOrVideoUrl(string|null $service = null): Chain;
 
     public static function nullOrVowel(string ...$additionalChars): Chain;
 
-    public static function nullOrWhen(Validator $when, Validator $then, Validator|null $else = null): Chain;
-
     public static function nullOrWritable(): Chain;
 
     public static function nullOrXdigit(string ...$additionalChars): Chain;
diff --git a/library/Mixins/NullOrChain.php b/library/Mixins/NullOrChain.php
@@ -205,6 +205,8 @@ public function nullOrLessThanOrEqual(mixed $compareTo): Chain;
 
     public function nullOrLogicAnd(Validator $validator1, Validator $validator2, Validator ...$validators): Chain;
 
+    public function nullOrLogicCond(Validator $logicCond, Validator $then, Validator|null $else = null): Chain;
+
     public function nullOrLogicNor(Validator $validator1, Validator $validator2, Validator ...$validators): Chain;
 
     public function nullOrLogicOr(Validator $validator1, Validator $validator2, Validator ...$validators): Chain;
@@ -333,8 +335,6 @@ public function nullOrVideoUrl(string|null $service = null): Chain;
 
     public function nullOrVowel(string ...$additionalChars): Chain;
 
-    public function nullOrWhen(Validator $when, Validator $then, Validator|null $else = null): Chain;
-
     public function nullOrWritable(): Chain;
 
     public function nullOrXdigit(string ...$additionalChars): Chain;
diff --git a/library/Mixins/PropertyBuilder.php b/library/Mixins/PropertyBuilder.php
@@ -211,6 +211,13 @@ public static function propertyLogicAnd(
         Validator ...$validators,
     ): Chain;
 
+    public static function propertyLogicCond(
+        string $propertyName,
+        Validator $logicCond,
+        Validator $then,
+        Validator|null $else = null,
+    ): Chain;
+
     public static function propertyLogicNor(
         string $propertyName,
         Validator $validator1,
@@ -358,13 +365,6 @@ public static function propertyVideoUrl(string $propertyName, string|null $servi
 
     public static function propertyVowel(string $propertyName, string ...$additionalChars): Chain;
 
-    public static function propertyWhen(
-        string $propertyName,
-        Validator $when,
-        Validator $then,
-        Validator|null $else = null,
-    ): Chain;
-
     public static function propertyWritable(string $propertyName): Chain;
 
     public static function propertyXdigit(string $propertyName, string ...$additionalChars): Chain;
diff --git a/library/Mixins/PropertyChain.php b/library/Mixins/PropertyChain.php
diff --git a/library/Mixins/UndefOrBuilder.php b/library/Mixins/UndefOrBuilder.php
diff --git a/library/Mixins/UndefOrChain.php b/library/Mixins/UndefOrChain.php
diff --git a/library/Validators/LogicCond.php b/library/Validators/LogicCond.php
diff --git a/tests/feature/Issues/Issue739Test.php b/tests/feature/Issues/Issue739Test.php
diff --git a/tests/feature/Validators/LogicCondTest.php b/tests/feature/Validators/LogicCondTest.php
diff --git a/tests/unit/Validators/LogicCondTest.php b/tests/unit/Validators/LogicCondTest.php
diff --git a/tests/unit/Validators/WhenTest.php b/tests/unit/Validators/WhenTest.php
