Rename "Consecutive" to "Circuit"

henriquemoody · henriquemoody · commit 0c07060a048f · 2024-12-20T16:53:56.000+01:00
The "Consecutive" rule is now renamed to "Circuit" to better reflect its
behavior of stopping at the first failure. I also favour this name
because it's much shorter.
diff --git a/docs/02-feature-guide.md b/docs/02-feature-guide.md
@@ -43,7 +43,7 @@ Respect\Validation offers over 150 rules, many of which are designed to address
 * Validating the **Length** of the input: [Length](rules/Length.md).
 * Validating the **Maximum** value in the input: [Max](rules/Max.md).
 * Validating the **Minimum** value in the input: [Min](rules/Min.md).
-* Handling **Special cases**: [Lazy](rules/Lazy.md), [Consecutive](rules/Consecutive.md), [Call](rules/Call.md).
+* Handling **Special cases**: [Lazy](rules/Lazy.md), [Circuit](rules/Circuit.md), [Call](rules/Call.md).
 
 ### Custom templates
 
diff --git a/docs/09-list-of-rules-by-category.md b/docs/09-list-of-rules-by-category.md
@@ -61,13 +61,11 @@
 
 - [AllOf](rules/AllOf.md)
 - [AnyOf](rules/AnyOf.md)
-- [Consecutive](rules/Consecutive.md)
 - [NoneOf](rules/NoneOf.md)
 - [OneOf](rules/OneOf.md)
 
 ## Conditions
 
-- [Consecutive](rules/Consecutive.md)
 - [Not](rules/Not.md)
 - [When](rules/When.md)
 
@@ -163,7 +161,6 @@
 - [AllOf](rules/AllOf.md)
 - [AnyOf](rules/AnyOf.md)
 - [Call](rules/Call.md)
-- [Consecutive](rules/Consecutive.md)
 - [Each](rules/Each.md)
 - [Key](rules/Key.md)
 - [KeySet](rules/KeySet.md)
@@ -314,7 +311,6 @@
 - [Charset](rules/Charset.md)
 - [Cnh](rules/Cnh.md)
 - [Cnpj](rules/Cnpj.md)
-- [Consecutive](rules/Consecutive.md)
 - [Consonant](rules/Consonant.md)
 - [Contains](rules/Contains.md)
 - [ContainsAny](rules/ContainsAny.md)
diff --git a/docs/rules/AllOf.md b/docs/rules/AllOf.md
@@ -46,7 +46,7 @@ v::allOf(v::intVal(), v::positive())->isValid(15); // true
 See also:
 
 - [AnyOf](AnyOf.md)
-- [Consecutive](Consecutive.md)
+- [Circuit](Circuit.md)
 - [NoneOf](NoneOf.md)
 - [OneOf](OneOf.md)
 - [When](When.md)
diff --git a/docs/rules/AnyOf.md b/docs/rules/AnyOf.md
@@ -44,7 +44,7 @@ so `AnyOf()` returns true.
 See also:
 
 - [AllOf](AllOf.md)
-- [Consecutive](Consecutive.md)
+- [Circuit](Circuit.md)
 - [ContainsAny](ContainsAny.md)
 - [NoneOf](NoneOf.md)
 - [OneOf](OneOf.md)
diff --git a/docs/rules/Circuit.md b/docs/rules/Circuit.md
@@ -1,16 +1,16 @@
-# Consecutive
+# Circuit
 
-- `Consecutive(Rule $rule1, Rule $rule2, Rule ...$rule)`
+- `Circuit(Rule $rule1, Rule $rule2, Rule ...$rule)`
 
-Validates the input against a series of rules until one fails.
+Validates the input against a series of rules until the first fails.
 
 This rule can be handy for getting the least error messages possible from a chain.
 
 This rule can be helpful in combinations with [Lazy](Lazy.md). An excellent example is when you want to validate a
 country code and a subdivision code.
 
 ```php
-v::consecutive(
+v::circuit(
     v::key('countryCode', v::countryCode()),
     v::lazy(static fn($input) => v::key('subdivisionCode', v::subdivisionCode($input['countryCode']))),
 )->isValid($_POST);
@@ -22,11 +22,7 @@ would then have to write `v::key('countryCode', v::countryCode())` twice in your
 
 ## Templates
 
-## Template placeholders
-
-| Placeholder | Description                                                      |
-|-------------|------------------------------------------------------------------|
-| `name`      | The validated input or the custom validator name (if specified). |
+This rule does not have any templates, because it will always return the result of the first rule that fails. When all the validation rules pass, it will return the result of the last rule of the circuit.
 
 ## Categorization
 
diff --git a/docs/rules/Lazy.md b/docs/rules/Lazy.md
@@ -47,4 +47,4 @@ See also:
 
 - [Call](Call.md)
 - [CallableType](CallableType.md)
-- [Consecutive](Consecutive.md)
+- [Circuit](Circuit.md)
diff --git a/docs/rules/NoneOf.md b/docs/rules/NoneOf.md
@@ -45,7 +45,7 @@ See also:
 
 - [AllOf](AllOf.md)
 - [AnyOf](AnyOf.md)
-- [Consecutive](Consecutive.md)
+- [Circuit](Circuit.md)
 - [Not](Not.md)
 - [OneOf](OneOf.md)
 - [When](When.md)
diff --git a/docs/rules/OneOf.md b/docs/rules/OneOf.md
@@ -46,6 +46,6 @@ See also:
 
 - [AllOf](AllOf.md)
 - [AnyOf](AnyOf.md)
-- [Consecutive](Consecutive.md)
+- [Circuit](Circuit.md)
 - [NoneOf](NoneOf.md)
 - [When](When.md)
diff --git a/docs/rules/SubdivisionCode.md b/docs/rules/SubdivisionCode.md
@@ -44,7 +44,7 @@ v::subdivisionCode('US')->isValid('CA'); // true
 ***
 See also:
 
-- [Consecutive](Consecutive.md)
+- [Circuit](Circuit.md)
 - [CountryCode](CountryCode.md)
 - [CurrencyCode](CurrencyCode.md)
 - [Nip](Nip.md)
diff --git a/docs/rules/When.md b/docs/rules/When.md
@@ -46,6 +46,6 @@ See also:
 - [AllOf](AllOf.md)
 - [AlwaysInvalid](AlwaysInvalid.md)
 - [AnyOf](AnyOf.md)
-- [Consecutive](Consecutive.md)
+- [Circuit](Circuit.md)
 - [NoneOf](NoneOf.md)
 - [OneOf](OneOf.md)
diff --git a/library/Mixins/Builder.php b/library/Mixins/Builder.php
@@ -65,12 +65,12 @@ public static function callback(callable $callback, mixed ...$arguments): Chain;
 
     public static function charset(string $charset, string ...$charsets): Chain;
 
+    public static function circuit(Rule $rule1, Rule $rule2, Rule ...$rules): Chain;
+
     public static function cnh(): Chain;
 
     public static function cnpj(): Chain;
 
-    public static function consecutive(Rule $rule1, Rule $rule2, Rule ...$rules): Chain;
-
     public static function consonant(string ...$additionalChars): Chain;
 
     public static function contains(mixed $containsValue, bool $identical = false): Chain;
diff --git a/library/Mixins/Chain.php b/library/Mixins/Chain.php
@@ -70,12 +70,12 @@ public function callback(callable $callback, mixed ...$arguments): Chain;
 
     public function charset(string $charset, string ...$charsets): Chain;
 
+    public function circuit(Rule $rule1, Rule $rule2, Rule ...$rules): Chain;
+
     public function cnh(): Chain;
 
     public function cnpj(): Chain;
 
-    public function consecutive(Rule $rule1, Rule $rule2, Rule ...$rules): Chain;
-
     public function consonant(string ...$additionalChars): Chain;
 
     public function contains(mixed $containsValue, bool $identical = false): Chain;
diff --git a/library/Mixins/KeyBuilder.php b/library/Mixins/KeyBuilder.php
@@ -56,12 +56,12 @@ public static function keyCallback(int|string $key, callable $callback, mixed ..
 
     public static function keyCharset(int|string $key, string $charset, string ...$charsets): Chain;
 
+    public static function keyCircuit(int|string $key, Rule $rule1, Rule $rule2, Rule ...$rules): Chain;
+
     public static function keyCnh(int|string $key): Chain;
 
     public static function keyCnpj(int|string $key): Chain;
 
-    public static function keyConsecutive(int|string $key, Rule $rule1, Rule $rule2, Rule ...$rules): Chain;
-
     public static function keyConsonant(int|string $key, string ...$additionalChars): Chain;
 
     public static function keyContains(int|string $key, mixed $containsValue, bool $identical = false): Chain;
diff --git a/library/Mixins/KeyChain.php b/library/Mixins/KeyChain.php
@@ -56,12 +56,12 @@ public function keyCallback(int|string $key, callable $callback, mixed ...$argum
 
     public function keyCharset(int|string $key, string $charset, string ...$charsets): Chain;
 
+    public function keyCircuit(int|string $key, Rule $rule1, Rule $rule2, Rule ...$rules): Chain;
+
     public function keyCnh(int|string $key): Chain;
 
     public function keyCnpj(int|string $key): Chain;
 
-    public function keyConsecutive(int|string $key, Rule $rule1, Rule $rule2, Rule ...$rules): Chain;
-
     public function keyConsonant(int|string $key, string ...$additionalChars): Chain;
 
     public function keyContains(int|string $key, mixed $containsValue, bool $identical = false): Chain;
diff --git a/library/Mixins/NotBuilder.php b/library/Mixins/NotBuilder.php
@@ -55,12 +55,12 @@ public static function notCallback(callable $callback, mixed ...$arguments): Cha
 
     public static function notCharset(string $charset, string ...$charsets): Chain;
 
+    public static function notCircuit(Rule $rule1, Rule $rule2, Rule ...$rules): Chain;
+
     public static function notCnh(): Chain;
 
     public static function notCnpj(): Chain;
 
-    public static function notConsecutive(Rule $rule1, Rule $rule2, Rule ...$rules): Chain;
-
     public static function notConsonant(string ...$additionalChars): Chain;
 
     public static function notContains(mixed $containsValue, bool $identical = false): Chain;
diff --git a/library/Mixins/NotChain.php b/library/Mixins/NotChain.php
@@ -55,12 +55,12 @@ public function notCallback(callable $callback, mixed ...$arguments): Chain;
 
     public function notCharset(string $charset, string ...$charsets): Chain;
 
+    public function notCircuit(Rule $rule1, Rule $rule2, Rule ...$rules): Chain;
+
     public function notCnh(): Chain;
 
     public function notCnpj(): Chain;
 
-    public function notConsecutive(Rule $rule1, Rule $rule2, Rule ...$rules): Chain;
-
     public function notConsonant(string ...$additionalChars): Chain;
 
     public function notContains(mixed $containsValue, bool $identical = false): Chain;
diff --git a/library/Mixins/NullOrBuilder.php b/library/Mixins/NullOrBuilder.php
@@ -57,12 +57,12 @@ public static function nullOrCallback(callable $callback, mixed ...$arguments):
 
     public static function nullOrCharset(string $charset, string ...$charsets): Chain;
 
+    public static function nullOrCircuit(Rule $rule1, Rule $rule2, Rule ...$rules): Chain;
+
     public static function nullOrCnh(): Chain;
 
     public static function nullOrCnpj(): Chain;
 
-    public static function nullOrConsecutive(Rule $rule1, Rule $rule2, Rule ...$rules): Chain;
-
     public static function nullOrConsonant(string ...$additionalChars): Chain;
 
     public static function nullOrContains(mixed $containsValue, bool $identical = false): Chain;
diff --git a/library/Mixins/NullOrChain.php b/library/Mixins/NullOrChain.php
@@ -57,12 +57,12 @@ public function nullOrCallback(callable $callback, mixed ...$arguments): Chain;
 
     public function nullOrCharset(string $charset, string ...$charsets): Chain;
 
+    public function nullOrCircuit(Rule $rule1, Rule $rule2, Rule ...$rules): Chain;
+
     public function nullOrCnh(): Chain;
 
     public function nullOrCnpj(): Chain;
 
-    public function nullOrConsecutive(Rule $rule1, Rule $rule2, Rule ...$rules): Chain;
-
     public function nullOrConsonant(string ...$additionalChars): Chain;
 
     public function nullOrContains(mixed $containsValue, bool $identical = false): Chain;
diff --git a/library/Mixins/PropertyBuilder.php b/library/Mixins/PropertyBuilder.php
@@ -56,12 +56,12 @@ public static function propertyCallback(string $propertyName, callable $callback
 
     public static function propertyCharset(string $propertyName, string $charset, string ...$charsets): Chain;
 
+    public static function propertyCircuit(string $propertyName, Rule $rule1, Rule $rule2, Rule ...$rules): Chain;
+
     public static function propertyCnh(string $propertyName): Chain;
 
     public static function propertyCnpj(string $propertyName): Chain;
 
-    public static function propertyConsecutive(string $propertyName, Rule $rule1, Rule $rule2, Rule ...$rules): Chain;
-
     public static function propertyConsonant(string $propertyName, string ...$additionalChars): Chain;
 
     public static function propertyContains(
diff --git a/library/Mixins/PropertyChain.php b/library/Mixins/PropertyChain.php
@@ -56,12 +56,12 @@ public function propertyCallback(string $propertyName, callable $callback, mixed
 
     public function propertyCharset(string $propertyName, string $charset, string ...$charsets): Chain;
 
+    public function propertyCircuit(string $propertyName, Rule $rule1, Rule $rule2, Rule ...$rules): Chain;
+
     public function propertyCnh(string $propertyName): Chain;
 
     public function propertyCnpj(string $propertyName): Chain;
 
-    public function propertyConsecutive(string $propertyName, Rule $rule1, Rule $rule2, Rule ...$rules): Chain;
-
     public function propertyConsonant(string $propertyName, string ...$additionalChars): Chain;
 
     public function propertyContains(string $propertyName, mixed $containsValue, bool $identical = false): Chain;
diff --git a/library/Mixins/UndefOrBuilder.php b/library/Mixins/UndefOrBuilder.php
@@ -55,12 +55,12 @@ public static function undefOrCallback(callable $callback, mixed ...$arguments):
 
     public static function undefOrCharset(string $charset, string ...$charsets): Chain;
 
+    public static function undefOrCircuit(Rule $rule1, Rule $rule2, Rule ...$rules): Chain;
+
     public static function undefOrCnh(): Chain;
 
     public static function undefOrCnpj(): Chain;
 
-    public static function undefOrConsecutive(Rule $rule1, Rule $rule2, Rule ...$rules): Chain;
-
     public static function undefOrConsonant(string ...$additionalChars): Chain;
 
     public static function undefOrContains(mixed $containsValue, bool $identical = false): Chain;
diff --git a/library/Mixins/UndefOrChain.php b/library/Mixins/UndefOrChain.php
@@ -55,12 +55,12 @@ public function undefOrCallback(callable $callback, mixed ...$arguments): Chain;
 
     public function undefOrCharset(string $charset, string ...$charsets): Chain;
 
+    public function undefOrCircuit(Rule $rule1, Rule $rule2, Rule ...$rules): Chain;
+
     public function undefOrCnh(): Chain;
 
     public function undefOrCnpj(): Chain;
 
-    public function undefOrConsecutive(Rule $rule1, Rule $rule2, Rule ...$rules): Chain;
-
     public function undefOrConsonant(string ...$additionalChars): Chain;
 
     public function undefOrContains(mixed $containsValue, bool $identical = false): Chain;
diff --git a/library/Rules/Circuit.php b/library/Rules/Circuit.php
@@ -15,7 +15,7 @@
 use Respect\Validation\Rules\Core\Composite;
 
 #[Attribute(Attribute::TARGET_PROPERTY | Attribute::IS_REPEATABLE)]
-final class Consecutive extends Composite
+final class Circuit extends Composite
 {
     public function evaluate(mixed $input): Result
     {
diff --git a/library/Rules/Domain.php b/library/Rules/Domain.php
@@ -58,9 +58,9 @@ public function evaluate(mixed $input): Result
         return new Result($this->partsRule->evaluate($parts)->isValid, $input, $this);
     }
 
-    private function createGenericRule(): Consecutive
+    private function createGenericRule(): Circuit
     {
-        return new Consecutive(
+        return new Circuit(
             new StringType(),
             new NoWhitespace(),
             new Contains('.'),
@@ -74,13 +74,13 @@ private function createTldRule(bool $realTldCheck): Rule
             return new Tld();
         }
 
-        return new Consecutive(new Not(new StartsWith('-')), new Length(new GreaterThanOrEqual(2)));
+        return new Circuit(new Not(new StartsWith('-')), new Length(new GreaterThanOrEqual(2)));
     }
 
     private function createPartsRule(): Rule
     {
         return new Each(
-            new Consecutive(
+            new Circuit(
                 new Alnum('-'),
                 new Not(new StartsWith('-')),
                 new AnyOf(
diff --git a/library/Transformers/DeprecatedKeyValue.php b/library/Transformers/DeprecatedKeyValue.php
@@ -42,7 +42,7 @@ public function transform(RuleSpec $ruleSpec): RuleSpec
 
         [$comparedKey, $ruleName, $baseKey] = $ruleSpec->arguments;
 
-        return new RuleSpec('consecutive', [
+        return new RuleSpec('circuit', [
             new KeyExists($comparedKey),
             new KeyExists($baseKey),
             new Lazy(
diff --git a/tests/feature/Rules/CircuitTest.php b/tests/feature/Rules/CircuitTest.php
diff --git a/tests/unit/Rules/CircuitTest.php b/tests/unit/Rules/CircuitTest.php
