Create ShortCircuit validator and ShortCircuitCapable interface

This commit introduces a mechanism for validators to return early once
the validation outcome is determined, rather than evaluating all child
validators.

The ShortCircuit validator evaluates validators sequentially and stops
at the first failure, similar to how PHP's && operator works. This is
useful when later validators depend on earlier ones passing, or when
you want only the first error message.

The ShortCircuitCapable interface allows composite validators (AllOf,
AnyOf, OneOf, NoneOf, Each, All) to implement their own short-circuit
logic:

- AllOf: stops at first failure (like &&)
- AnyOf: stops at first success (like ||)
- OneOf: stops when two validators pass (already invalid)
- NoneOf: stops at first success (already invalid)
- Each/All: stops at first failing item

Why "ShortCircuit" instead of "FailFast":

The name "FailFast" was initially considered but proved misleading.
While AllOf stops on failure (fail fast), AnyOf stops on success
(succeed fast), and OneOf stops on the second success. The common
behavior is not about failing quickly, but about returning as soon as
the outcome is determined—which is exactly what short-circuit
evaluation means. This terminology is familiar to developers from
boolean operators (&& and ||), making the behavior immediately
understandable.

Co-authored-by: Alexandre Gomes Gaigalas <alganet@gmail.com>
Assisted-by: Claude Code (Opus 4.5)

Author: henriquemoody

docs/feature-guide.md

@@ -129,7 +129,7 @@ Beyond the examples above, Respect\Validation provides specialized validators fo
 - **Grouped validation**: Combine validators with AND/OR logic using [AllOf](validators/AllOf.md), [AnyOf](validators/AnyOf.md), [NoneOf](validators/NoneOf.md), [OneOf](validators/OneOf.md).
 - **Iteration**: Validate every item in a collection with [Each](validators/Each.md).
 - **Length, Min, Max**: Validate derived values with [Length](validators/Length.md), [Min](validators/Min.md), [Max](validators/Max.md).
-- **Special cases**: Handle dynamic rules with [Lazy](validators/Lazy.md), short-circuit on first failure with [Circuit](validators/Circuit.md), or transform input before validation with [Call](validators/Call.md).
+- **Special cases**: Handle dynamic rules with [Lazy](validators/Lazy.md), short-circuit on first failure with [ShortCircuit](validators/ShortCircuit.md), or transform input before validation with [Call](validators/Call.md).
 
 ## Customizing error messages
 

docs/migrating-from-v2-to-v3.md

@@ -373,11 +373,10 @@ composer require ramsey/uuid
 
 In 3.0, `Min` and `Max` validators exist but have different semantics. They extract the minimum/maximum value from a collection and validate it (see [Result composition](#result-composition)).
 
-
-| Validator  | 2.x             | 3.x                                           |
-| ---------- | --------------- | --------------------------------------------- |
-| `Min`      | Single value >= | Pick minimum value from iterable and validate |
-| `Max`      | Single value <= | Pick minimum value from iterable and validate |
+| Validator | 2.x             | 3.x                                           |
+| --------- | --------------- | --------------------------------------------- |
+| `Min`     | Single value >= | Pick minimum value from iterable and validate |
+| `Max`     | Single value <= | Pick minimum value from iterable and validate |
 
 ##### `NotBlank` logic inverted
 
@@ -572,9 +571,9 @@ Version 3.0 introduces several new validators:
 | `All`              | Validates that every item in an iterable passes validation |
 | `Attributes`       | Validates object properties using PHP attributes           |
 | `BetweenExclusive` | Validates that a value is between two bounds (exclusive)   |
-| `Circuit`          | Short-circuit validation, stops at first failure           |
 | `ContainsCount`    | Validates the count of occurrences in a value              |
 | `DateTimeDiff`     | Validates date/time differences (replaces Age validators)  |
+| `ShortCircuit`     | Stops at first failure instead of collecting all errors    |
 | `Hetu`             | Validates Finnish personal identity codes (henkilötunnus)  |
 | `KeyExists`        | Checks if an array key exists                              |
 | `KeyOptional`      | Validates an array key only if it exists                   |
@@ -630,26 +629,6 @@ v::betweenExclusive(1, 10)->assert(1); // fails (1 is not > 1)
 v::betweenExclusive(1, 10)->assert(10); // fails (10 is not < 10)
 ```
 
-#### Circuit
-
-Validates input against a series of validators, stopping at the first failure. Useful for dependent validations:
-
-```php
-$validator = v::circuit(
-    v::key('countryCode', v::countryCode()),
-    v::lazy(
-        fn($input) => v::key(
-            'subdivisionCode',
-            v::subdivisionCode($input['countryCode'])
-        )
-    ),
-);
-
-$validator->assert([]); // → `.countryCode` must be present
-$validator->assert(['countryCode' => 'US']); // → `.subdivisionCode` must be present
-$validator->assert(['countryCode' => 'US', 'subdivisionCode' => 'CA']); // passes
-```
-
 #### ContainsCount
 
 Validates the count of occurrences of a value:
@@ -668,6 +647,26 @@ v::dateTimeDiff('years', v::greaterThanOrEqual(18))->assert('2000-01-01'); // pa
 v::dateTimeDiff('days', v::lessThan(30))->assert('2024-01-15'); // passes if less than 30 days ago
 ```
 
+#### ShortCircuit
+
+Validates input against a series of validators, stopping at the first failure. Useful for dependent validations:
+
+```php
+$validator = v::shortCircuit(
+    v::key('countryCode', v::countryCode()),
+    v::lazy(
+        fn($input) => v::key(
+            'subdivisionCode',
+            v::subdivisionCode($input['countryCode'])
+        )
+    ),
+);
+
+$validator->assert([]); // → `.countryCode` must be present
+$validator->assert(['countryCode' => 'US']); // → `.subdivisionCode` must be present
+$validator->assert(['countryCode' => 'US', 'subdivisionCode' => 'CA']); // passes
+```
+
 #### Hetu
 
 Validates Finnish personal identity codes (henkilötunnus):

docs/validators.md

@@ -17,9 +17,9 @@ In this page you will find a list of validators by their category.
 
 **Comparisons**: [All][] - [Between][] - [BetweenExclusive][] - [Equals][] - [Equivalent][] - [GreaterThan][] - [GreaterThanOrEqual][] - [Identical][] - [In][] - [Length][] - [LessThan][] - [LessThanOrEqual][] - [Max][] - [Min][]
 
-**Composite**: [AllOf][] - [AnyOf][] - [Circuit][] - [NoneOf][] - [OneOf][]
+**Composite**: [AllOf][] - [AnyOf][] - [NoneOf][] - [OneOf][] - [ShortCircuit][]
 
-**Conditions**: [Circuit][] - [Not][] - [When][]
+**Conditions**: [Not][] - [ShortCircuit][] - [When][]
 
 **Core**: [Named][] - [Not][] - [Templated][]
 
@@ -41,7 +41,7 @@ In this page you will find a list of validators by their category.
 
 **Miscellaneous**: [Blank][] - [Falsy][] - [Masked][] - [Named][] - [Templated][] - [Undef][]
 
-**Nesting**: [AllOf][] - [AnyOf][] - [Call][] - [Circuit][] - [Each][] - [Key][] - [KeySet][] - [Lazy][] - [NoneOf][] - [Not][] - [NullOr][] - [OneOf][] - [Property][] - [PropertyOptional][] - [UndefOr][] - [When][]
+**Nesting**: [AllOf][] - [AnyOf][] - [Call][] - [Each][] - [Key][] - [KeySet][] - [Lazy][] - [NoneOf][] - [Not][] - [NullOr][] - [OneOf][] - [Property][] - [PropertyOptional][] - [ShortCircuit][] - [UndefOr][] - [When][]
 
 **Numbers**: [Base][] - [Decimal][] - [Digit][] - [Even][] - [Factor][] - [Finite][] - [FloatType][] - [FloatVal][] - [Infinite][] - [IntType][] - [IntVal][] - [Multiple][] - [Negative][] - [Number][] - [NumericVal][] - [Odd][] - [Positive][] - [Roman][]
 
@@ -79,7 +79,6 @@ In this page you will find a list of validators by their category.
 - [CallableType][] - `v::callableType()->assert(function () {});`
 - [Callback][] - `v::callback(fn (int $input): bool => $input % 5 === 0,)->assert(10);`
 - [Charset][] - `v::charset('ASCII')->assert('sugar');`
-- [Circuit][] - `v::circuit(v::intVal(), v::floatVal())->assert(15);`
 - [Cnh][] - `v::cnh()->assert('02650306461');`
 - [Cnpj][] - `v::cnpj()->assert('00394460005887');`
 - [Consonant][] - `v::consonant()->assert('xkcd');`
@@ -186,6 +185,7 @@ In this page you will find a list of validators by their category.
 - [ResourceType][] - `v::resourceType()->assert(fopen('/path/to/file.txt', 'r'));`
 - [Roman][] - `v::roman()->assert('IV');`
 - [ScalarVal][] - `v::scalarVal()->assert(135.0);`
+- [ShortCircuit][] - `v::shortCircuit(v::intVal(), v::positive())->assert(15);`
 - [Size][] - `v::size('KB', v::greaterThan(1))->assert('/path/to/file');`
 - [Slug][] - `v::slug()->assert('my-wordpress-title');`
 - [Sorted][] - `v::sorted('ASC')->assert([1, 2, 3]);`
@@ -235,7 +235,6 @@ In this page you will find a list of validators by their category.
 [CallableType]: validators/CallableType.md "Validates whether the pseudo-type of the input is callable."
 [Callback]: validators/Callback.md "Validates the input using the return of a given callable."
 [Charset]: validators/Charset.md "Validates if a string is in a specific charset."
-[Circuit]: validators/Circuit.md "Validates the input against a series of validators until the first fails."
 [Cnh]: validators/Cnh.md "Validates a Brazilian driver's license."
 [Cnpj]: validators/Cnpj.md "Validates if the input is a Brazilian National Registry of Legal Entities (CNPJ) number."
 [Consonant]: validators/Consonant.md "Validates if the input contains only consonants."
@@ -342,6 +341,7 @@ In this page you will find a list of validators by their category.
 [ResourceType]: validators/ResourceType.md "Validates whether the input is a resource."
 [Roman]: validators/Roman.md "Validates if the input is a Roman numeral."
 [ScalarVal]: validators/ScalarVal.md "Validates whether the input is a scalar value or not."
+[ShortCircuit]: validators/ShortCircuit.md "Validates the input against a series of validators, stopping at the first failure."
 [Size]: validators/Size.md "Validates whether the input is a file that is of a certain size or not."
 [Slug]: validators/Slug.md "Validates whether the input is a valid slug."
 [Sorted]: validators/Sorted.md "Validates whether the input is sorted in a certain order or not."

docs/validators/AllOf.md

@@ -56,7 +56,7 @@ Used when all validators have failed.
 ## See Also
 
 - [AnyOf](AnyOf.md)
-- [Circuit](Circuit.md)
 - [NoneOf](NoneOf.md)
 - [OneOf](OneOf.md)
+- [ShortCircuit](ShortCircuit.md)
 - [When](When.md)

docs/validators/AnyOf.md

@@ -50,8 +50,8 @@ so `AnyOf()` returns true.
 ## See Also
 
 - [AllOf](AllOf.md)
-- [Circuit](Circuit.md)
 - [ContainsAny](ContainsAny.md)
 - [NoneOf](NoneOf.md)
 - [OneOf](OneOf.md)
+- [ShortCircuit](ShortCircuit.md)
 - [When](When.md)

docs/validators/Call.md

@@ -53,17 +53,17 @@ v::call(
 ```
 
 Call does not handle possible errors (type mismatches). If you need to
-ensure that your callback is of a certain type, use [Circuit](Circuit.md) or 
+ensure that your callback is of a certain type, use [ShortCircuit](ShortCircuit.md) or 
 handle it using a closure:
 
 ```php
 v::call('strtolower', v::equals('ABC'))->assert(123);
 // 𝙭 strtolower(): Argument #1 ($string) must be of type string, int given
 
-v::circuit(v::stringType(), v::call('strtolower', v::equals('abc')))->assert(123);
+v::shortCircuit(v::stringType(), v::call('strtolower', v::equals('abc')))->assert(123);
 // → 123 must be a string
 
-v::circuit(v::stringType(), v::call('strtolower', v::equals('abc')))->assert('ABC');
+v::shortCircuit(v::stringType(), v::call('strtolower', v::equals('abc')))->assert('ABC');
 // Validation passes successfully
 ```
 

docs/validators/Circuit.md

@@ -58,4 +58,4 @@ on the input itself (`$_POST`), but it will use any input that’s given to the
 
 - [Call](Call.md)
 - [CallableType](CallableType.md)
-- [Circuit](Circuit.md)
+- [ShortCircuit](ShortCircuit.md)

docs/validators/Lazy.md

@@ -59,7 +59,7 @@ Used when all validators have passed.
 
 - [AllOf](AllOf.md)
 - [AnyOf](AnyOf.md)
-- [Circuit](Circuit.md)
 - [Not](Not.md)
 - [OneOf](OneOf.md)
+- [ShortCircuit](ShortCircuit.md)
 - [When](When.md)

docs/validators/NoneOf.md

@@ -73,6 +73,6 @@ Used when more than one validator has passed.
 
 - [AllOf](AllOf.md)
 - [AnyOf](AnyOf.md)
-- [Circuit](Circuit.md)
 - [NoneOf](NoneOf.md)
+- [ShortCircuit](ShortCircuit.md)
 - [When](When.md)