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][] - [Circuit][] - [NoneOf][] - [OneOf][] - [ShortCircuit][]
 
-**Conditions**: [Circuit][] - [Not][] - [When][]
+**Conditions**: [Circuit][] - [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][] - [Circuit][] - [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][]
 
@@ -186,6 +186,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]);`
@@ -342,6 +343,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/Lazy.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/NoneOf.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/OneOf.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)

docs/validators/ShortCircuit.md

@@ -0,0 +1,79 @@
+<!--
+SPDX-FileCopyrightText: (c) Respect Project Contributors
+SPDX-License-Identifier: MIT
+-->
+
+# ShortCircuit
+
+- `ShortCircuit()`
+- `ShortCircuit(Validator ...$validators)`
+
+Validates the input against a series of validators, stopping at the first failure.
+
+Like PHP's `&&` operator, it uses short-circuit evaluation: once the outcome is determined, remaining validators are
+skipped. Unlike [AllOf](AllOf.md), which evaluates all validators and collects all failures, `ShortCircuit` returns
+immediately.
+
+```php
+v::shortCircuit(v::intVal(), v::positive())->assert(15);
+// Validation passes successfully
+```
+
+This is useful when:
+
+- You want only the first error message instead of all of them
+- Later validators depend on earlier ones passing (e.g., checking a format before checking a value)
+- You want to avoid unnecessary validation work
+
+This validator is particularly useful in combination with [Lazy](Lazy.md) when later validations depend on earlier
+results. For example, validating a subdivision code that depends on a valid country code:
+
+```php
+$validator = v::shortCircuit(
+    v::key('countryCode', v::countryCode()),
+    v::lazy(static 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' => 'ZZ']);
+// → `.subdivisionCode` must be a subdivision code of United States
+
+$validator->assert(['countryCode' => 'US', 'subdivisionCode' => 'CA']);
+// Validation passes successfully
+```
+
+Because [SubdivisionCode](SubdivisionCode.md) requires a valid country code, it only makes sense to validate the
+subdivision after the country code passes. You could achieve this with [When](When.md), but you would have to repeat
+`v::key('countryCode', v::countryCode())` twice.
+
+## Templates
+
+This validator does not have templates of its own. It returns the result of the first failing validator, or the result
+of the last validator when all pass.
+
+## Categorization
+
+- Composite
+- Conditions
+- Nesting
+
+## Changelog
+
+| Version | Description |
+| ------: | :---------- |
+|   3.0.0 | Created     |
+
+## See Also
+
+- [AllOf](AllOf.md)
+- [AnyOf](AnyOf.md)
+- [Lazy](Lazy.md)
+- [NoneOf](NoneOf.md)
+- [OneOf](OneOf.md)
+- [SubdivisionCode](SubdivisionCode.md)
+- [When](When.md)