diff --git a/bin/console b/bin/console
index 8cf929b2..0936e803 100755
--- a/bin/console
+++ b/bin/console
@@ -17,6 +17,7 @@ use Respect\Dev\Commands\UpdateDomainToplevelCommand;
use Respect\Dev\Commands\UpdatePostalCodesCommand;
use Respect\Dev\Markdown\CompositeLinter;
use Respect\Dev\Markdown\Differ as MarkdownDiffer;
+use Respect\Dev\Markdown\Linters\AssertionMessageLinter;
use Respect\Dev\Markdown\Linters\ValidatorHeaderLinter;
use Respect\Dev\Markdown\Linters\ValidatorIndexLinter;
use Respect\Dev\Markdown\Linters\ValidatorRelatedLinter;
@@ -31,6 +32,7 @@ return (static function () {
$application = new Application('Respect/Validation', '3.0');
$application->addCommand(new CreateMixinCommand());
$application->addCommand(new DocsLintCommand($differ, new CompositeLinter(
+ new AssertionMessageLinter(),
new ValidatorHeaderLinter(),
new ValidatorIndexLinter(),
new ValidatorRelatedLinter(),
diff --git a/docs/concrete-api.md b/docs/concrete-api.md
index 051e089e..1170e235 100644
--- a/docs/concrete-api.md
+++ b/docs/concrete-api.md
@@ -1,7 +1,7 @@
# Concrete API
There are many micro-frameworks that rely on magic methods. We don't. In this
-document we're gonna explore the Respect\Validation API without fluent interfaces
+document we're going to explore the Respect\Validation API without fluent interfaces
or magic methods. We'll use a traditional dependency injection approach.
```php
diff --git a/docs/custom-validators.md b/docs/custom-validators.md
index 02edce8d..b3903d47 100644
--- a/docs/custom-validators.md
+++ b/docs/custom-validators.md
@@ -27,7 +27,7 @@ final class Something extends Simple
}
```
-The `'{{subject}} is not something` message would be used then you call the validator
+The `'{{subject}} is not something` message would be used when you call the validator
with the `not()`.
All classes in Validation are created by the `Factory` class. If you want
diff --git a/docs/validators/All.md b/docs/validators/All.md
index 6d77c7a3..2349780f 100644
--- a/docs/validators/All.md
+++ b/docs/validators/All.md
@@ -5,8 +5,11 @@
Validates all items of the input against a given validator.
```php
-v::all(v::intType())->isValid([1, 2, 3]); // true
-v::all(v::intType())->isValid([1, 2, '3']); // false
+v::all(v::intType())->assert([1, 2, 3]);
+// Validation passes successfully
+
+v::all(v::intType())->assert([1, 2, '3']);
+// → Every item in `[1, 2, "3"]` must be an integer
```
This validator is similar to [Each](Each.md), but as opposed to the former, it displays a single message when asserting an input.
@@ -30,10 +33,10 @@ The template serves as a prefix to the template of the inner validator.
```php
v::all(v::floatType())->assert([1.5, 2]);
-// Message: Every item in `[1.5, 2]` must be float
+// → Every item in `[1.5, 2]` must be float
v::not(v::all(v::intType()))->assert([1, 2, -3]);
-// Message: Every item in `[1, 2, -3]` must not be an integer
+// → Every item in `[1, 2, -3]` must not be an integer
```
## Categorization
diff --git a/docs/validators/AllOf.md b/docs/validators/AllOf.md
index e1d6c9f9..5977ebbd 100644
--- a/docs/validators/AllOf.md
+++ b/docs/validators/AllOf.md
@@ -6,7 +6,8 @@
Will validate if all inner validators validates.
```php
-v::allOf(v::intVal(), v::positive())->isValid(15); // true
+v::allOf(v::intVal(), v::positive())->assert(15);
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Alnum.md b/docs/validators/Alnum.md
index acb01fd2..fc505608 100644
--- a/docs/validators/Alnum.md
+++ b/docs/validators/Alnum.md
@@ -9,18 +9,28 @@ Alphanumeric is a combination of alphabetic (a-z and A-Z) and numeric (0-9)
characters.
```php
-v::alnum()->isValid('foo 123'); // false
-v::alnum(' ')->isValid('foo 123'); // true
-v::alnum()->isValid('100%'); // false
-v::alnum('%')->isValid('100%'); // true
-v::alnum('%', ',')->isValid('10,5%'); // true
+v::alnum()->assert('foo 123');
+// → "foo 123" must contain only letters (a-z) and digits (0-9)
+
+v::alnum(' ')->assert('foo 123');
+// Validation passes successfully
+
+v::alnum()->assert('100%');
+// → "100%" must contain only letters (a-z) and digits (0-9)
+
+v::alnum('%')->assert('100%');
+// Validation passes successfully
+
+v::alnum('%', ',')->assert('10,5%');
+// Validation passes successfully
```
You can restrict case using the [Lowercase](Lowercase.md) and
[Uppercase](Uppercase.md) validators.
```php
-v::alnum()->uppercase()->isValid('example'); // false
+v::alnum()->uppercase()->assert('example');
+// → "example" must contain only uppercase letters
```
Message template for this validator includes `{{additionalChars}}` as the string
diff --git a/docs/validators/Alpha.md b/docs/validators/Alpha.md
index eac85baf..2daa4a7f 100644
--- a/docs/validators/Alpha.md
+++ b/docs/validators/Alpha.md
@@ -7,18 +7,28 @@ Validates whether the input contains only alphabetic characters. This is similar
to [Alnum](Alnum.md), but it does not allow numbers.
```php
-v::alpha()->isValid('some name'); // false
-v::alpha(' ')->isValid('some name'); // true
-v::alpha()->isValid('Cedric-Fabian'); // false
-v::alpha('-')->isValid('Cedric-Fabian'); // true
-v::alpha('-', '\'')->isValid('\'s-Gravenhage'); // true
+v::alpha()->assert('some name');
+// → "some name" must contain only letters (a-z)
+
+v::alpha(' ')->assert('some name');
+// Validation passes successfully
+
+v::alpha()->assert('Cedric-Fabian');
+// → "Cedric-Fabian" must contain only letters (a-z)
+
+v::alpha('-')->assert('Cedric-Fabian');
+// Validation passes successfully
+
+v::alpha('-', '\'')->assert('\'s-Gravenhage');
+// Validation passes successfully
```
You can restrict case using the [Lowercase](Lowercase.md) and
[Uppercase](Uppercase.md) validators.
```php
-v::alpha()->uppercase()->isValid('example'); // false
+v::alpha()->uppercase()->assert('example');
+// → "example" must contain only uppercase letters
```
## Templates
diff --git a/docs/validators/AlwaysInvalid.md b/docs/validators/AlwaysInvalid.md
index c7d23def..3db3a971 100644
--- a/docs/validators/AlwaysInvalid.md
+++ b/docs/validators/AlwaysInvalid.md
@@ -5,7 +5,8 @@
Validates any input as invalid.
```php
-v::alwaysInvalid()->isValid('whatever'); // false
+v::alwaysInvalid()->assert('whatever');
+// → "whatever" must be valid
```
## Templates
diff --git a/docs/validators/AlwaysValid.md b/docs/validators/AlwaysValid.md
index 2cde9f20..54fc8da5 100644
--- a/docs/validators/AlwaysValid.md
+++ b/docs/validators/AlwaysValid.md
@@ -5,7 +5,8 @@
Validates any input as valid.
```php
-v::alwaysValid()->isValid('whatever'); // true
+v::alwaysValid()->assert('whatever');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/AnyOf.md b/docs/validators/AnyOf.md
index 0431030b..5d0dc62d 100644
--- a/docs/validators/AnyOf.md
+++ b/docs/validators/AnyOf.md
@@ -6,7 +6,8 @@
This is a group validator that acts as an OR operator.
```php
-v::anyOf(v::intVal(), v::floatVal())->isValid(15.5); // true
+v::anyOf(v::intVal(), v::floatVal())->assert(15.5);
+// Validation passes successfully
```
In the sample above, `IntVal()` doesn't validates, but `FloatVal()` validates,
diff --git a/docs/validators/ArrayType.md b/docs/validators/ArrayType.md
index d377b31f..d6748b44 100644
--- a/docs/validators/ArrayType.md
+++ b/docs/validators/ArrayType.md
@@ -5,9 +5,14 @@
Validates whether the type of an input is array.
```php
-v::arrayType()->isValid([]); // true
-v::arrayType()->isValid([1, 2, 3]); // true
-v::arrayType()->isValid(new ArrayObject()); // false
+v::arrayType()->assert([]);
+// Validation passes successfully
+
+v::arrayType()->assert([1, 2, 3]);
+// Validation passes successfully
+
+v::arrayType()->assert(new ArrayObject());
+// → `ArrayObject { getArrayCopy() => [] }` must be an array
```
## Templates
@@ -55,5 +60,4 @@ See also:
- [ResourceType](ResourceType.md)
- [StringType](StringType.md)
- [Subset](Subset.md)
-- [Type](Type.md)
- [Unique](Unique.md)
diff --git a/docs/validators/ArrayVal.md b/docs/validators/ArrayVal.md
index 2d13d2e8..75cadbbf 100644
--- a/docs/validators/ArrayVal.md
+++ b/docs/validators/ArrayVal.md
@@ -6,9 +6,14 @@ Validates if the input is an array or if the input can be used as an array
(instance of `ArrayAccess` or `SimpleXMLElement`).
```php
-v::arrayVal()->isValid([]); // true
-v::arrayVal()->isValid(new ArrayObject); // true
-v::arrayVal()->isValid(new SimpleXMLElement('')); // true
+v::arrayVal()->assert([]);
+// Validation passes successfully
+
+v::arrayVal()->assert(new ArrayObject);
+// Validation passes successfully
+
+v::arrayVal()->assert(new SimpleXMLElement(''));
+// Validation passes successfully
```
## Templates
@@ -55,5 +60,4 @@ See also:
- [ScalarVal](ScalarVal.md)
- [Sorted](Sorted.md)
- [Subset](Subset.md)
-- [Type](Type.md)
- [Unique](Unique.md)
diff --git a/docs/validators/Attributes.md b/docs/validators/Attributes.md
index 41cf3b40..ced60293 100644
--- a/docs/validators/Attributes.md
+++ b/docs/validators/Attributes.md
@@ -19,7 +19,6 @@ final class Person
#[Validator\Not(new Validator\Undef())]
public string $name,
#[Validator\Date('Y-m-d')]
- #[Validator\DateTimeDiff('years', new Validator\LessThanOrEqual(25))]
public string $birthdate,
#[Validator\Email]
public ?string $email = null,
@@ -34,38 +33,34 @@ Here is how you can validate the attributes of the object:
```php
v::attributes()->assert(new Person('John Doe', '2020-06-23', 'john.doe@gmail.com'));
-// No exception
+// Validation passes successfully
v::attributes()->assert(new Person('John Doe', '2020-06-23', 'john.doe@gmail.com', '+12024561111'));
-// No exception
+// Validation passes successfully
v::attributes()->assert(new Person('', '2020-06-23', 'john.doe@gmail.com', '+12024561111'));
-// Message: `.name` must not be empty
+// → `.name` must be defined
v::attributes()->assert(new Person('John Doe', 'not a date', 'john.doe@gmail.com', '+12024561111'));
-// Message: `.birthdate` must be a valid date in the format "2005-12-30"
+// → `.birthdate` must be a valid date in the format "2005-12-30"
v::attributes()->assert(new Person('John Doe', '2020-06-23', 'not an email', '+12024561111'));
-// Message: `.email` must be a valid email address or must be null
+// → `.email` must be a valid email address or must be null
v::attributes()->assert(new Person('John Doe', '2020-06-23', 'john.doe@gmail.com', 'not a phone number'));
-// Message: `.phone` must be a valid telephone number or must be null
+// → `.phone` must be a valid telephone number or must be null
v::attributes()->assert(new Person('John Doe', '2020-06-23'));
-// Full message:
-// - `Person { +$name="John Doe" +$birthdate="2020-06-23" +$email=null +$phone=null +$address=null }` must pass at least one of the rules
-// - `.email` must be defined
-// - `.phone` must be defined
+// → - `Person { +$name="John Doe" +$birthdate="2020-06-23" +$email=null +$phone=null }` must pass at least one of the rules
+// → - `.email` must be defined
+// → - `.phone` must be defined
v::attributes()->assert(new Person('', 'not a date', 'not an email', 'not a phone number'));
-// Full message:
-// - `Person { +$name="" +$birthdate="not a date" +$email="not an email" +$phone="not a phone number" +$address=null }` must pass the rules
-// - `.name` must not be empty
-// - `.birthdate` must pass all the rules
-// - `.birthdate` must be a valid date in the format "2005-12-30"
-// - For comparison with now, `.birthdate` must be a valid datetime
-// - `.email` must be a valid email address or must be null
-// - `.phone` must be a valid telephone number or must be null
+// → - `Person { +$name="" +$birthdate="not a date" +$email="not an email" +$phone="not a phone number" }` must pass the rules
+// → - `.name` must be defined
+// → - `.birthdate` must be a valid date in the format "2005-12-30"
+// → - `.email` must be a valid email address or must be null
+// → - `.phone` must be a valid telephone number or must be null
```
## Caveats
diff --git a/docs/validators/Base.md b/docs/validators/Base.md
index a020fff4..f858b94a 100644
--- a/docs/validators/Base.md
+++ b/docs/validators/Base.md
@@ -6,11 +6,20 @@
Validate numbers in any base, even with non regular bases.
```php
-v::base(2)->isValid('011010001'); // true
-v::base(3)->isValid('0120122001'); // true
-v::base(8)->isValid('01234567520'); // true
-v::base(16)->isValid('012a34f5675c20d'); // true
-v::base(2)->isValid('0120122001'); // false
+v::base(2)->assert('011010001');
+// Validation passes successfully
+
+v::base(3)->assert('0120122001');
+// Validation passes successfully
+
+v::base(8)->assert('01234567520');
+// Validation passes successfully
+
+v::base(16)->assert('012a34f5675c20d');
+// Validation passes successfully
+
+v::base(2)->assert('0120122001');
+// → "0120122001" must be a number in base 2
```
## Templates
diff --git a/docs/validators/Base64.md b/docs/validators/Base64.md
index be97aad7..12808176 100644
--- a/docs/validators/Base64.md
+++ b/docs/validators/Base64.md
@@ -5,8 +5,11 @@
Validate if a string is Base64-encoded.
```php
-v::base64()->isValid('cmVzcGVjdCE='); // true
-v::base64()->isValid('respect!'); // false
+v::base64()->assert('cmVzcGVjdCE=');
+// Validation passes successfully
+
+v::base64()->assert('respect!');
+// → "respect!" must be a base64 encoded string
```
## Templates
diff --git a/docs/validators/Between.md b/docs/validators/Between.md
index e18ad026..4536e2da 100644
--- a/docs/validators/Between.md
+++ b/docs/validators/Between.md
@@ -5,9 +5,14 @@
Validates whether the input is between two other values.
```php
-v::intVal()->between(10, 20)->isValid(10); // true
-v::intVal()->between(10, 20)->isValid(15); // true
-v::intVal()->between(10, 20)->isValid(20); // true
+v::intVal()->between(10, 20)->assert(10);
+// Validation passes successfully
+
+v::intVal()->between(10, 20)->assert(15);
+// Validation passes successfully
+
+v::intVal()->between(10, 20)->assert(20);
+// Validation passes successfully
```
Validation makes comparison easier, check out our supported
diff --git a/docs/validators/BetweenExclusive.md b/docs/validators/BetweenExclusive.md
index f2deacc0..a22ef6d5 100644
--- a/docs/validators/BetweenExclusive.md
+++ b/docs/validators/BetweenExclusive.md
@@ -5,12 +5,20 @@
Validates whether the input is between two other values, exclusively.
```php
-v::betweenExclusive(10, 20)->isValid(10); // true
-v::betweenExclusive('a', 'e')->isValid('c'); // true
-v::betweenExclusive(new DateTime('yesterday'), new DateTime('tomorrow'))->isValid(new DateTime('today')); // true
+v::betweenExclusive(10, 20)->assert(10);
+// → 10 must be greater than 10 and less than 20
-v::betweenExclusive(0, 100)->isValid(100); // false
-v::betweenExclusive('a', 'z')->isValid('a'); // false
+v::betweenExclusive('a', 'e')->assert('c');
+// Validation passes successfully
+
+v::betweenExclusive(new DateTime('yesterday'), new DateTime('tomorrow'))->assert(new DateTime('today'));
+// Validation passes successfully
+
+v::betweenExclusive(0, 100)->assert(100);
+// → 100 must be greater than 0 and less than 100
+
+v::betweenExclusive('a', 'z')->assert('a');
+// → "a" must be greater than "a" and less than "z"
```
Validation makes comparison easier, check out our supported [comparable values](../comparable-values.md).
diff --git a/docs/validators/Blank.md b/docs/validators/Blank.md
index b8f8b885..8f9dc214 100644
--- a/docs/validators/Blank.md
+++ b/docs/validators/Blank.md
@@ -7,22 +7,20 @@ Validates if the given input is a blank value (`null`, zeros, empty strings or e
We recommend you to check [Comparing empty values](../comparing-empty-values.md) for more details.
```php
-v::blank()->isValid(null); // true
-v::blank()->isValid(''); // true
-v::blank()->isValid([]); // true
-v::blank()->isValid(' '); // true
-v::blank()->isValid(0); // true
-v::blank()->isValid('0'); // true
-v::blank()->isValid(0); // true
-v::blank()->isValid('0.0'); // true
-v::blank()->isValid(false); // true
-v::blank()->isValid(['']); // true
-v::blank()->isValid([' ']); // true
-v::blank()->isValid([0]); // true
-v::blank()->isValid(['0']); // true
-v::blank()->isValid([false]); // true
-v::blank()->isValid([[''], [0]]); // true
-v::blank()->isValid(new stdClass()); // true
+v::blank()->assert(' ');
+// Validation passes successfully
+
+v::blank()->assert(0);
+// Validation passes successfully
+
+v::blank()->assert(false);
+// Validation passes successfully
+
+v::blank()->assert(['', ' ', '0.0', []]);
+// Validation passes successfully
+
+v::blank()->assert(new stdClass());
+// Validation passes successfully
```
It's similar to [Falsy](Falsy.md), but way stricter.
diff --git a/docs/validators/BoolType.md b/docs/validators/BoolType.md
index fbb72312..44bf51a5 100644
--- a/docs/validators/BoolType.md
+++ b/docs/validators/BoolType.md
@@ -5,8 +5,11 @@
Validates whether the type of the input is [boolean](http://php.net/types.boolean).
```php
-v::boolType()->isValid(true); // true
-v::boolType()->isValid(false); // true
+v::boolType()->assert(true);
+// Validation passes successfully
+
+v::boolType()->assert(false);
+// Validation passes successfully
```
## Templates
@@ -53,4 +56,3 @@ See also:
- [StringType](StringType.md)
- [StringVal](StringVal.md)
- [TrueVal](TrueVal.md)
-- [Type](Type.md)
diff --git a/docs/validators/BoolVal.md b/docs/validators/BoolVal.md
index cb74873a..8000e8bb 100644
--- a/docs/validators/BoolVal.md
+++ b/docs/validators/BoolVal.md
@@ -5,12 +5,23 @@
Validates if the input results in a boolean value:
```php
-v::boolVal()->isValid('on'); // true
-v::boolVal()->isValid('off'); // true
-v::boolVal()->isValid('yes'); // true
-v::boolVal()->isValid('no'); // true
-v::boolVal()->isValid(1); // true
-v::boolVal()->isValid(0); // true
+v::boolVal()->assert('on');
+// Validation passes successfully
+
+v::boolVal()->assert('off');
+// Validation passes successfully
+
+v::boolVal()->assert('yes');
+// Validation passes successfully
+
+v::boolVal()->assert('no');
+// Validation passes successfully
+
+v::boolVal()->assert(1);
+// Validation passes successfully
+
+v::boolVal()->assert(0);
+// Validation passes successfully
```
## Templates
@@ -53,4 +64,3 @@ See also:
- [ResourceType](ResourceType.md)
- [StringType](StringType.md)
- [TrueVal](TrueVal.md)
-- [Type](Type.md)
diff --git a/docs/validators/Bsn.md b/docs/validators/Bsn.md
index fc588ac8..79de07ef 100644
--- a/docs/validators/Bsn.md
+++ b/docs/validators/Bsn.md
@@ -5,7 +5,8 @@
Validates a Dutch citizen service number ([BSN](https://nl.wikipedia.org/wiki/Burgerservicenummer)).
```php
-v::bsn()->isValid('612890053'); // true
+v::bsn()->assert('612890053');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Call.md b/docs/validators/Call.md
index ad157602..39bee4bb 100644
--- a/docs/validators/Call.md
+++ b/docs/validators/Call.md
@@ -38,7 +38,8 @@ v::call(
->key('host', v::domain())
->key('path', v::stringType())
->key('query', v::notBlank())
-)->isValid($url);
+)->assert($url);
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/CallableType.md b/docs/validators/CallableType.md
index e8d3c7ac..1ad50c83 100644
--- a/docs/validators/CallableType.md
+++ b/docs/validators/CallableType.md
@@ -5,9 +5,14 @@
Validates whether the pseudo-type of the input is [callable](http://php.net/types.callable).
```php
-v::callableType()->isValid(function () {}); // true
-v::callableType()->isValid('trim'); // true
-v::callableType()->isValid([new DateTime(), 'format']); // true
+v::callableType()->assert(function () {});
+// Validation passes successfully
+
+v::callableType()->assert('trim');
+// Validation passes successfully
+
+v::callableType()->assert([new DateTime(), 'format']);
+// Validation passes successfully
```
## Templates
@@ -53,4 +58,3 @@ See also:
- [ResourceType](ResourceType.md)
- [StringType](StringType.md)
- [StringVal](StringVal.md)
-- [Type](Type.md)
diff --git a/docs/validators/Callback.md b/docs/validators/Callback.md
index 1aa42bfa..bc765cdc 100644
--- a/docs/validators/Callback.md
+++ b/docs/validators/Callback.md
@@ -7,10 +7,9 @@ Validates the input using the return of a given callable.
```php
v::callback(
- function (int $input): bool {
- return $input + ($input / 2) == 15;
- }
-)->isValid(10); // true
+ fn (int $input): bool => $input + ($input / 2) == 15,
+)->assert(10);
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Charset.md b/docs/validators/Charset.md
index 73d16521..e25a55f3 100644
--- a/docs/validators/Charset.md
+++ b/docs/validators/Charset.md
@@ -6,9 +6,14 @@
Validates if a string is in a specific charset.
```php
-v::charset('ASCII')->isValid('açúcar'); // false
-v::charset('ASCII')->isValid('sugar'); //true
-v::charset('ISO-8859-1', 'EUC-JP')->isValid('日本国'); // true
+v::charset('ASCII')->assert('açúcar');
+// → "açúcar" must only contain characters from the `["ASCII"]` charset
+
+v::charset('ASCII')->assert('sugar');
+// Validation passes successfully
+
+v::charset('ISO-8859-1', 'EUC-JP')->assert('日本国');
+// Validation passes successfully
```
The array format is a logic OR, not AND.
diff --git a/docs/validators/Circuit.md b/docs/validators/Circuit.md
index 5cc2a308..d0153029 100644
--- a/docs/validators/Circuit.md
+++ b/docs/validators/Circuit.md
@@ -11,10 +11,22 @@ This validator can be helpful in combinations with [Lazy](Lazy.md). An excellent
country code and a subdivision code.
```php
-v::circuit(
+$validator = v::circuit(
v::key('countryCode', v::countryCode()),
v::lazy(static fn($input) => v::key('subdivisionCode', v::subdivisionCode($input['countryCode']))),
-)->isValid($_POST);
+);
+
+$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
```
You need a valid country code to create a [SubdivisionCode](SubdivisionCode.md), so it makes sense only to validate the
diff --git a/docs/validators/Cnh.md b/docs/validators/Cnh.md
index 3021b13c..db68e7c3 100644
--- a/docs/validators/Cnh.md
+++ b/docs/validators/Cnh.md
@@ -5,7 +5,8 @@
Validates a Brazilian driver's license.
```php
-v::cnh()->isValid('02650306461'); // true
+v::cnh()->assert('02650306461');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Consonant.md b/docs/validators/Consonant.md
index 77c736d2..12672c4b 100644
--- a/docs/validators/Consonant.md
+++ b/docs/validators/Consonant.md
@@ -6,7 +6,8 @@
Validates if the input contains only consonants.
```php
-v::consonant()->isValid('xkcd'); // true
+v::consonant()->assert('xkcd');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Contains.md b/docs/validators/Contains.md
index 68c3197f..2be52deb 100644
--- a/docs/validators/Contains.md
+++ b/docs/validators/Contains.md
@@ -8,13 +8,15 @@ Validates if the input contains some value.
For strings:
```php
-v::contains('ipsum')->isValid('lorem ipsum'); // true
+v::contains('ipsum')->assert('lorem ipsum');
+// Validation passes successfully
```
For arrays:
```php
-v::contains('ipsum')->isValid(['ipsum', 'lorem']); // true
+v::contains('ipsum')->assert(['ipsum', 'lorem']);
+// Validation passes successfully
```
A second parameter may be passed for identical comparison instead
diff --git a/docs/validators/ContainsAny.md b/docs/validators/ContainsAny.md
index 2b8b423a..7022cd20 100644
--- a/docs/validators/ContainsAny.md
+++ b/docs/validators/ContainsAny.md
@@ -8,13 +8,15 @@ Validates if the input contains at least one of defined values
For strings (comparing is case insensitive):
```php
-v::containsAny(['lorem', 'dolor'])->isValid('lorem ipsum'); // true
+v::containsAny(['lorem', 'dolor'])->assert('lorem ipsum');
+// Validation passes successfully
```
For arrays (comparing is case sensitive to respect "contains" behavior):
```php
-v::containsAny(['lorem', 'dolor'])->isValid(['ipsum', 'lorem']); // true
+v::containsAny(['lorem', 'dolor'])->assert(['ipsum', 'lorem']);
+// Validation passes successfully
```
A second parameter may be passed for identical comparison instead
diff --git a/docs/validators/Control.md b/docs/validators/Control.md
index 8df46f1e..342172b9 100644
--- a/docs/validators/Control.md
+++ b/docs/validators/Control.md
@@ -7,7 +7,8 @@ Validates if all of the characters in the provided string, are control
characters.
```php
-v::control()->isValid("\n\r\t"); // true
+v::control()->assert("\n\r\t");
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Countable.md b/docs/validators/Countable.md
index c7728c39..c0a55948 100644
--- a/docs/validators/Countable.md
+++ b/docs/validators/Countable.md
@@ -6,9 +6,14 @@ Validates if the input is countable, in other words, if you're allowed to use
[count()](http://php.net/count) function on it.
```php
-v::countable()->isValid([]); // true
-v::countable()->isValid(new ArrayObject()); // true
-v::countable()->isValid('string'); // false
+v::countable()->assert([]);
+// Validation passes successfully
+
+v::countable()->assert(new ArrayObject());
+// Validation passes successfully
+
+v::countable()->assert('string');
+// → "string" must be a countable value
```
## Templates
diff --git a/docs/validators/CountryCode.md b/docs/validators/CountryCode.md
index 85d806a6..e9e46c16 100644
--- a/docs/validators/CountryCode.md
+++ b/docs/validators/CountryCode.md
@@ -8,11 +8,17 @@ Validates whether the input is a country code in [ISO 3166-1][] standard.
**This validator requires [sokil/php-isocodes][] and [sokil/php-isocodes-db-only][] to be installed.**
```php
-v::countryCode()->isValid('BR'); // true
+v::countryCode()->assert('BR');
+// Validation passes successfully
-v::countryCode('alpha-2')->isValid('NL'); // true
-v::countryCode('alpha-3')->isValid('USA'); // true
-v::countryCode('numeric')->isValid('504'); // true
+v::countryCode('alpha-2')->assert('NL');
+// Validation passes successfully
+
+v::countryCode('alpha-3')->assert('USA');
+// Validation passes successfully
+
+v::countryCode('numeric')->assert('504');
+// Validation passes successfully
```
This validator supports the three sets of country codes:
diff --git a/docs/validators/Cpf.md b/docs/validators/Cpf.md
index ff4d25f0..69bccb13 100644
--- a/docs/validators/Cpf.md
+++ b/docs/validators/Cpf.md
@@ -5,20 +5,23 @@
Validates a Brazillian CPF number.
```php
-v::cpf()->isValid('11598647644'); // true
+v::cpf()->assert('11598647644');
+// Validation passes successfully
```
It ignores any non-digit char:
```php
-v::cpf()->isValid('693.319.118-40'); // true
+v::cpf()->assert('693.319.118-40');
+// Validation passes successfully
```
If you need to validate digits only, add `->digit()` to
the chain:
```php
-v::digit()->cpf()->isValid('11598647644'); // true
+v::digit()->cpf()->assert('11598647644');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/CreditCard.md b/docs/validators/CreditCard.md
index 4aa39ab9..9aeab3f3 100644
--- a/docs/validators/CreditCard.md
+++ b/docs/validators/CreditCard.md
@@ -6,17 +6,35 @@
Validates a credit card number.
```php
-v::creditCard()->isValid('5376 7473 9720 8720'); // true
-v::creditCard()->isValid('5376-7473-9720-8720'); // true
-v::creditCard()->isValid('5376.7473.9720.8720'); // true
+v::creditCard()->assert('5376 7473 9720 8720');
+// Validation passes successfully
-v::creditCard('American_Express')->isValid('340316193809364'); // true
-v::creditCard('Diners_Club')->isValid('30351042633884'); // true
-v::creditCard('Discover')->isValid('6011000990139424'); // true
-v::creditCard('JCB')->isValid('3566002020360505'); // true
-v::creditCard('Mastercard')->isValid('5376747397208720'); // true
-v::creditCard('Visa')->isValid('4024007153361885'); // true
-v::creaditCard('RuPay')->isValid('6062973831636410') // true
+v::creditCard()->assert('5376-7473-9720-8720');
+// Validation passes successfully
+
+v::creditCard()->assert('5376.7473.9720.8720');
+// Validation passes successfully
+
+v::creditCard('American Express')->assert('340316193809364');
+// Validation passes successfully
+
+v::creditCard('Diners Club')->assert('30351042633884');
+// Validation passes successfully
+
+v::creditCard('Discover')->assert('6011000990139424');
+// Validation passes successfully
+
+v::creditCard('JCB')->assert('3566002020360505');
+// Validation passes successfully
+
+v::creditCard('MasterCard')->assert('5376747397208720');
+// Validation passes successfully
+
+v::creditCard('Visa')->assert('4024007153361885');
+// Validation passes successfully
+
+v::creditCard('RuPay')->assert('6062973831636410');
+// Validation passes successfully
```
The current supported brands are:
@@ -33,7 +51,8 @@ It ignores any non-numeric characters, use [Digit](Digit.md),
[Spaced](Spaced.md), or [Regex](Regex.md) when appropriate.
```php
-v::digit()->creditCard()->isValid('5376747397208720'); // true
+v::digit()->creditCard()->assert('5376747397208720');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/CurrencyCode.md b/docs/validators/CurrencyCode.md
index 05500437..5724b68e 100644
--- a/docs/validators/CurrencyCode.md
+++ b/docs/validators/CurrencyCode.md
@@ -8,7 +8,8 @@ Validates an [ISO 4217][] currency code.
**This validator requires [sokil/php-isocodes][] and [sokil/php-isocodes-db-only][] to be installed.**
```php
-v::currencyCode()->isValid('GBP'); // true
+v::currencyCode()->assert('GBP');
+// Validation passes successfully
```
This validator supports the two [ISO 4217][] sets:
diff --git a/docs/validators/Date.md b/docs/validators/Date.md
index 34ebfd04..d5fb4fed 100644
--- a/docs/validators/Date.md
+++ b/docs/validators/Date.md
@@ -21,12 +21,23 @@ PHP's [date()](http://php.net/date) function, but only those are allowed:
When a `$format` is not given its default value is `Y-m-d`.
```php
-v::date()->isValid('2017-12-31'); // true
-v::date()->isValid('2020-02-29'); // true
-v::date()->isValid('2019-02-29'); // false
-v::date('m/d/y')->isValid('12/31/17'); // true
-v::date('F jS, Y')->isValid('May 1st, 2017'); // true
-v::date('Ydm')->isValid(20173112); // true
+v::date()->assert('2017-12-31');
+// Validation passes successfully
+
+v::date()->assert('2020-02-29');
+// Validation passes successfully
+
+v::date()->assert('2019-02-29');
+// → "2019-02-29" must be a valid date in the format "2005-12-30"
+
+v::date('m/d/y')->assert('12/31/17');
+// Validation passes successfully
+
+v::date('F jS, Y')->assert('May 1st, 2017');
+// Validation passes successfully
+
+v::date('Ydm')->assert(20173112);
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/DateTime.md b/docs/validators/DateTime.md
index b89c852c..2093cf4e 100644
--- a/docs/validators/DateTime.md
+++ b/docs/validators/DateTime.md
@@ -10,26 +10,32 @@ The `$format` argument should be in accordance to [DateTime::format()][]. See mo
When a `$format` is not given its default value is `Y-m-d H:i:s`.
```php
-v::dateTime()->isValid('2009-01-01'); // true
+v::dateTime()->assert('2009-01-01');
+// Validation passes successfully
```
Also accepts [strtotime()](http://php.net/strtotime) values:
```php
-v::dateTime()->isValid('now'); // true
+v::dateTime()->assert('now');
+// Validation passes successfully
```
And `DateTimeInterface` instances:
```php
-v::dateTime()->isValid(new DateTime()); // true
-v::dateTime()->isValid(new DateTimeImmutable()); // true
+v::dateTime()->assert(new DateTime());
+// Validation passes successfully
+
+v::dateTime()->assert(new DateTimeImmutable());
+// Validation passes successfully
```
You can pass a format when validating strings:
```php
-v::dateTime('Y-m-d')->isValid('01-01-2009'); // false
+v::dateTime('Y-m-d')->assert('01-01-2009');
+// → "01-01-2009" must be a valid date/time in the format "2005-12-30"
```
Format has no effect when validating DateTime instances.
@@ -50,9 +56,11 @@ you desire, and you may want to use [Callback](Callback.md) to create a custom v
$input = '2014-04-12T23:20:50.052Z';
v::callback(fn($input) => is_string($input) && DateTime::createFromFormat(DateTime::RFC3339_EXTENDED, $input))
- ->isValid($input); // true
+ ->assert($input);
+// Validation passes successfully
-v::dateTime(DateTime::RFC3339_EXTENDED)->isValid($input); // false
+v::dateTime(DateTime::RFC3339_EXTENDED)->assert($input);
+// → "2014-04-12T23:20:50.052Z" must be a valid date/time in the format "2005-12-30T01:02:03.000+00:00"
```
## Templates
diff --git a/docs/validators/DateTimeDiff.md b/docs/validators/DateTimeDiff.md
index eeda4cc2..13461fb9 100644
--- a/docs/validators/DateTimeDiff.md
+++ b/docs/validators/DateTimeDiff.md
@@ -10,13 +10,20 @@ The `$format` argument should follow PHP's [date()][] function. When the `$forma
[Supported Date and Time Formats][] by PHP (see [strtotime()][]).
```php
-v::dateTimeDiff('years', v::equals(7))->isValid('7 years ago'); // true
-v::dateTimeDiff('years', v::equals(7))->isValid('7 years ago + 1 minute'); // false
+v::dateTimeDiff('years', v::equals(7))->assert('7 years ago');
+// → The number of years between now and "7 years ago" must be equal to 7
-v::dateTimeDiff('years', v::greaterThan(18), 'd/m/Y')->isValid('09/12/1990'); // true
-v::dateTimeDiff('years', v::greaterThan(18), 'd/m/Y')->isValid('09/12/2023'); // false
+v::dateTimeDiff('years', v::equals(7))->assert('7 years ago + 1 minute');
+// → The number of years between now and "7 years ago + 1 minute" must be equal to 7
-v::dateTimeDiff('months', v::between(1, 18))->isValid('5 months ago'); // true
+v::dateTimeDiff('years', v::greaterThan(18), 'd/m/Y')->assert('09/12/1990');
+// Validation passes successfully
+
+v::dateTimeDiff('years', v::greaterThan(18), 'd/m/Y')->assert('09/12/2023');
+// → The number of years between "01/01/2024" and "09/12/2023" must be greater than 18
+
+v::dateTimeDiff('months', v::between(1, 18))->assert('5 months ago');
+// Validation passes successfully
```
The supported types are:
@@ -70,11 +77,11 @@ Used when the input cannot be parsed with the given format.
The template serves as a prefix to the template of the inner validator.
```php
-v::dateTimeDiff('years', v::equals(2))->assert('1 year ago')
-// The number of years between now and 1 year ago must be equal to 2
+v::dateTimeDiff('years', v::equals(2))->assert('1 year ago');
+// → The number of years between now and "1 year ago" must be equal to 2
-v::not(v::dateTimeDiff('years', v::lessThan(8)))->assert('7 year ago')
-// The number of years between now and 7 year ago must not be less than 8
+v::not(v::dateTimeDiff('years', v::lessThan(8)))->assert('7 year ago');
+// → The number of years between now and "7 year ago" must not be less than 8
```
## Template placeholders
@@ -94,7 +101,7 @@ When using custom templates, the key must be `dateTimeDiff` + name of the valida
v::dateTimeDiff('years', v::equals(2))->assert('1 year ago', [
'dateTimeDiffEquals' => 'Please enter a date that is 2 years ago'
]);
-// Please enter a date that is 2 years ago.
+// → Please enter a date that is 2 years ago
```
## Categorization
diff --git a/docs/validators/Decimal.md b/docs/validators/Decimal.md
index c7188bba..e983f84c 100644
--- a/docs/validators/Decimal.md
+++ b/docs/validators/Decimal.md
@@ -5,10 +5,14 @@
Validates whether the input matches the expected number of decimals.
```php
-v::decimals(2)->isValid('27990.50'); // true
-v::decimals(1)->isValid('27990.50'); // false
-v::decimal(1)->isValid(1.5); // true
+v::decimal(2)->assert('27990.50');
+// Validation passes successfully
+v::decimal(1)->assert('27990.50');
+// → "27990.50" must have 1 decimals
+
+v::decimal(1)->assert(1.5);
+// Validation passes successfully
```
## Known limitations
@@ -17,7 +21,8 @@ When validating float types, it is not possible to determine the amount of
ending zeros and because of that, validations like the ones below will pass.
```php
-v::decimal(1)->isValid(1.50); // true
+v::decimal(1)->assert(1.50);
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Digit.md b/docs/validators/Digit.md
index 5568bea5..d7201557 100644
--- a/docs/validators/Digit.md
+++ b/docs/validators/Digit.md
@@ -6,10 +6,17 @@
Validates whether the input contains only digits.
```php
-v::digit()->isValid('020 612 1851'); // false
-v::digit(' ')->isValid('020 612 1851'); // true
-v::digit()->isValid('172.655.537-21'); // false
-v::digit('.', '-')->isValid('172.655.537-21'); // true
+v::digit()->assert('020 612 1851');
+// → "020 612 1851" must contain only digits (0-9)
+
+v::digit(' ')->assert('020 612 1851');
+// Validation passes successfully
+
+v::digit()->assert('172.655.537-21');
+// → "172.655.537-21" must contain only digits (0-9)
+
+v::digit('.', '-')->assert('172.655.537-21');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Directory.md b/docs/validators/Directory.md
index a442937c..42bb0814 100644
--- a/docs/validators/Directory.md
+++ b/docs/validators/Directory.md
@@ -5,15 +5,21 @@
Validates if the given path is a directory.
```php
-v::directory()->isValid(__DIR__); // true
-v::directory()->isValid(__FILE__); // false
+v::directory()->assert(__DIR__);
+// Validation passes successfully
+
+v::directory()->assert(__FILE__);
+// → "/path/to/file" must be a directory
```
This validator will consider SplFileInfo instances, so you can do something like:
```php
-v::directory()->isValid(new SplFileInfo('library/'));
-v::directory()->isValid(dir('/'));
+v::directory()->assert(new SplFileInfo('library/'));
+// Validation passes successfully
+
+v::directory()->assert(dir('/'));
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Domain.md b/docs/validators/Domain.md
index 749df603..e66533b4 100644
--- a/docs/validators/Domain.md
+++ b/docs/validators/Domain.md
@@ -6,14 +6,16 @@
Validates whether the input is a valid domain name or not.
```php
-v::domain()->isValid('google.com');
+v::domain()->assert('google.com');
+// Validation passes successfully
```
You can skip _top level domain_ (TLD) checks to validate internal
domain names:
```php
-v::domain(false)->isValid('dev.machine.local');
+v::domain(false)->assert('dev.machine.local');
+// Validation passes successfully
```
This is a composite validator, it validates several validators
diff --git a/docs/validators/Each.md b/docs/validators/Each.md
index e2f4b6e7..0ab5375b 100644
--- a/docs/validators/Each.md
+++ b/docs/validators/Each.md
@@ -11,13 +11,15 @@ $releaseDates = [
'relational' => '2011-02-05',
];
-v::each(v::dateTime())->isValid($releaseDates); // true
+v::each(v::dateTime())->assert($releaseDates);
+// Validation passes successfully
```
You can also validate array keys combining this validator with [Call](Call.md):
```php
-v::call('array_keys', v::each(v::stringType()))->isValid($releaseDates); // true
+v::call('array_keys', v::each(v::stringType()))->assert($releaseDates);
+// Validation passes successfully
```
## Note
diff --git a/docs/validators/Email.md b/docs/validators/Email.md
index 7f27e342..918422f0 100644
--- a/docs/validators/Email.md
+++ b/docs/validators/Email.md
@@ -5,7 +5,8 @@
Validates an email address.
```php
-v::email()->isValid('alganet@gmail.com'); // true
+v::email()->assert('alganet@gmail.com');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Emoji.md b/docs/validators/Emoji.md
index 07ddb284..528c9e87 100644
--- a/docs/validators/Emoji.md
+++ b/docs/validators/Emoji.md
@@ -5,16 +5,35 @@
Validates if the input is an emoji or a sequence of emojis.
```php
-v::emoji()->isValid('🍕'); // true
-v::emoji()->isValid('🎈'); // true
-v::emoji()->isValid('⚡'); // true
-v::emoji()->isValid('🌊🌊🌊🌊🌊🏄🌊🌊🌊🏖🌴'); // true
-v::emoji()->isValid('🇧🇷'); // true (country flag)
-v::emoji()->isValid('👨👩👧👦'); // true (ZWJ sequence)
-v::emoji()->isValid('👩🏽'); // true (skin tone modifier)
-v::emoji()->isValid('1️⃣'); // true (keycap sequence)
-v::emoji()->isValid('Hello World'); // false
-v::emoji()->isValid('this is a spark ⚡'); // false (mixed content)
+v::emoji()->assert('🍕');
+// Validation passes successfully
+
+v::emoji()->assert('🎈');
+// Validation passes successfully
+
+v::emoji()->assert('⚡');
+// Validation passes successfully
+
+v::emoji()->assert('🌊🌊🌊🌊🌊🏄🌊🌊🌊🏖🌴');
+// Validation passes successfully
+
+v::emoji()->assert('🇧🇷'); // (Country flags)
+// Validation passes successfully
+
+v::emoji()->assert('👨👩👧👦'); // (ZWJ sequence)
+// Validation passes successfully
+
+v::emoji()->assert('👩🏽'); // (Skin tone modifier)
+// Validation passes successfully
+
+v::emoji()->assert('1️⃣'); // (Keycap sequence)
+// Validation passes successfully
+
+v::emoji()->assert('Hello World');
+// → "Hello World" must be an emoji
+
+v::emoji()->assert('this is a spark ⚡'); // (Mixed content)
+// → "this is a spark ⚡" must be an emoji
```
This validator supports:
diff --git a/docs/validators/EndsWith.md b/docs/validators/EndsWith.md
index d807fd70..df6c859e 100644
--- a/docs/validators/EndsWith.md
+++ b/docs/validators/EndsWith.md
@@ -9,13 +9,15 @@ only if the value is at the end of the input.
For strings:
```php
-v::endsWith('ipsum')->isValid('lorem ipsum'); // true
+v::endsWith('ipsum')->assert('lorem ipsum');
+// Validation passes successfully
```
For arrays:
```php
-v::endsWith('ipsum')->isValid(['lorem', 'ipsum']); // true
+v::endsWith('ipsum')->assert(['lorem', 'ipsum']);
+// Validation passes successfully
```
A second parameter may be passed for identical comparison instead
diff --git a/docs/validators/Equals.md b/docs/validators/Equals.md
index c64057c9..62061a8f 100644
--- a/docs/validators/Equals.md
+++ b/docs/validators/Equals.md
@@ -5,7 +5,8 @@
Validates if the input is equal to some value.
```php
-v::equals('alganet')->isValid('alganet'); // true
+v::equals('alganet')->assert('alganet');
+// Validation passes successfully
```
Message template for this validator includes `{{compareTo}}`.
diff --git a/docs/validators/Equivalent.md b/docs/validators/Equivalent.md
index 3efdc849..edbedd33 100644
--- a/docs/validators/Equivalent.md
+++ b/docs/validators/Equivalent.md
@@ -5,9 +5,14 @@
Validates if the input is equivalent to some value.
```php
-v::equivalent(1)->isValid(true); // true
-v::equivalent('Something')->isValid('someThing'); // true
-v::equivalent(new ArrayObject([1, 2, 3, 4, 5]))->isValid(new ArrayObject([1, 2, 3, 4, 5])); // true
+v::equivalent(1)->assert(true);
+// Validation passes successfully
+
+v::equivalent('Something')->assert('someThing');
+// Validation passes successfully
+
+v::equivalent(new ArrayObject([1, 2, 3, 4, 5]))->assert(new ArrayObject([1, 2, 3, 4, 5]));
+// Validation passes successfully
```
This validator is very similar to [Equals](Equals.md) but it does not make case-sensitive
diff --git a/docs/validators/Even.md b/docs/validators/Even.md
index 76c97443..41113f9c 100644
--- a/docs/validators/Even.md
+++ b/docs/validators/Even.md
@@ -5,7 +5,8 @@
Validates whether the input is an even number or not.
```php
-v::intVal()->even()->isValid(2); // true
+v::intVal()->even()->assert(2);
+// Validation passes successfully
```
Using `int()` before `even()` is a best practice.
diff --git a/docs/validators/Executable.md b/docs/validators/Executable.md
index 3335b54e..5750a1ac 100644
--- a/docs/validators/Executable.md
+++ b/docs/validators/Executable.md
@@ -5,7 +5,11 @@
Validates if a file is an executable.
```php
-v::executable()->isValid('script.sh'); // true
+v::executable()->assert('/path/to/file');
+// → "/path/to/file" must be an executable file
+
+v::executable()->assert('/path/to/executable');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Exists.md b/docs/validators/Exists.md
index fb9a8412..b80997d1 100644
--- a/docs/validators/Exists.md
+++ b/docs/validators/Exists.md
@@ -5,14 +5,18 @@
Validates files or directories.
```php
-v::exists()->isValid(__FILE__); // true
-v::exists()->isValid(__DIR__); // true
+v::exists()->assert(__FILE__);
+// Validation passes successfully
+
+v::exists()->assert(__DIR__);
+// Validation passes successfully
```
This validator will consider SplFileInfo instances, so you can do something like:
```php
-v::exists()->isValid(new SplFileInfo('file.txt'));
+v::exists()->assert(new SplFileInfo('/path/to/file.txt'));
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Extension.md b/docs/validators/Extension.md
index b89de5a7..a2b16938 100644
--- a/docs/validators/Extension.md
+++ b/docs/validators/Extension.md
@@ -5,7 +5,8 @@
Validates if the file extension matches the expected one:
```php
-v::extension('png')->isValid('image.png'); // true
+v::extension('png')->assert('image.png');
+// Validation passes successfully
```
This validator is case-sensitive.
diff --git a/docs/validators/Factor.md b/docs/validators/Factor.md
index 7d0c530d..bdd238d5 100644
--- a/docs/validators/Factor.md
+++ b/docs/validators/Factor.md
@@ -5,9 +5,14 @@
Validates if the input is a factor of the defined dividend.
```php
-v::factor(0)->isValid(5); // true
-v::factor(4)->isValid(2); // true
-v::factor(4)->isValid(3); // false
+v::factor(0)->assert(5);
+// Validation passes successfully
+
+v::factor(4)->assert(2);
+// Validation passes successfully
+
+v::factor(4)->assert(3);
+// → 3 must be a factor of 4
```
## Templates
diff --git a/docs/validators/FalseVal.md b/docs/validators/FalseVal.md
index 3c89c784..47350ac4 100644
--- a/docs/validators/FalseVal.md
+++ b/docs/validators/FalseVal.md
@@ -5,14 +5,29 @@
Validates if a value is considered as `false`.
```php
-v::falseVal()->isValid(false); // true
-v::falseVal()->isValid(0); // true
-v::falseVal()->isValid('0'); // true
-v::falseVal()->isValid('false'); // true
-v::falseVal()->isValid('off'); // true
-v::falseVal()->isValid('no'); // true
-v::falseVal()->isValid('0.5'); // false
-v::falseVal()->isValid('2'); // false
+v::falseVal()->assert(false);
+// Validation passes successfully
+
+v::falseVal()->assert(0);
+// Validation passes successfully
+
+v::falseVal()->assert('0');
+// Validation passes successfully
+
+v::falseVal()->assert('false');
+// Validation passes successfully
+
+v::falseVal()->assert('off');
+// Validation passes successfully
+
+v::falseVal()->assert('no');
+// Validation passes successfully
+
+v::falseVal()->assert('0.5');
+// → "0.5" must evaluate to `false`
+
+v::falseVal()->assert('2');
+// → "2" must evaluate to `false`
```
## Templates
diff --git a/docs/validators/Falsy.md b/docs/validators/Falsy.md
index 485f70d2..ea786523 100644
--- a/docs/validators/Falsy.md
+++ b/docs/validators/Falsy.md
@@ -7,25 +7,29 @@ Validates whether the given input is considered empty or falsy, similar to PHP's
We recommend you to check [Comparing empty values](../comparing-empty-values.md) for more details.
```php
-v::falsy()->isValid(''); // true
+v::falsy()->assert('');
+// Validation passes successfully
```
Null values are empty:
```php
-v::falsy()->isValid(null); // true
+v::falsy()->assert(null);
+// Validation passes successfully
```
Numbers:
```php
-v::falsy()->isValid(0); // true
+v::falsy()->assert(0);
+// Validation passes successfully
```
Empty arrays:
```php
-v::falsy()->isValid([]); // true
+v::falsy()->assert([]);
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Fibonacci.md b/docs/validators/Fibonacci.md
index 305bfeb5..009a43f7 100644
--- a/docs/validators/Fibonacci.md
+++ b/docs/validators/Fibonacci.md
@@ -5,9 +5,14 @@
Validates whether the input follows the Fibonacci integer sequence.
```php
-v::fibonacci()->isValid(1); // true
-v::fibonacci()->isValid('34'); // true
-v::fibonacci()->isValid(6); // false
+v::fibonacci()->assert(1);
+// Validation passes successfully
+
+v::fibonacci()->assert('34');
+// Validation passes successfully
+
+v::fibonacci()->assert(6);
+// → 6 must be a valid Fibonacci number
```
## Templates
diff --git a/docs/validators/File.md b/docs/validators/File.md
index 0dee297e..31a807c2 100644
--- a/docs/validators/File.md
+++ b/docs/validators/File.md
@@ -5,14 +5,18 @@
Validates whether file input is as a regular filename.
```php
-v::file()->isValid(__FILE__); // true
-v::file()->isValid(__DIR__); // false
+v::file()->assert(__FILE__);
+// Validation passes successfully
+
+v::file()->assert(__DIR__);
+// → "/path/to/dir" must be a valid file
```
This validator will consider SplFileInfo instances, so you can do something like:
```php
-v::file()->isValid(new SplFileInfo('file.txt'));
+v::file()->assert(new SplFileInfo('/path/to/file.txt'));
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/FilterVar.md b/docs/validators/FilterVar.md
index 60d74c56..99ec492b 100644
--- a/docs/validators/FilterVar.md
+++ b/docs/validators/FilterVar.md
@@ -6,12 +6,23 @@
Validates the input with the PHP's [filter_var()](http://php.net/filter_var) function.
```php
-v::filterVar(FILTER_VALIDATE_EMAIL)->isValid('bob@example.com'); // true
-v::filterVar(FILTER_VALIDATE_URL)->isValid('http://example.com'); // true
-v::filterVar(FILTER_VALIDATE_URL, FILTER_FLAG_PATH_REQUIRED)->isValid('http://example.com'); // false
-v::filterVar(FILTER_VALIDATE_URL, FILTER_FLAG_PATH_REQUIRED)->isValid('http://example.com/path'); // true
-v::filterVar(FILTER_VALIDATE_DOMAIN, FILTER_FLAG_HOSTNAME)->isValid('webserver.local'); // true
-v::filterVar(FILTER_VALIDATE_DOMAIN, FILTER_FLAG_HOSTNAME)->isValid('@local'); // false
+v::filterVar(FILTER_VALIDATE_EMAIL)->assert('bob@example.com');
+// Validation passes successfully
+
+v::filterVar(FILTER_VALIDATE_URL)->assert('http://example.com');
+// Validation passes successfully
+
+v::filterVar(FILTER_VALIDATE_URL, FILTER_FLAG_PATH_REQUIRED)->assert('http://example.com');
+// → "http://example.com" must be valid
+
+v::filterVar(FILTER_VALIDATE_URL, FILTER_FLAG_PATH_REQUIRED)->assert('http://example.com/path');
+// Validation passes successfully
+
+v::filterVar(FILTER_VALIDATE_DOMAIN, FILTER_FLAG_HOSTNAME)->assert('webserver.local');
+// Validation passes successfully
+
+v::filterVar(FILTER_VALIDATE_DOMAIN, FILTER_FLAG_HOSTNAME)->assert('@local');
+// → "@local" must be valid
```
## Templates
diff --git a/docs/validators/Finite.md b/docs/validators/Finite.md
index 4d178583..e46de77c 100644
--- a/docs/validators/Finite.md
+++ b/docs/validators/Finite.md
@@ -5,8 +5,11 @@
Validates if the input is a finite number.
```php
-v::finite()->isValid('10'); // true
-v::finite()->isValid(10); // true
+v::finite()->assert('10');
+// Validation passes successfully
+
+v::finite()->assert(10);
+// Validation passes successfully
```
## Templates
@@ -46,4 +49,3 @@ See also:
- [IntType](IntType.md)
- [IntVal](IntVal.md)
- [NumericVal](NumericVal.md)
-- [Type](Type.md)
diff --git a/docs/validators/FloatType.md b/docs/validators/FloatType.md
index 988fc4db..ed3144e1 100644
--- a/docs/validators/FloatType.md
+++ b/docs/validators/FloatType.md
@@ -5,9 +5,14 @@
Validates whether the type of the input is [float](http://php.net/types.float).
```php
-v::floatType()->isValid(1.5); // true
-v::floatType()->isValid('1.5'); // false
-v::floatType()->isValid(0e5); // true
+v::floatType()->assert(1.5);
+// Validation passes successfully
+
+v::floatType()->assert('1.5');
+// → "1.5" must be float
+
+v::floatType()->assert(0e5);
+// Validation passes successfully
```
## Templates
@@ -54,4 +59,3 @@ See also:
- [ResourceType](ResourceType.md)
- [StringType](StringType.md)
- [StringVal](StringVal.md)
-- [Type](Type.md)
diff --git a/docs/validators/FloatVal.md b/docs/validators/FloatVal.md
index b5c32745..72a612e1 100644
--- a/docs/validators/FloatVal.md
+++ b/docs/validators/FloatVal.md
@@ -5,8 +5,11 @@
Validate whether the input value is float.
```php
-v::floatVal()->isValid(1.5); // true
-v::floatVal()->isValid('1e5'); // true
+v::floatVal()->assert(1.5);
+// Validation passes successfully
+
+v::floatVal()->assert('1e5');
+// Validation passes successfully
```
## Templates
@@ -44,4 +47,3 @@ See also:
- [FloatType](FloatType.md)
- [IntType](IntType.md)
- [IntVal](IntVal.md)
-- [Type](Type.md)
diff --git a/docs/validators/Graph.md b/docs/validators/Graph.md
index 909b272d..4e99165a 100644
--- a/docs/validators/Graph.md
+++ b/docs/validators/Graph.md
@@ -7,7 +7,8 @@ Validates if all characters in the input are printable and actually creates
visible output (no white space).
```php
-v::graph()->isValid('LKM@#$%4;'); // true
+v::graph()->assert('LKM@#$%4;');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/GreaterThan.md b/docs/validators/GreaterThan.md
index 89cae3dd..0c4f073e 100644
--- a/docs/validators/GreaterThan.md
+++ b/docs/validators/GreaterThan.md
@@ -5,8 +5,11 @@
Validates whether the input is greater than a value.
```php
-v::greaterThan(10)->isValid(11); // true
-v::greaterThan(10)->isValid(9); // false
+v::greaterThan(10)->assert(11);
+// Validation passes successfully
+
+v::greaterThan(10)->assert(9);
+// → 9 must be greater than 10
```
Validation makes comparison easier, check out our supported
diff --git a/docs/validators/GreaterThanOrEqual.md b/docs/validators/GreaterThanOrEqual.md
index efd1d17b..e6b82db1 100644
--- a/docs/validators/GreaterThanOrEqual.md
+++ b/docs/validators/GreaterThanOrEqual.md
@@ -5,9 +5,14 @@
Validates whether the input is greater than or equal to a value.
```php
-v::intVal()->greaterThanOrEqual(10)->isValid(9); // false
-v::intVal()->greaterThanOrEqual(10)->isValid(10); // true
-v::intVal()->greaterThanOrEqual(10)->isValid(11); // true
+v::intVal()->greaterThanOrEqual(10)->assert(9);
+// → 9 must be greater than or equal to 10
+
+v::intVal()->greaterThanOrEqual(10)->assert(10);
+// Validation passes successfully
+
+v::intVal()->greaterThanOrEqual(10)->assert(11);
+// Validation passes successfully
```
Validation makes comparison easier, check out our supported
diff --git a/docs/validators/Hetu.md b/docs/validators/Hetu.md
index 0118143a..c3e85d40 100644
--- a/docs/validators/Hetu.md
+++ b/docs/validators/Hetu.md
@@ -5,11 +5,17 @@
Validates a Finnish personal identity code ([HETU][]).
```php
-v::hetu()->isValid('010106A9012'); // true
-v::hetu()->isValid('290199-907A'); // true
-v::hetu()->isValid('280291+923X'); // true
+v::hetu()->assert('010106A9012');
+// Validation passes successfully
-v::hetu()->isValid('010106_9012'); // false
+v::hetu()->assert('290199-907A');
+// Validation passes successfully
+
+v::hetu()->assert('280291+923X');
+// Validation passes successfully
+
+v::hetu()->assert('010106_9012');
+// → "010106_9012" must be a valid Finnish personal identity code
```
The validation is case-sensitive.
diff --git a/docs/validators/HexRgbColor.md b/docs/validators/HexRgbColor.md
index 943f75e4..df1d1f8d 100644
--- a/docs/validators/HexRgbColor.md
+++ b/docs/validators/HexRgbColor.md
@@ -5,10 +5,17 @@
Validates weather the input is a hex RGB color or not.
```php
-v::hexRgbColor()->isValid('#FFFAAA'); // true
-v::hexRgbColor()->isValid('#ff6600'); // true
-v::hexRgbColor()->isValid('123123'); // true
-v::hexRgbColor()->isValid('FCD'); // true
+v::hexRgbColor()->assert('#FFFAAA');
+// Validation passes successfully
+
+v::hexRgbColor()->assert('#ff6600');
+// Validation passes successfully
+
+v::hexRgbColor()->assert('123123');
+// Validation passes successfully
+
+v::hexRgbColor()->assert('FCD');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Iban.md b/docs/validators/Iban.md
index 823576dc..ba4969f6 100644
--- a/docs/validators/Iban.md
+++ b/docs/validators/Iban.md
@@ -6,12 +6,20 @@ Validates whether the input is a valid [IBAN][] (International Bank Account
Number) or not.
```php
-v::iban()->isValid('SE35 5000 0000 0549 1000 0003'); // true
-v::iban()->isValid('ch9300762011623852957'); // true
+v::iban()->assert('SE35 5000 0000 0549 1000 0003');
+// Validation passes successfully
-v::iban()->isValid('ZZ32 5000 5880 7742'); // false
-v::iban()->isValid(123456789); // false
-v::iban()->isValid(''); // false
+v::iban()->assert('ch9300762011623852957');
+// → "ch9300762011623852957" must be a valid IBAN
+
+v::iban()->assert('ZZ32 5000 5880 7742');
+// → "ZZ32 5000 5880 7742" must be a valid IBAN
+
+v::iban()->assert(123456789);
+// → 123456789 must be a valid IBAN
+
+v::iban()->assert('');
+// → "" must be a valid IBAN
```
## Templates
diff --git a/docs/validators/Identical.md b/docs/validators/Identical.md
index 760079d1..e1f83ad0 100644
--- a/docs/validators/Identical.md
+++ b/docs/validators/Identical.md
@@ -5,8 +5,11 @@
Validates if the input is identical to some value.
```php
-v::identical(42)->isValid(42); // true
-v::identical(42)->isValid('42'); // false
+v::identical(42)->assert(42);
+// Validation passes successfully
+
+v::identical(42)->assert('42');
+// → "42" must be identical to 42
```
Message template for this validator includes `{{compareTo}}`.
diff --git a/docs/validators/Image.md b/docs/validators/Image.md
index 52777401..7d8f82b3 100644
--- a/docs/validators/Image.md
+++ b/docs/validators/Image.md
@@ -5,9 +5,14 @@
Validates if the file is a valid image by checking its MIME type.
```php
-v::image()->isValid('image.gif'); // true
-v::image()->isValid('image.jpg'); // true
-v::image()->isValid('image.png'); // true
+v::image()->assert('/path/to/image.gif');
+// Validation passes successfully
+
+v::image()->assert('/path/to/image.jpg');
+// Validation passes successfully
+
+v::image()->assert('/path/to/image.png');
+// Validation passes successfully
```
All the validations above must return `false` if the input is not a valid file
diff --git a/docs/validators/Imei.md b/docs/validators/Imei.md
index 63f568e1..4f0c4909 100644
--- a/docs/validators/Imei.md
+++ b/docs/validators/Imei.md
@@ -5,8 +5,11 @@
Validates is the input is a valid [IMEI][].
```php
-v::imei()->isValid('35-209900-176148-1'); // true
-v::imei()->isValid('490154203237518'); // true
+v::imei()->assert('35-209900-176148-1');
+// Validation passes successfully
+
+v::imei()->assert('490154203237518');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/In.md b/docs/validators/In.md
index 781f450c..5b24f346 100644
--- a/docs/validators/In.md
+++ b/docs/validators/In.md
@@ -8,13 +8,15 @@ Validates if the input is contained in a specific haystack.
For strings:
```php
-v::in('lorem ipsum')->isValid('ipsum'); // true
+v::in('lorem ipsum')->assert('ipsum');
+// Validation passes successfully
```
For arrays:
```php
-v::in(['lorem', 'ipsum'])->isValid('lorem'); // true
+v::in(['lorem', 'ipsum'])->assert('lorem');
+// Validation passes successfully
```
A second parameter may be passed for identical comparison instead
diff --git a/docs/validators/Infinite.md b/docs/validators/Infinite.md
index 341bcf2c..b5ba6184 100644
--- a/docs/validators/Infinite.md
+++ b/docs/validators/Infinite.md
@@ -5,7 +5,8 @@
Validates if the input is an infinite number.
```php
-v::infinite()->isValid(INF); // true
+v::infinite()->assert(INF);
+// Validation passes successfully
```
## Templates
@@ -45,4 +46,3 @@ See also:
- [IntType](IntType.md)
- [IntVal](IntVal.md)
- [NumericVal](NumericVal.md)
-- [Type](Type.md)
diff --git a/docs/validators/Instance.md b/docs/validators/Instance.md
index c9bed98f..0b8c426e 100644
--- a/docs/validators/Instance.md
+++ b/docs/validators/Instance.md
@@ -5,8 +5,11 @@
Validates if the input is an instance of the given class or interface.
```php
-v::instance('DateTime')->isValid(new DateTime); // true
-v::instance('Traversable')->isValid(new ArrayObject); // true
+v::instance('DateTime')->assert(new DateTime);
+// Validation passes successfully
+
+v::instance('Traversable')->assert(new ArrayObject);
+// Validation passes successfully
```
Message template for this validator includes `{{instanceName}}`.
@@ -45,4 +48,3 @@ See also:
- [IterableType](IterableType.md)
- [IterableVal](IterableVal.md)
- [ObjectType](ObjectType.md)
-- [Type](Type.md)
diff --git a/docs/validators/IntType.md b/docs/validators/IntType.md
index de2f101c..affa2f21 100644
--- a/docs/validators/IntType.md
+++ b/docs/validators/IntType.md
@@ -5,8 +5,11 @@
Validates whether the type of the input is [integer](http://php.net/types.integer).
```php
-v::intType()->isValid(42); // true
-v::intType()->isValid('10'); // false
+v::intType()->assert(42);
+// Validation passes successfully
+
+v::intType()->assert('10');
+// → "10" must be an integer
```
## Templates
@@ -57,4 +60,3 @@ See also:
- [ResourceType](ResourceType.md)
- [StringType](StringType.md)
- [StringVal](StringVal.md)
-- [Type](Type.md)
diff --git a/docs/validators/IntVal.md b/docs/validators/IntVal.md
index bfc4267b..14a2fd62 100644
--- a/docs/validators/IntVal.md
+++ b/docs/validators/IntVal.md
@@ -5,11 +5,20 @@
Validates if the input is an integer, allowing leading zeros and other number bases.
```php
-v::intVal()->isValid('10'); // true
-v::intVal()->isValid('089'); // true
-v::intVal()->isValid(10); // true
-v::intVal()->isValid(0b101010); // true
-v::intVal()->isValid(0x2a); // true
+v::intVal()->assert('10');
+// Validation passes successfully
+
+v::intVal()->assert('089');
+// Validation passes successfully
+
+v::intVal()->assert(10);
+// Validation passes successfully
+
+v::intVal()->assert(0b101010);
+// Validation passes successfully
+
+v::intVal()->assert(0x2a);
+// Validation passes successfully
```
This validator will consider as valid any input that PHP can convert to an integer,
@@ -17,8 +26,11 @@ but that does not contain non-integer values. That way, one can safely use the
value this validator validates, without having surprises.
```php
-v::intVal()->isValid(true); // false
-v::intVal()->isValid('89a'); // false
+v::intVal()->assert(true);
+// → `true` must be an integer value
+
+v::intVal()->assert('89a');
+// → "89a" must be an integer value
```
Even though PHP can cast the values above as integers, this validator will not
@@ -65,4 +77,3 @@ See also:
- [Infinite](Infinite.md)
- [IntType](IntType.md)
- [NumericVal](NumericVal.md)
-- [Type](Type.md)
diff --git a/docs/validators/Ip.md b/docs/validators/Ip.md
index e662bfaf..7058deda 100644
--- a/docs/validators/Ip.md
+++ b/docs/validators/Ip.md
@@ -9,28 +9,38 @@ Validates whether the input is a valid IP address.
This validator uses the native [filter_var()][] PHP function.
```php
-v::ip()->isValid('127.0.0.1'); // true
-v::ip('220.78.168.0/21')->isValid('220.78.173.2'); // true
-v::ip('220.78.168.0/21')->isValid('220.78.176.2'); // false
+v::ip()->assert('127.0.0.1');
+// Validation passes successfully
+
+v::ip('220.78.168.0/21')->assert('220.78.173.2');
+// Validation passes successfully
+
+v::ip('220.78.168.0/21')->assert('220.78.176.2');
+// → "220.78.176.2" must be an IP address in the 220.78.168.0/255.255.255.255 range
```
Validating ranges:
```php
-v::ip('127.0.0.1-127.0.0.5')->isValid('127.0.0.2'); // true
-v::ip('127.0.0.1-127.0.0.5')->isValid('127.0.0.10'); // false
+v::ip('127.0.0.1-127.0.0.5')->assert('127.0.0.2');
+// Validation passes successfully
+
+v::ip('127.0.0.1-127.0.0.5')->assert('127.0.0.10');
+// → "127.0.0.10" must be an IP address in the 127.0.0.1-127.0.0.5 range
```
You can pass a parameter with [filter_var()][] flags for IP.
```php
-v::ip('*', FILTER_FLAG_NO_PRIV_RANGE)->isValid('192.168.0.1'); // false
+v::ip('*', FILTER_FLAG_NO_PRIV_RANGE)->assert('192.168.0.1');
+// → "192.168.0.1" must be an IP address
```
If you want to validate IPv6 you can do as follow:
```php
-v::ip('*', FILTER_FLAG_IPV6)->isValid('2001:0db8:85a3:08d3:1319:8a2e:0370:7334'); // true
+v::ip('*', FILTER_FLAG_IPV6)->assert('2001:0db8:85a3:08d3:1319:8a2e:0370:7334');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Isbn.md b/docs/validators/Isbn.md
index 973ea65d..78b590f6 100644
--- a/docs/validators/Isbn.md
+++ b/docs/validators/Isbn.md
@@ -5,10 +5,17 @@
Validates whether the input is a valid [ISBN][] or not.
```php
-v::isbn()->isValid('ISBN-13: 978-0-596-52068-7'); // true
-v::isbn()->isValid('978 0 596 52068 7'); // true
-v::isbn()->isValid('ISBN-12: 978-0-596-52068-7'); // false
-v::isbn()->isValid('978 10 596 52068 7'); // false
+v::isbn()->assert('ISBN-13: 978-0-596-52068-7');
+// Validation passes successfully
+
+v::isbn()->assert('978 0 596 52068 7');
+// Validation passes successfully
+
+v::isbn()->assert('ISBN-12: 978-0-596-52068-7');
+// → "ISBN-12: 978-0-596-52068-7" must be a valid ISBN
+
+v::isbn()->assert('978 10 596 52068 7');
+// → "978 10 596 52068 7" must be a valid ISBN
```
## Templates
diff --git a/docs/validators/IterableType.md b/docs/validators/IterableType.md
index b42ae6d1..b5d2b14f 100644
--- a/docs/validators/IterableType.md
+++ b/docs/validators/IterableType.md
@@ -5,11 +5,17 @@
Validates whether the input is iterable, meaning that it matches the built-in compile time type alias `iterable`.
```php
-v::iterableType()->isValid([]); // true
-v::iterableType()->isValid(new ArrayObject()); // true
+v::iterableType()->assert([]);
+// Validation passes successfully
-v::iterableType()->isValid(new stdClass()); // false
-v::iterableType()->isValid('string'); // false
+v::iterableType()->assert(new ArrayObject());
+// Validation passes successfully
+
+v::iterableType()->assert(new stdClass());
+// → `stdClass {}` must be iterable
+
+v::iterableType()->assert('string');
+// → "string" must be iterable
```
## Templates
diff --git a/docs/validators/IterableVal.md b/docs/validators/IterableVal.md
index 0aaf6748..3c582494 100644
--- a/docs/validators/IterableVal.md
+++ b/docs/validators/IterableVal.md
@@ -5,10 +5,17 @@
Validates whether the input is an iterable value, in other words, if you can iterate over it with the [foreach][] language construct.
```php
-v::iterableVal()->isValid([]); // true
-v::iterableVal()->isValid(new ArrayObject()); // true
-v::iterableVal()->isValid(new stdClass()); // true
-v::iterableVal()->isValid('string'); // false
+v::iterableVal()->assert([]);
+// Validation passes successfully
+
+v::iterableVal()->assert(new ArrayObject());
+// Validation passes successfully
+
+v::iterableVal()->assert(new stdClass());
+// Validation passes successfully
+
+v::iterableVal()->assert('string');
+// → "string" must be an iterable value
```
## Note
diff --git a/docs/validators/Json.md b/docs/validators/Json.md
index e54e8a43..2c853afb 100644
--- a/docs/validators/Json.md
+++ b/docs/validators/Json.md
@@ -5,7 +5,8 @@
Validates if the given input is a valid JSON.
```php
-v::json()->isValid('{"foo":"bar"}'); // true
+v::json()->assert('{"foo":"bar"}');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Key.md b/docs/validators/Key.md
index 5fcd9be7..ecb95adb 100644
--- a/docs/validators/Key.md
+++ b/docs/validators/Key.md
@@ -5,11 +5,14 @@
Validates the value of an array against a given validator.
```php
-v::key('name', v::stringType())->isValid(['name' => 'The Respect Panda']); // true
+v::key('name', v::stringType())->assert(['name' => 'The Respect Panda']);
+// Validation passes successfully
-v::key('email', v::email())->isValid(['email' => 'therespectpanda@gmail.com']); // true
+v::key('email', v::email())->assert(['email' => 'therespectpanda@gmail.com']);
+// Validation passes successfully
-v::key('age', v::intVal())->isValid([]); // false
+v::key('age', v::intVal())->assert([]);
+// → `.age` must be present
```
You can also use `Key` to validate nested arrays:
@@ -18,21 +21,22 @@ You can also use `Key` to validate nested arrays:
v::key(
'payment_details',
v::key('credit_card', v::creditCard())
-)->isValid([
+)->assert([
'payment_details' => [
'credit_card' => '5376 7473 9720 8720',
],
-]); // true
+]);
+// Validation passes successfully
```
The name of this validator is automatically set to the key name.
```php
v::key('email', v::email())->assert([]);
-// message: email must be present
+// → `.email` must be present
v::key('email', v::email())->assert(['email' => 'not email']);
-// message: email must be valid email
+// → `.email` must be a valid email address
```
## Note
diff --git a/docs/validators/KeyExists.md b/docs/validators/KeyExists.md
index a1171128..ed7625ce 100644
--- a/docs/validators/KeyExists.md
+++ b/docs/validators/KeyExists.md
@@ -5,14 +5,23 @@
Validates if the given key exists in an array.
```php
-v::keyExists('name')->isValid(['name' => 'The Respect Panda']); // true
-v::keyExists('name')->isValid(['email' => 'therespectpanda@gmail.com']); // false
+v::keyExists('name')->assert(['name' => 'The Respect Panda']);
+// Validation passes successfully
-v::keyExists(0)->isValid(['a', 'b', 'c']); // true
-v::keyExists(4)->isValid(['a', 'b', 'c']); // false
+v::keyExists('name')->assert(['email' => 'therespectpanda@gmail.com']);
+// → `.name` must be present
-v::keyExists('username')->isValid(new ArrayObject(['username' => 'therespectpanda'])); // true
-v::keyExists(5)->isValid(new ArrayObject(['a', 'b', 'c'])); // false
+v::keyExists(0)->assert(['a', 'b', 'c']);
+// Validation passes successfully
+
+v::keyExists(4)->assert(['a', 'b', 'c']);
+// → `.4` must be present
+
+v::keyExists('username')->assert(new ArrayObject(['username' => 'therespectpanda']));
+// Validation passes successfully
+
+v::keyExists(5)->assert(new ArrayObject(['a', 'b', 'c']));
+// → `.5` must be present
```
## Notes
@@ -43,17 +52,17 @@ When no custom name is set, the path is displayed as `{{name}}`. When a custom n
```php
v::keyExists('foo')->assert([]);
-// Message: `.foo` must be present
+// → `.foo` must be present
v::named('Custom name', v::keyExists('foo'))->assert([]);
-// Message: `.foo` (<- Custom name) must be present
+// → `.foo` (<- Custom name) must be present
```
If you want to display only a custom name while checking if a key exists, use [Key](Key.md) with [AlwaysValid](AlwaysValid.md):
```php
-v::key('foo', v::named('Custom name', v::alwaysValid())->assert([]);
-// Message: Custom name must be present
+v::key('foo', v::named('Custom name', v::alwaysValid()))->assert([]);
+// → Custom name must be present
```
## Categorization
diff --git a/docs/validators/KeyOptional.md b/docs/validators/KeyOptional.md
index 56e45c16..890a7b3f 100644
--- a/docs/validators/KeyOptional.md
+++ b/docs/validators/KeyOptional.md
@@ -5,20 +5,27 @@
Validates the value of an array against a given validator when the key exists.
```php
-v::keyOptional('name', v::stringType())->isValid([]); // true
-v::keyOptional('name', v::stringType())->isValid(['name' => 'The Respect Panda']); // true
+v::keyOptional('name', v::stringType())->assert([]);
+// Validation passes successfully
-v::keyOptional('email', v::email())->isValid([]); // true
-v::keyOptional('email', v::email())->isValid(['email' => 'therespectpanda@gmail.com']); // true
+v::keyOptional('name', v::stringType())->assert(['name' => 'The Respect Panda']);
+// Validation passes successfully
-v::keyOptional('age', v::intVal())->isValid(['age' => 'Twenty-Five']); // false
+v::keyOptional('email', v::email())->assert([]);
+// Validation passes successfully
+
+v::keyOptional('email', v::email())->assert(['email' => 'therespectpanda@gmail.com']);
+// Validation passes successfully
+
+v::keyOptional('age', v::intVal())->assert(['age' => 'Twenty-Five']);
+// → `.age` must be an integer value
```
The name of this validator is automatically set to the key name.
```php
v::keyOptional('age', v::intVal())->assert(['age' => 'Twenty-Five']);
-// message: age must be an integer number
+// → `.age` must be an integer value
```
## Note
@@ -28,7 +35,7 @@ want to ensure the input is an array, use [ArrayType](ArrayType.md) with it.
```php
v::arrayType()->keyOptional('phone', v::phone())->assert('This is not an array');
-// message: "This is not an array" must be of type array
+// → "This is not an array" must be an array
```
Below are some other validators that are tightly related to `KeyOptional`:
diff --git a/docs/validators/KeySet.md b/docs/validators/KeySet.md
index 61e29176..a37abef0 100644
--- a/docs/validators/KeySet.md
+++ b/docs/validators/KeySet.md
@@ -9,7 +9,8 @@ Validates a keys in a defined structure.
v::keySet(
v::keyExists('foo'),
v::keyExists('bar')
-)->isValid(['foo' => 'whatever', 'bar' => 'something']); // true
+)->assert(['foo' => 'whatever', 'bar' => 'something']);
+// Validation passes successfully
```
It will validate the keys in the array with the validators passed in the constructor.
@@ -17,11 +18,13 @@ It will validate the keys in the array with the validators passed in the constru
```php
v::keySet(
v::key('foo', v::intVal())
-)->isValid(['foo' => 42]); // true
+)->assert(['foo' => 42]);
+// Validation passes successfully
v::keySet(
v::key('foo', v::intVal())
-)->isValid(['foo' => 'string']); // false
+)->assert(['foo' => 'string']);
+// → `.foo` must be an integer value
```
Extra keys are not allowed:
@@ -29,7 +32,8 @@ Extra keys are not allowed:
```php
v::keySet(
v::key('foo', v::intVal())
-)->isValid(['foo' => 42, 'bar' => 'String']); // false
+)->assert(['foo' => 42, 'bar' => 'String']);
+// → `.bar` must not be present
```
Missing required keys are not allowed:
@@ -39,7 +43,8 @@ v::keySet(
v::key('foo', v::intVal()),
v::key('bar', v::stringType()),
v::key('baz', v::boolType())
-)->isValid(['foo' => 42, 'bar' => 'String']); // false
+)->assert(['foo' => 42, 'bar' => 'String']);
+// → `.baz` must be present
```
Missing non-required keys are allowed:
@@ -49,7 +54,8 @@ v::keySet(
v::key('foo', v::intVal()),
v::key('bar', v::stringType()),
v::keyOptional('baz', v::boolType())
-)->isValid(['foo' => 42, 'bar' => 'String']); // true
+)->assert(['foo' => 42, 'bar' => 'String']);
+// Validation passes successfully
```
Alternatively, you can pass a chain of key-related validators to `keySet()`:
@@ -60,7 +66,8 @@ v::keySet(
->key('foo', v::intVal())
->key('bar', v::stringType())
->keyOptional('baz', v::boolType())
-)->isValid(['foo' => 42, 'bar' => 'String']); // true
+)->assert(['foo' => 42, 'bar' => 'String']);
+// Validation passes successfully
```
It is not possible to negate `keySet()` validators with `not()`.
diff --git a/docs/validators/LanguageCode.md b/docs/validators/LanguageCode.md
index 54648b91..517cd4d8 100644
--- a/docs/validators/LanguageCode.md
+++ b/docs/validators/LanguageCode.md
@@ -8,11 +8,20 @@ Validates whether the input is language code based on [ISO 639][].
**This validator requires [sokil/php-isocodes][] and [sokil/php-isocodes-db-only][] to be installed.**
```php
-v::languageCode()->isValid('pt'); // true
-v::languageCode()->isValid('en'); // true
-v::languageCode()->isValid('it'); // true
-v::languageCode('alpha-3')->isValid('ita'); // true
-v::languageCode('alpha-3')->isValid('eng'); // true
+v::languageCode()->assert('pt');
+// Validation passes successfully
+
+v::languageCode()->assert('en');
+// Validation passes successfully
+
+v::languageCode()->assert('it');
+// Validation passes successfully
+
+v::languageCode('alpha-3')->assert('ita');
+// Validation passes successfully
+
+v::languageCode('alpha-3')->assert('eng');
+// Validation passes successfully
```
This validator supports the two[ISO 639][] sets:
diff --git a/docs/validators/Lazy.md b/docs/validators/Lazy.md
index 68eff512..4f61825c 100644
--- a/docs/validators/Lazy.md
+++ b/docs/validators/Lazy.md
@@ -8,7 +8,8 @@ This validator is particularly useful when creating validators that rely on the
`confirmation` field matches the `password` field when processing data from a form.
```php
-v::key('confirmation', v::equals($_POST['password'] ?? null))->isValid($_POST);
+v::key('confirmation', v::equals($_POST['password'] ?? null))->assert($_POST);
+// → `.confirmation` must be present
```
The issue with the code is that it’s hard to reuse because you’re relying upon the input itself (`$_POST`). That means
@@ -17,7 +18,8 @@ you can create a chain of validators and use it everywhere.
The `lazy()` validator makes this job much simpler and more elegantly:
```php
-v::lazy(static fn($input) => v::key('confirmation', v::equals($input['password'] ?? null)))->isValid($_POST);
+v::lazy(static fn($input) => v::key('confirmation', v::equals($input['password'] ?? null)))->assert($_POST);
+// → `.confirmation` must be present
```
The code above is similar to the first example, but the biggest difference is that the creation of the validator doesn't rely
diff --git a/docs/validators/LeapDate.md b/docs/validators/LeapDate.md
index 732026b1..eeb7731e 100644
--- a/docs/validators/LeapDate.md
+++ b/docs/validators/LeapDate.md
@@ -5,7 +5,8 @@
Validates if a date is leap.
```php
-v::leapDate('Y-m-d')->isValid('1988-02-29'); // true
+v::leapDate('Y-m-d')->assert('1988-02-29');
+// Validation passes successfully
```
This validator accepts DateTime instances as well. The $format
diff --git a/docs/validators/LeapYear.md b/docs/validators/LeapYear.md
index 471301cc..afe1f01c 100644
--- a/docs/validators/LeapYear.md
+++ b/docs/validators/LeapYear.md
@@ -5,7 +5,8 @@
Validates if a year is leap.
```php
-v::leapYear()->isValid('1988'); // true
+v::leapYear()->assert('1988');
+// Validation passes successfully
```
This validator accepts DateTime instances as well.
diff --git a/docs/validators/Length.md b/docs/validators/Length.md
index 7a8e1ffe..ad908c3e 100644
--- a/docs/validators/Length.md
+++ b/docs/validators/Length.md
@@ -5,19 +5,24 @@
Validates the length of the given input against a given validator.
```php
-v::length(v::between(1, 5))->isValid('abc'); // true
+v::length(v::between(1, 5))->assert('abc');
+// Validation passes successfully
-v::length(v::greaterThan(5))->isValid('abcdef'); // true
+v::length(v::greaterThan(5))->assert('abcdef');
+// Validation passes successfully
-v::length(v::lessThan(5))->isValid('abc'); // true
+v::length(v::lessThan(5))->assert('abc');
+// Validation passes successfully
```
This validator can be used to validate the length of strings, arrays, and objects that implement the `Countable` interface.
```php
-v::length(v::greaterThanOrEqual(3))->isValid([1, 2, 3]); // true
+v::length(v::greaterThanOrEqual(3))->assert([1, 2, 3]);
+// Validation passes successfully
-v::length(v::equals(0))->isValid(new SplPriorityQueue()); // true
+v::length(v::equals(0))->assert(new SplPriorityQueue());
+// Validation passes successfully
```
## Templates
@@ -44,10 +49,10 @@ The template serves as a prefix to the template of the inner validator.
```php
v::length(v::equals(3))->assert('tulip');
-// Message: The length of "tulip" must be equal to 3
+// → The length of "tulip" must be equal to 3
v::not(v::length(v::equals(4)))->assert('rose');
-// Message: The length of "rose" must not be equal to 4
+// → The length of "rose" must not be equal to 4
```
### `Length::TEMPLATE_WRONG_TYPE`
diff --git a/docs/validators/LessThan.md b/docs/validators/LessThan.md
index 3722338f..4bbd4fcc 100644
--- a/docs/validators/LessThan.md
+++ b/docs/validators/LessThan.md
@@ -5,8 +5,11 @@
Validates whether the input is less than a value.
```php
-v::lessThan(10)->isValid(9); // true
-v::lessThan(10)->isValid(10); // false
+v::lessThan(10)->assert(9);
+// Validation passes successfully
+
+v::lessThan(10)->assert(10);
+// → 10 must be less than 10
```
Validation makes comparison easier, check out our supported
diff --git a/docs/validators/LessThanOrEqual.md b/docs/validators/LessThanOrEqual.md
index 610f5181..871a178f 100644
--- a/docs/validators/LessThanOrEqual.md
+++ b/docs/validators/LessThanOrEqual.md
@@ -5,9 +5,14 @@
Validates whether the input is less than or equal to a value.
```php
-v::lessThanOrEqual(10)->isValid(9); // true
-v::lessThanOrEqual(10)->isValid(10); // true
-v::lessThanOrEqual(10)->isValid(11); // false
+v::lessThanOrEqual(10)->assert(9);
+// Validation passes successfully
+
+v::lessThanOrEqual(10)->assert(10);
+// Validation passes successfully
+
+v::lessThanOrEqual(10)->assert(11);
+// → 11 must be less than or equal to 10
```
Validation makes comparison easier, check out our supported
diff --git a/docs/validators/Lowercase.md b/docs/validators/Lowercase.md
index c7934e2f..d3ec08e5 100644
--- a/docs/validators/Lowercase.md
+++ b/docs/validators/Lowercase.md
@@ -5,7 +5,8 @@
Validates whether the characters in the input are lowercase.
```php
-v::stringType()->lowercase()->isValid('xkcd'); // true
+v::stringType()->lowercase()->assert('xkcd');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Luhn.md b/docs/validators/Luhn.md
index b5e59d58..81380887 100644
--- a/docs/validators/Luhn.md
+++ b/docs/validators/Luhn.md
@@ -5,8 +5,11 @@
Validate whether a given input is a [Luhn][] number.
```php
-v::luhn()->isValid('2222400041240011'); // true
-v::luhn()->isValid('respect!'); // false
+v::luhn()->assert('2222400041240011');
+// Validation passes successfully
+
+v::luhn()->assert('respect!');
+// → "respect!" must be a valid Luhn number
```
## Templates
diff --git a/docs/validators/MacAddress.md b/docs/validators/MacAddress.md
index 29ed85fb..39a6423f 100644
--- a/docs/validators/MacAddress.md
+++ b/docs/validators/MacAddress.md
@@ -5,8 +5,11 @@
Validates whether the input is a valid MAC address.
```php
-v::macAddress()->isValid('00:11:22:33:44:55'); // true
-v::macAddress()->isValid('af-AA-22-33-44-55'); // true
+v::macAddress()->assert('00:11:22:33:44:55');
+// Validation passes successfully
+
+v::macAddress()->assert('af-AA-22-33-44-55');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Max.md b/docs/validators/Max.md
index a579e440..3be63fd6 100644
--- a/docs/validators/Max.md
+++ b/docs/validators/Max.md
@@ -5,14 +5,18 @@
Validates the maximum value of the input against a given validator.
```php
-v::max(v::equals(30))->isValid([10, 20, 30]); // true
+v::max(v::equals(30))->assert([10, 20, 30]);
+// Validation passes successfully
-v::max(v::between('e', 'g'))->isValid(['b', 'd', 'f']); // true
+v::max(v::between('e', 'g'))->assert(['b', 'd', 'f']);
+// Validation passes successfully
v::max(v::greaterThan(new DateTime('today')))
- ->isValid([new DateTime('yesterday'), new DateTime('tomorrow')]); // true
+ ->assert([new DateTime('yesterday'), new DateTime('tomorrow')]);
+// Validation passes successfully
-v::max(v::greaterThan(15))->isValid([4, 8, 12]); // false
+v::max(v::greaterThan(15))->assert([4, 8, 12]);
+// → The maximum of `[4, 8, 12]` must be greater than 15
```
## Note
diff --git a/docs/validators/Mimetype.md b/docs/validators/Mimetype.md
index 726713c7..fa937805 100644
--- a/docs/validators/Mimetype.md
+++ b/docs/validators/Mimetype.md
@@ -5,8 +5,11 @@
Validates if the input is a file and if its MIME type matches the expected one.
```php
-v::mimetype('image/png')->isValid('image.png'); // true
-v::mimetype('image/jpeg')->isValid('image.jpg'); // true
+v::mimetype('image/png')->assert('/path/to/image.png');
+// Validation passes successfully
+
+v::mimetype('image/jpeg')->assert('/path/to/image.jpg');
+// Validation passes successfully
```
This validator is case-sensitive and requires [fileinfo](http://php.net/fileinfo) PHP extension.
diff --git a/docs/validators/Min.md b/docs/validators/Min.md
index b9ca4cf3..f199020c 100644
--- a/docs/validators/Min.md
+++ b/docs/validators/Min.md
@@ -5,14 +5,18 @@
Validates the minimum value of the input against a given validator.
```php
-v::min(v::equals(10))->isValid([10, 20, 30]); // true
+v::min(v::equals(10))->assert([10, 20, 30]);
+// Validation passes successfully
-v::min(v::between('a', 'c'))->isValid(['b', 'd', 'f']); // true
+v::min(v::between('a', 'c'))->assert(['b', 'd', 'f']);
+// Validation passes successfully
v::min(v::greaterThan(new DateTime('yesterday')))
- ->isValid([new DateTime('today'), new DateTime('tomorrow')]); // true
+ ->assert([new DateTime('today'), new DateTime('tomorrow')]);
+// Validation passes successfully
-v::min(v::lessThan(3))->isValid([4, 8, 12]); // false
+v::min(v::lessThan(3))->assert([4, 8, 12]);
+// → The minimum of `[4, 8, 12]` must be less than 3
```
## Note
diff --git a/docs/validators/Multiple.md b/docs/validators/Multiple.md
index 6eba06c1..18cfd922 100644
--- a/docs/validators/Multiple.md
+++ b/docs/validators/Multiple.md
@@ -5,7 +5,8 @@
Validates if the input is a multiple of the given parameter
```php
-v::intVal()->multiple(3)->isValid(9); // true
+v::intVal()->multiple(3)->assert(9);
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Named.md b/docs/validators/Named.md
index 5dbea7ee..f558b4d7 100644
--- a/docs/validators/Named.md
+++ b/docs/validators/Named.md
@@ -6,14 +6,14 @@ Validates the input with the given validator, and uses the custom name in the er
```php
v::named('Your email', v::email())->assert('not an email');
-// Message: Your email must be a valid email address
+// → Your email must be a valid email address
```
Here's an example of a similar code, but without using the `Named` validator:
```php
v::email()->assert('not an email');
-// Message: "not an email" must be a valid email address
+// → "not an email" must be a valid email address
```
The `Named` validator can be also useful when you're using [Attributes](Attributes.md) and want a custom name for a specific property.
diff --git a/docs/validators/Negative.md b/docs/validators/Negative.md
index ac23470f..72795c0b 100644
--- a/docs/validators/Negative.md
+++ b/docs/validators/Negative.md
@@ -5,7 +5,8 @@
Validates whether the input is a negative number.
```php
-v::numericVal()->negative()->isValid(-15); // true
+v::numericVal()->negative()->assert(-15);
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/NfeAccessKey.md b/docs/validators/NfeAccessKey.md
index 8d742b17..1d866e48 100644
--- a/docs/validators/NfeAccessKey.md
+++ b/docs/validators/NfeAccessKey.md
@@ -5,7 +5,8 @@
Validates the access key of the Brazilian electronic invoice (NFe).
```php
-v::nfeAccessKey()->isValid('31841136830118868211870485416765268625116906'); // true
+v::nfeAccessKey()->assert('31841136830118868211870485416765268625116906');
+// → "31841136830118868211870485416765268625116906" must be a valid NFe access key
```
## Templates
diff --git a/docs/validators/Nif.md b/docs/validators/Nif.md
index b17d40e7..ac087e3e 100644
--- a/docs/validators/Nif.md
+++ b/docs/validators/Nif.md
@@ -5,8 +5,11 @@
Validates Spain's fiscal identification number ([NIF](https://es.wikipedia.org/wiki/N%C3%BAmero_de_identificaci%C3%B3n_fiscal)).
```php
-v::nif()->isValid('49294492H'); // true
-v::nif()->isValid('P6437358A'); // false
+v::nif()->assert('49294492H');
+// Validation passes successfully
+
+v::nif()->assert('P6437358A');
+// → "P6437358A" must be a valid NIF
```
## Templates
diff --git a/docs/validators/Nip.md b/docs/validators/Nip.md
index 0938a312..d6b26d26 100644
--- a/docs/validators/Nip.md
+++ b/docs/validators/Nip.md
@@ -5,11 +5,20 @@
Validates whether the input is a Polish VAT identification number (NIP).
```php
-v::nip()->isValid('1645865777'); // true
-v::nip()->isValid('1645865778'); // false
-v::nip()->isValid('1234567890'); // false
-v::nip()->isValid('164-586-57-77'); // false
-v::nip()->isValid('164-58-65-777'); // false
+v::nip()->assert('1645865777');
+// Validation passes successfully
+
+v::nip()->assert('1645865778');
+// → "1645865778" must be a valid Polish VAT identification number
+
+v::nip()->assert('1234567890');
+// → "1234567890" must be a valid Polish VAT identification number
+
+v::nip()->assert('164-586-57-77');
+// → "164-586-57-77" must be a valid Polish VAT identification number
+
+v::nip()->assert('164-58-65-777');
+// → "164-58-65-777" must be a valid Polish VAT identification number
```
## Templates
diff --git a/docs/validators/NoneOf.md b/docs/validators/NoneOf.md
index 676e0da5..557764b8 100644
--- a/docs/validators/NoneOf.md
+++ b/docs/validators/NoneOf.md
@@ -6,10 +6,8 @@
Validates if NONE of the given validators validate:
```php
-v::noneOf(
- v::intVal(),
- v::floatVal()
-)->isValid('foo'); // true
+v::noneOf(v::intVal(), v::floatVal())->assert('foo');
+// Validation passes successfully
```
In the sample above, 'foo' isn't a integer nor a float, so noneOf returns true.
diff --git a/docs/validators/Not.md b/docs/validators/Not.md
index ab4e5303..259e7799 100644
--- a/docs/validators/Not.md
+++ b/docs/validators/Not.md
@@ -5,7 +5,8 @@
Negates any validator.
```php
-v::not(v::ip())->isValid('foo'); // true
+v::not(v::ip())->assert('foo');
+// Validation passes successfully
```
In the sample above, validator returns true because 'foo' isn't an IP Address.
@@ -13,7 +14,8 @@ In the sample above, validator returns true because 'foo' isn't an IP Address.
You can negate complex, grouped or chained validators as well:
```php
-v::not(v::intVal()->positive())->isValid(-1.5); // true
+v::not(v::intVal()->positive())->assert(-1.5);
+// Validation passes successfully
```
Each other validation has custom messages for negated validators.
diff --git a/docs/validators/NullOr.md b/docs/validators/NullOr.md
index 518abe97..3d302355 100644
--- a/docs/validators/NullOr.md
+++ b/docs/validators/NullOr.md
@@ -7,9 +7,14 @@ Validates the input using a defined validator when the input is not `null`.
## Usage
```php
-v::nullable(v::email())->isValid(null); // true
-v::nullable(v::email())->isValid('example@example.com'); // true
-v::nullable(v::email())->isValid('not an email'); // false
+v::nullOr(v::email())->assert(null);
+// Validation passes successfully
+
+v::nullOr(v::email())->assert('example@example.com');
+// Validation passes successfully
+
+v::nullOr(v::email())->assert('not an email');
+// → "not an email" must be a valid email address or must be null
```
## Prefix
@@ -17,9 +22,14 @@ v::nullable(v::email())->isValid('not an email'); // false
For convenience, you can use `nullOr` as a prefix to any validator:
```php
-v::nullOrEmail()->isValid('not an email'); // false
-v::nullOrBetween(1, 3)->isValid(2); // true
-v::nullOrBetween(1, 3)->isValid(null); // true
+v::nullOrEmail()->assert('not an email');
+// → "not an email" must be a valid email address or must be null
+
+v::nullOrBetween(1, 3)->assert(2);
+// Validation passes successfully
+
+v::nullOrBetween(1, 3)->assert(null);
+// Validation passes successfully
```
## Templates
@@ -37,10 +47,10 @@ The template serves as a suffix to the template of the inner validator.
```php
v::nullOr(v::alpha())->assert('has1number');
-// "has1number" must contain only letters (a-z) or must be null
+// → "has1number" must contain only letters (a-z) or must be null
v::not(v::nullOr(v::alpha()))->assert("alpha");
-// "alpha" must not contain letters (a-z) and must not be null
+// → "alpha" must not contain letters (a-z) and must not be null
```
## Template placeholders
diff --git a/docs/validators/NullType.md b/docs/validators/NullType.md
index b7d5da2f..7fd6a4fb 100644
--- a/docs/validators/NullType.md
+++ b/docs/validators/NullType.md
@@ -5,7 +5,8 @@
Validates whether the input is [null](http://php.net/types.null).
```php
-v::nullType()->isValid(null); // true
+v::nullType()->assert(null);
+// Validation passes successfully
```
## Templates
@@ -52,6 +53,5 @@ See also:
- [ResourceType](ResourceType.md)
- [StringType](StringType.md)
- [StringVal](StringVal.md)
-- [Type](Type.md)
- [Undef](Undef.md)
- [UndefOr](UndefOr.md)
diff --git a/docs/validators/Number.md b/docs/validators/Number.md
index 2dbe62ec..bd651502 100644
--- a/docs/validators/Number.md
+++ b/docs/validators/Number.md
@@ -5,8 +5,11 @@
Validates if the input is a number.
```php
-v::number()->isValid(42); // true
-v::number()->isValid(acos(8)); // false
+v::number()->assert(42);
+// Validation passes successfully
+
+v::number()->assert(acos(8));
+// → `NaN` must be a valid number
```
> "In computing, NaN, standing for not a number, is a numeric data type value
@@ -53,5 +56,4 @@ See also:
- [ObjectType](ObjectType.md)
- [ResourceType](ResourceType.md)
- [StringType](StringType.md)
-- [Type](Type.md)
- [Undef](Undef.md)
diff --git a/docs/validators/NumericVal.md b/docs/validators/NumericVal.md
index c927a80f..d9706635 100644
--- a/docs/validators/NumericVal.md
+++ b/docs/validators/NumericVal.md
@@ -5,8 +5,11 @@
Validates whether the input is numeric.
```php
-v::numericVal()->isValid(-12); // true
-v::numericVal()->isValid('135.0'); // true
+v::numericVal()->assert(-12);
+// Validation passes successfully
+
+v::numericVal()->assert('135.0');
+// Validation passes successfully
```
This validator doesn't validate if the input is a valid number, for that
diff --git a/docs/validators/ObjectType.md b/docs/validators/ObjectType.md
index 13e603b8..136816cd 100644
--- a/docs/validators/ObjectType.md
+++ b/docs/validators/ObjectType.md
@@ -5,7 +5,8 @@
Validates whether the input is an [object](http://php.net/types.object).
```php
-v::objectType()->isValid(new stdClass); // true
+v::objectType()->assert(new stdClass);
+// Validation passes successfully
```
## Templates
@@ -55,4 +56,3 @@ See also:
- [ResourceType](ResourceType.md)
- [StringType](StringType.md)
- [StringVal](StringVal.md)
-- [Type](Type.md)
diff --git a/docs/validators/Odd.md b/docs/validators/Odd.md
index 89658e8b..fe5e0bd8 100644
--- a/docs/validators/Odd.md
+++ b/docs/validators/Odd.md
@@ -5,8 +5,11 @@
Validates whether the input is an odd number or not.
```php
-v::odd()->isValid(0); // false
-v::odd()->isValid(3); // true
+v::odd()->assert(0);
+// → 0 must be an odd number
+
+v::odd()->assert(3);
+// Validation passes successfully
```
Using `intVal()` before `odd()` is a best practice.
diff --git a/docs/validators/OneOf.md b/docs/validators/OneOf.md
index ca598a27..ffb4f7c8 100644
--- a/docs/validators/OneOf.md
+++ b/docs/validators/OneOf.md
@@ -6,10 +6,21 @@
Will validate if exactly one inner validator passes.
```php
-v::oneOf(v::digit(), v::alpha())->isValid('AB'); // true
-v::oneOf(v::digit(), v::alpha())->isValid('12'); // true
-v::oneOf(v::digit(), v::alpha())->isValid('AB12'); // false
-v::oneOf(v::digit(), v::alpha())->isValid('*'); // false
+v::oneOf(v::digit(), v::alpha())->assert('AB');
+// Validation passes successfully
+
+v::oneOf(v::digit(), v::alpha())->assert('12');
+// Validation passes successfully
+
+v::oneOf(v::digit(), v::alpha())->assert('AB12');
+// → - "AB12" must pass one of the rules
+// → - "AB12" must contain only digits (0-9)
+// → - "AB12" must contain only letters (a-z)
+
+v::oneOf(v::digit(), v::alpha())->assert('*');
+// → - "*" must pass one of the rules
+// → - "*" must contain only digits (0-9)
+// → - "*" must contain only letters (a-z)
```
The chains above validate if the input is either a digit or an alphabetic
diff --git a/docs/validators/PerfectSquare.md b/docs/validators/PerfectSquare.md
index a59f9116..ce52ca89 100644
--- a/docs/validators/PerfectSquare.md
+++ b/docs/validators/PerfectSquare.md
@@ -5,8 +5,11 @@
Validates whether the input is a perfect square.
```php
-v::perfectSquare()->isValid(25); // true (5*5)
-v::perfectSquare()->isValid(9); // true (3*3)
+v::perfectSquare()->assert(25); // (5*5)
+// Validation passes successfully
+
+v::perfectSquare()->assert(9); // (3*3)
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Pesel.md b/docs/validators/Pesel.md
index 9e349987..29b8e7c7 100644
--- a/docs/validators/Pesel.md
+++ b/docs/validators/Pesel.md
@@ -5,10 +5,17 @@
Validates PESEL (Polish human identification number).
```php
-v::pesel()->isValid('21120209256'); // true
-v::pesel()->isValid('97072704800'); // true
-v::pesel()->isValid('97072704801'); // false
-v::pesel()->isValid('PESEL123456'); // false
+v::pesel()->assert('21120209256');
+// Validation passes successfully
+
+v::pesel()->assert('97072704800');
+// Validation passes successfully
+
+v::pesel()->assert('97072704801');
+// → "97072704801" must be a valid PESEL
+
+v::pesel()->assert('PESEL123456');
+// → "PESEL123456" must be a valid PESEL
```
## Templates
diff --git a/docs/validators/Phone.md b/docs/validators/Phone.md
index 280ce986..bc3650cd 100644
--- a/docs/validators/Phone.md
+++ b/docs/validators/Phone.md
@@ -7,9 +7,14 @@ Validates whether the input is a valid phone number. This validator requires
the `giggsey/libphonenumber-for-php-lite` package.
```php
-v::phone()->isValid('+1 650 253 00 00'); // true
-v::phone('BR')->isValid('+55 11 91111 1111'); // true
-v::phone('BR')->isValid('11 91111 1111'); // false
+v::phone()->assert('+1 650 253 00 00');
+// Validation passes successfully
+
+v::phone('BR')->assert('+55 11 91111 1111');
+// Validation passes successfully
+
+v::phone('BR')->assert('11 91111 1111');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/PhpLabel.md b/docs/validators/PhpLabel.md
index 3fdaef86..3b0a79d2 100644
--- a/docs/validators/PhpLabel.md
+++ b/docs/validators/PhpLabel.md
@@ -9,9 +9,14 @@ Reference:
http://php.net/manual/en/language.variables.basics.php
```php
-v::phpLabel()->isValid('person'); //true
-v::phpLabel()->isValid('foo'); //true
-v::phpLabel()->isValid('4ccess'); //false
+v::phpLabel()->assert('person'); //true
+// Validation passes successfully
+
+v::phpLabel()->assert('foo'); //true
+// Validation passes successfully
+
+v::phpLabel()->assert('4ccess'); //false
+// → "4ccess" must be a valid PHP label
```
## Templates
diff --git a/docs/validators/Pis.md b/docs/validators/Pis.md
index 65586295..85eafeb1 100644
--- a/docs/validators/Pis.md
+++ b/docs/validators/Pis.md
@@ -5,11 +5,20 @@
Validates a Brazilian PIS/NIS number ignoring any non-digit char.
```php
-v::pis()->isValid('120.0340.678-8'); // true
-v::pis()->isValid('120.03406788'); // true
-v::pis()->isValid('120.0340.6788'); // true
-v::pis()->isValid('1.2.0.0.3.4.0.6.7.8.8'); // true
-v::pis()->isValid('12003406788'); // true
+v::pis()->assert('120.0340.678-8');
+// Validation passes successfully
+
+v::pis()->assert('120.03406788');
+// Validation passes successfully
+
+v::pis()->assert('120.0340.6788');
+// Validation passes successfully
+
+v::pis()->assert('1.2.0.0.3.4.0.6.7.8.8');
+// Validation passes successfully
+
+v::pis()->assert('12003406788');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/PolishIdCard.md b/docs/validators/PolishIdCard.md
index 3a4b7de7..a7ee0d4d 100644
--- a/docs/validators/PolishIdCard.md
+++ b/docs/validators/PolishIdCard.md
@@ -5,10 +5,17 @@
Validates whether the input is a Polish identity card (Dowód Osobisty).
```php
-v::polishIdCard()->isValid('AYW036733'); // true
-v::polishIdCard()->isValid('APH505567'); // true
-v::polishIdCard()->isValid('APH 505567'); // false
-v::polishIdCard()->isValid('AYW036731'); // false
+v::polishIdCard()->assert('AYW036733');
+// Validation passes successfully
+
+v::polishIdCard()->assert('APH505567');
+// Validation passes successfully
+
+v::polishIdCard()->assert('APH 505567');
+// → "APH 505567" must be a valid Polish Identity Card number
+
+v::polishIdCard()->assert('AYW036731');
+// → "AYW036731" must be a valid Polish Identity Card number
```
## Templates
diff --git a/docs/validators/PortugueseNif.md b/docs/validators/PortugueseNif.md
index e21c0bec..eff3e090 100644
--- a/docs/validators/PortugueseNif.md
+++ b/docs/validators/PortugueseNif.md
@@ -5,8 +5,11 @@
Validates Portugal's fiscal identification number ([NIF](https://pt.wikipedia.org/wiki/N%C3%BAmero_de_identifica%C3%A7%C3%A3o_fiscal)).
```php
-v::portugueseNif()->isValid('124885446'); // true
-v::portugueseNif()->isValid('220005245'); // false
+v::portugueseNif()->assert('124885446');
+// Validation passes successfully
+
+v::portugueseNif()->assert('220005245');
+// → "220005245" must be a Portuguese NIF
```
## Templates
diff --git a/docs/validators/Positive.md b/docs/validators/Positive.md
index 1ddc2c64..a2c7daab 100644
--- a/docs/validators/Positive.md
+++ b/docs/validators/Positive.md
@@ -5,9 +5,14 @@
Validates whether the input is a positive number.
```php
-v::positive()->isValid(1); // true
-v::positive()->isValid(0); // false
-v::positive()->isValid(-15); // false
+v::positive()->assert(1);
+// Validation passes successfully
+
+v::positive()->assert(0);
+// → 0 must be a positive number
+
+v::positive()->assert(-15);
+// → -15 must be a positive number
```
## Templates
diff --git a/docs/validators/PostalCode.md b/docs/validators/PostalCode.md
index 8e204fc6..9ddbc3ec 100644
--- a/docs/validators/PostalCode.md
+++ b/docs/validators/PostalCode.md
@@ -6,18 +6,30 @@
Validates whether the input is a valid postal code or not.
```php
-v::postalCode('BR')->isValid('02179000'); // true
-v::postalCode('BR')->isValid('02179-000'); // true
-v::postalCode('US')->isValid('02179-000'); // false
-v::postalCode('US')->isValid('55372'); // true
-v::postalCode('PL')->isValid('99-300'); // true
+v::postalCode('BR')->assert('02179000');
+// Validation passes successfully
+
+v::postalCode('BR')->assert('02179-000');
+// Validation passes successfully
+
+v::postalCode('US')->assert('02179-000');
+// → "02179-000" must be a valid postal code on "US"
+
+v::postalCode('US')->assert('55372');
+// Validation passes successfully
+
+v::postalCode('PL')->assert('99-300');
+// Validation passes successfully
```
By default, `PostalCode` won't validate the format (puncts, spaces), unless you pass `$formatted = true`:
```php
-v::postalCode('BR', true)->isValid('02179000'); // false
-v::postalCode('BR', true)->isValid('02179-000'); // true
+v::postalCode('BR', true)->assert('02179000');
+// → "02179000" must be a valid postal code on "BR"
+
+v::postalCode('BR', true)->assert('02179-000');
+// Validation passes successfully
```
Message template for this validator includes `{{countryCode}}`.
diff --git a/docs/validators/PrimeNumber.md b/docs/validators/PrimeNumber.md
index 6de6e3fe..fb07a798 100644
--- a/docs/validators/PrimeNumber.md
+++ b/docs/validators/PrimeNumber.md
@@ -5,7 +5,8 @@
Validates a prime number
```php
-v::primeNumber()->isValid(7); // true
+v::primeNumber()->assert(7);
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Printable.md b/docs/validators/Printable.md
index a3a01855..025c300a 100644
--- a/docs/validators/Printable.md
+++ b/docs/validators/Printable.md
@@ -6,7 +6,8 @@
Similar to `Graph` but accepts whitespace.
```php
-v::printable()->isValid('LMKA0$% _123'); // true
+v::printable()->assert('LMKA0$% _123');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Property.md b/docs/validators/Property.md
index d8f15a38..d2cc55f8 100644
--- a/docs/validators/Property.md
+++ b/docs/validators/Property.md
@@ -9,33 +9,28 @@ $object = new stdClass;
$object->name = 'The Respect Panda';
$object->email = 'therespectpanda@gmail.com';
-v::property('name', v::equals('The Respect Panda'))->isValid($object); // true
+v::property('name', v::equals('The Respect Panda'))->assert($object);
+// Validation passes successfully
-v::property('email', v::email())->isValid($object); // true
+v::property('email', v::email())->assert($object);
+// Validation passes successfully
-v::property('email', v::email()->endsWith('@example.com'))->assert($object); // false
+v::property('email', v::email()->endsWith('@example.com'))->assert($object);
+// → `.email` must end with "@example.com"
```
You can also use `Property` to validate nested objects:
```php
+$object = new stdClass();
$object->address = new stdClass();
$object->address->postalCode = '1017 BS';
v::property(
'address',
- v::property('postalCode', v::postalCode('NL'))
-)->isValid($object); // true
-```
-
-The name of this validator is automatically set to the property name.
-
-```php
-v::property('website', v::url())->assert($object);
-// message: website must be present
-
-v::property('name', v::uppercase())->assert($object);
-// message: name must be uppercase
+ v::property('postalCode', v::postalCode('BR'))
+)->assert($object);
+// → `.address.postalCode` must be a valid postal code on "BR"
```
## Note
diff --git a/docs/validators/PropertyExists.md b/docs/validators/PropertyExists.md
index 6d69a047..56ff2287 100644
--- a/docs/validators/PropertyExists.md
+++ b/docs/validators/PropertyExists.md
@@ -9,9 +9,14 @@ $object = new stdClass;
$object->name = 'The Respect Panda';
$object->email = 'therespectpanda@gmail.com';
-v::propertyExists('name')->isValid($object); // true
-v::propertyExists('email')->isValid($object); // true
-v::propertyExists('website')->isValid($object); // false
+v::propertyExists('name')->assert($object);
+// Validation passes successfully
+
+v::propertyExists('email')->assert($object);
+// Validation passes successfully
+
+v::propertyExists('website')->assert($object);
+// → `.website` must be present
```
## Notes
@@ -44,17 +49,17 @@ When no custom name is set, the path is displayed as `{{name}}`. When a custom n
```php
v::propertyExists('foo')->assert([]);
-// Message: `.foo` must be present
+// → `.foo` must be present
v::named('Custom name', v::propertyExists('foo'))->assert([]);
-// Message: `.foo` (<- Custom name) must be present
+// → `.foo` (<- Custom name) must be present
```
If you want to display only a custom name while checking if a property exists, use [Property](Property.md) with [AlwaysValid](AlwaysValid.md):
```php
v::property('foo', v::named('Custom name', v::alwaysValid()))->assert([]);
-// Message: Custom name must be present
+// → Custom name must be present
```
## Categorization
diff --git a/docs/validators/PropertyOptional.md b/docs/validators/PropertyOptional.md
index 4d74353d..3ced0ad9 100644
--- a/docs/validators/PropertyOptional.md
+++ b/docs/validators/PropertyOptional.md
@@ -9,20 +9,27 @@ $object = new stdClass;
$object->name = 'The Respect Panda';
$object->email = 'therespectpanda@gmail.com';
-v::propertyOptional('name', v::notBlank())->isValid($object); // true
-v::propertyOptional('email', v::email())->isValid($object); // true
+v::propertyOptional('name', v::notBlank())->assert($object);
+// Validation passes successfully
-v::propertyOptional('age', v::intVal())->isValid($object); // true
-v::propertyOptional('website', v::url())->isValid($object); // true
+v::propertyOptional('email', v::email())->assert($object);
+// Validation passes successfully
-v::propertyOptional('name', v::lowercase())->isValid($object); // false
+v::propertyOptional('age', v::intVal())->assert($object);
+// Validation passes successfully
+
+v::propertyOptional('website', v::url())->assert($object);
+// Validation passes successfully
+
+v::propertyOptional('name', v::lowercase())->assert($object);
+// → `.name` must contain only lowercase letters
```
The name of this validator is automatically set to the property name.
```php
v::propertyOptional('email', v::endsWith('@example.com'))->assert($object);
-// message: email must end with "@example.com"
+// → `.email` must end with "@example.com"
```
## Note
@@ -32,8 +39,11 @@ anything that is not an object because it will always pass when it doesn't find
ensure the input is an object, use [ObjectType](ObjectType.md) with it.
```php
-v::propertyOptional('name', v::notBlank())->isValid('Not an object'); // true
-v::objectType()->propertyOptional('name', v::notBlank())->isValid('Not an object'); // false
+v::propertyOptional('name', v::notBlank())->assert('Not an object');
+// Validation passes successfully
+
+v::objectType()->propertyOptional('name', v::notBlank())->assert('Not an object');
+// → "Not an object" must be an object
```
- To only validate if a property exists, use [PropertyExists](PropertyExists.md) instead.
diff --git a/docs/validators/PublicDomainSuffix.md b/docs/validators/PublicDomainSuffix.md
index 118e754e..ff5feeca 100644
--- a/docs/validators/PublicDomainSuffix.md
+++ b/docs/validators/PublicDomainSuffix.md
@@ -5,17 +5,25 @@
Validates whether the input is a public ICANN domain suffix.
```php
-v::publicDomainSuffix->isValid('co.uk'); // true
-v::publicDomainSuffix->isValid('CO.UK'); // true
-v::publicDomainSuffix->isValid('nom.br'); // true
-v::publicDomainSuffix->isValid('invalid.com'); // false
+v::publicDomainSuffix()->assert('co.uk');
+// Validation passes successfully
+
+v::publicDomainSuffix()->assert('CO.UK');
+// Validation passes successfully
+
+v::publicDomainSuffix()->assert('nom.br');
+// Validation passes successfully
+
+v::publicDomainSuffix()->assert('invalid.com');
+// → "invalid.com" must be a public domain suffix
```
This validator will not match top level domains such as `tk`.
If you want to match either, use a combination with `Tld`:
```php
-v::oneOf(v::tld(), v::publicDomainSuffix())->isValid('tk'); // true
+v::oneOf(v::tld(), v::publicDomainSuffix())->assert('tk');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Punct.md b/docs/validators/Punct.md
index c8c14e83..1c8902d5 100644
--- a/docs/validators/Punct.md
+++ b/docs/validators/Punct.md
@@ -6,7 +6,8 @@
Validates whether the input composed by only punctuation characters.
```php
-v::punct()->isValid('&,.;[]'); // true
+v::punct()->assert('&,.;[]');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Readable.md b/docs/validators/Readable.md
index 10fd8fd7..a1c89eed 100644
--- a/docs/validators/Readable.md
+++ b/docs/validators/Readable.md
@@ -5,7 +5,8 @@
Validates if the given data is a file exists and is readable.
```php
-v::readable()->isValid('file.txt'); // true
+v::readable()->assert('/path/to/file.txt');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Regex.md b/docs/validators/Regex.md
index 19cf5a9f..011da71c 100644
--- a/docs/validators/Regex.md
+++ b/docs/validators/Regex.md
@@ -5,7 +5,8 @@
Validates whether the input matches a defined regular expression.
```php
-v::regex('/[a-z]/')->isValid('a'); // true
+v::regex('/[a-z]/')->assert('a');
+// Validation passes successfully
```
Message template for this validator includes `{{regex}}`.
diff --git a/docs/validators/ResourceType.md b/docs/validators/ResourceType.md
index d39f3773..cde695b1 100644
--- a/docs/validators/ResourceType.md
+++ b/docs/validators/ResourceType.md
@@ -5,7 +5,8 @@
Validates whether the input is a [resource](http://php.net/types.resource).
```php
-v::resourceType()->isValid(fopen('/path/to/file.txt', 'w')); // true
+v::resourceType()->assert(fopen('/path/to/file.txt', 'r'));
+// Validation passes successfully
```
## Templates
@@ -49,4 +50,3 @@ See also:
- [PhpLabel](PhpLabel.md)
- [StringType](StringType.md)
- [StringVal](StringVal.md)
-- [Type](Type.md)
diff --git a/docs/validators/Roman.md b/docs/validators/Roman.md
index 65fde04d..d5ab43aa 100644
--- a/docs/validators/Roman.md
+++ b/docs/validators/Roman.md
@@ -5,7 +5,8 @@
Validates if the input is a Roman numeral.
```php
-v::roman()->isValid('IV'); // true
+v::roman()->assert('IV');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/ScalarVal.md b/docs/validators/ScalarVal.md
index 29d230eb..a62df1b4 100644
--- a/docs/validators/ScalarVal.md
+++ b/docs/validators/ScalarVal.md
@@ -5,8 +5,11 @@
Validates whether the input is a scalar value or not.
```php
-v::scalarVal()->isValid([]); // false
-v::scalarVal()->isValid(135.0); // true
+v::scalarVal()->assert([]);
+// → `[]` must be a scalar value
+
+v::scalarVal()->assert(135.0);
+// Validation passes successfully
```
## Templates
@@ -41,4 +44,3 @@ See also:
- [ArrayVal](ArrayVal.md)
- [NumericVal](NumericVal.md)
- [StringType](StringType.md)
-- [Type](Type.md)
diff --git a/docs/validators/Size.md b/docs/validators/Size.md
index 2d9ed71d..769d31da 100644
--- a/docs/validators/Size.md
+++ b/docs/validators/Size.md
@@ -5,9 +5,14 @@
Validates whether the input is a file that is of a certain size or not.
```php
-v::size('KB', v::greaterThan(1))->isValid($filename);
-v::size('MB', v::between(1, 2))->isValid($filename);
-v::size('GB', v::lessThan(1))->isValid($filename);
+v::size('KB', v::greaterThan(1))->assert('/path/to/file');
+// Validation passes successfully
+
+v::size('MB', v::between(1, 2))->assert('/path/to/file');
+// → The size in megabytes of "/path/to/file" must be between 1 and 2
+
+v::size('GB', v::lessThan(1))->assert('/path/to/file');
+// Validation passes successfully
```
Accepted data storage units are `B`, `KB`, `MB`, `GB`, `TB`, `PB`, `EB`, `ZB`, and `YB`.
@@ -42,11 +47,11 @@ Used when the input is not a valid file path, a `SplFileInfo` object, or a PSR-7
The template serves as a prefix to the template of the inner validator.
```php
-v::size('MB', v::equals(2))->assert('filename.txt')
-// Message: The size in megabytes of "filename.txt" must be equal to 2
+v::size('MB', v::equals(2))->assert('/path/to/file');
+// → The size in megabytes of "/path/to/file" must be equal to 2
-v::size('KB', v::not(v::equals(56)))->assert('filename.txt')
-// Message: The size in kilobytes of "filename.txt" must not be equal to 56
+v::size('KB', v::not(v::equals(56)))->assert('/path/to/file');
+// Validation passes successfully
```
## Template placeholders
diff --git a/docs/validators/Slug.md b/docs/validators/Slug.md
index 0d98fb1a..cb400726 100644
--- a/docs/validators/Slug.md
+++ b/docs/validators/Slug.md
@@ -5,9 +5,14 @@
Validates whether the input is a valid slug.
```php
-v::slug()->isValid('my-wordpress-title'); // true
-v::slug()->isValid('my-wordpress--title'); // false
-v::slug()->isValid('my-wordpress-title-'); // false
+v::slug()->assert('my-wordpress-title');
+// Validation passes successfully
+
+v::slug()->assert('my-wordpress--title');
+// → "my-wordpress--title" must be a valid slug
+
+v::slug()->assert('my-wordpress-title-');
+// → "my-wordpress-title-" must be a valid slug
```
## Templates
diff --git a/docs/validators/Sorted.md b/docs/validators/Sorted.md
index ea89b862..e46f807f 100644
--- a/docs/validators/Sorted.md
+++ b/docs/validators/Sorted.md
@@ -5,30 +5,40 @@
Validates whether the input is sorted in a certain order or not.
```php
-v::sorted('ASC')->isValid([1, 2, 3]); // true
-v::sorted('ASC')->isValid('ABC'); // true
-v::sorted('DESC')->isValid([3, 2, 1]); // true
-v::sorted('ASC')->isValid([]); // true
-v::sorted('ASC')->isValid([1]); // true
+v::sorted('ASC')->assert([1, 2, 3]);
+// Validation passes successfully
+
+v::sorted('ASC')->assert('ABC');
+// Validation passes successfully
+
+v::sorted('DESC')->assert([3, 2, 1]);
+// Validation passes successfully
+
+v::sorted('ASC')->assert([]);
+// Validation passes successfully
+
+v::sorted('ASC')->assert([1]);
+// Validation passes successfully
```
You can also combine [Call](Call.md) to create custom validations:
```php
v::call(
- static function (array $input): array {
- return array_column($input, 'key');
- },
+ fn (array $input): array => array_column($input, 'key'),
v::sorted('ASC')
- )->isValid([
+ )->assert([
['key' => 1],
['key' => 5],
['key' => 9],
- ]); // true
+ ]);
+// Validation passes successfully
-v::call('strval', v::sorted('DESC'))->isValid(4321); // true
+v::call('strval', v::sorted('DESC'))->assert(4321);
+// Validation passes successfully
-v::call('iterator_to_array', v::sorted())->isValid(new ArrayIterator([1, 7, 4])); // false
+v::call('iterator_to_array', v::sorted('ASC'))->assert(new ArrayIterator([1, 7, 4]));
+// → `[1, 7, 4]` must be sorted in ascending order
```
## Templates
diff --git a/docs/validators/Space.md b/docs/validators/Space.md
index 02117c06..4877134f 100644
--- a/docs/validators/Space.md
+++ b/docs/validators/Space.md
@@ -6,7 +6,8 @@
Validates whether the input contains only whitespaces characters.
```php
-v::space()->isValid(' '); // true
+v::space()->assert(' ');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Spaced.md b/docs/validators/Spaced.md
index 13fa356e..4a4d5c77 100644
--- a/docs/validators/Spaced.md
+++ b/docs/validators/Spaced.md
@@ -5,15 +5,23 @@
Validates if a string contains at least one whitespace (spaces, tabs, or line breaks);
```php
-v::spaced()->isValid('foo bar'); // true
-v::spaced()->isValid("foo\nbar"); // true
+v::spaced()->assert('foo bar');
+// Validation passes successfully
+
+v::spaced()->assert("foo\nbar");
+// Validation passes successfully
```
This is most useful when inverting the validator as `notSpaced()`, and chaining with other validators such as [Alnum](Alnum.md) or [Alpha](Alpha.md) to ensure that a string contains no whitespace characters:
```php
-v::notSpaced()->alnum()->isValid('username'); // true
-v::notSpaced()->alnum()->isValid('user name'); // false
+v::notSpaced()->alnum()->assert('username');
+// Validation passes successfully
+
+v::notSpaced()->alnum()->assert('user name');
+// → - "user name" must pass all the rules
+// → - "user name" must not contain whitespaces
+// → - "user name" must contain only letters (a-z) and digits (0-9)
```
## Templates
diff --git a/docs/validators/StartsWith.md b/docs/validators/StartsWith.md
index b9fbbbf1..e28f3c8b 100644
--- a/docs/validators/StartsWith.md
+++ b/docs/validators/StartsWith.md
@@ -11,13 +11,15 @@ if the value is at the beginning of the input.
For strings:
```php
-v::startsWith('lorem')->isValid('lorem ipsum'); // true
+v::startsWith('lorem')->assert('lorem ipsum');
+// Validation passes successfully
```
For arrays:
```php
-v::startsWith('lorem')->isValid(['lorem', 'ipsum']); // true
+v::startsWith('lorem')->assert(['lorem', 'ipsum']);
+// Validation passes successfully
```
`true` may be passed as a parameter to indicate identical comparison
diff --git a/docs/validators/StringType.md b/docs/validators/StringType.md
index 7817612d..2e98f326 100644
--- a/docs/validators/StringType.md
+++ b/docs/validators/StringType.md
@@ -5,7 +5,8 @@
Validates whether the type of an input is string or not.
```php
-v::stringType()->isValid('hi'); // true
+v::stringType()->assert('hi');
+// Validation passes successfully
```
## Templates
@@ -52,4 +53,3 @@ See also:
- [ResourceType](ResourceType.md)
- [ScalarVal](ScalarVal.md)
- [StringVal](StringVal.md)
-- [Type](Type.md)
diff --git a/docs/validators/StringVal.md b/docs/validators/StringVal.md
index 6fa2ecb4..222b7587 100644
--- a/docs/validators/StringVal.md
+++ b/docs/validators/StringVal.md
@@ -5,13 +5,26 @@
Validates whether the input can be used as a string.
```php
-v::stringVal()->isValid('6'); // true
-v::stringVal()->isValid('String'); // true
-v::stringVal()->isValid(1.0); // true
-v::stringVal()->isValid(42); // true
-v::stringVal()->isValid(false); // true
-v::stringVal()->isValid(true); // true
-v::stringVal()->isValid(new ClassWithToString()); // true if ClassWithToString implements `__toString`
+v::stringVal()->assert('6');
+// Validation passes successfully
+
+v::stringVal()->assert('String');
+// Validation passes successfully
+
+v::stringVal()->assert(1.0);
+// Validation passes successfully
+
+v::stringVal()->assert(42);
+// Validation passes successfully
+
+v::stringVal()->assert(false);
+// Validation passes successfully
+
+v::stringVal()->assert(true);
+// Validation passes successfully
+
+v::stringVal()->assert(new ClassWithToString());
+// Validation passes successfully
```
## Templates
@@ -53,4 +66,3 @@ See also:
- [ObjectType](ObjectType.md)
- [ResourceType](ResourceType.md)
- [StringType](StringType.md)
-- [Type](Type.md)
diff --git a/docs/validators/SubdivisionCode.md b/docs/validators/SubdivisionCode.md
index e38cb5bc..359c6b26 100644
--- a/docs/validators/SubdivisionCode.md
+++ b/docs/validators/SubdivisionCode.md
@@ -9,8 +9,11 @@ The `$countryCode` must be a country in [ISO 3166-1 alpha-2][] format.
**This validator requires [sokil/php-isocodes][] and [php-isocodes-db-only][] to be installed.**
```php
-v::subdivisionCode('BR')->isValid('SP'); // true
-v::subdivisionCode('US')->isValid('CA'); // true
+v::subdivisionCode('BR')->assert('SP');
+// Validation passes successfully
+
+v::subdivisionCode('US')->assert('CA');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Subset.md b/docs/validators/Subset.md
index 4c7dd125..2fea1a00 100644
--- a/docs/validators/Subset.md
+++ b/docs/validators/Subset.md
@@ -5,8 +5,11 @@
Validates whether the input is a subset of a given value.
```php
-v::subset([1, 2, 3])->isValid([1, 2]); // true
-v::subset([1, 2])->isValid([1, 2, 3]); // false
+v::subset([1, 2, 3])->assert([1, 2]);
+// Validation passes successfully
+
+v::subset([1, 2])->assert([1, 2, 3]);
+// → `[1, 2, 3]` must be subset of `[1, 2]`
```
## Templates
diff --git a/docs/validators/SymbolicLink.md b/docs/validators/SymbolicLink.md
index 16d2c6fc..65629c0d 100644
--- a/docs/validators/SymbolicLink.md
+++ b/docs/validators/SymbolicLink.md
@@ -5,9 +5,14 @@
Validates if the given input is a symbolic link.
```php
-v::symbolicLink()->isValid('/path/of/valid/symbolic/link'); // true
-v::symbolicLink()->isValid(new SplFileInfo('/path/of/valid/symbolic/link)); // true
-v::symbolicLink()->isValid(new SplFileObject('/path/of/valid/symbolic/link')); // true
+v::symbolicLink()->assert('/path/to/symbolic-link');
+// Validation passes successfully
+
+v::symbolicLink()->assert(new SplFileInfo('/path/to/file'));
+// → `SplFileInfo { __toString() => "/path/to/file" }` must be a symbolic link
+
+v::symbolicLink()->assert(new SplFileObject('/path/to/file'));
+// → `SplFileObject { current() => "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque nec enim vitae ve ... }` must be a symbolic link
```
## Templates
diff --git a/docs/validators/Templated.md b/docs/validators/Templated.md
index 678e12dd..0fb2f321 100644
--- a/docs/validators/Templated.md
+++ b/docs/validators/Templated.md
@@ -7,14 +7,14 @@ Defines a validator with a custom message template.
```php
v::templated('You must provide a valid email to signup', v::email())->assert('not an email');
-// Message: You must provide a valid email to signup
+// → You must provide a valid email to signup
v::templated(
'The author of the page {{title}} is empty, please fill it up.',
v::notBlank(),
['title' => 'Feature Guide']
)->assert('');
-// Message: The author of the page "Feature Guide" is empty, please fill it up.
+// → The author of the page "Feature Guide" is empty, please fill it up.
```
This validator can be also useful when you're using [Attributes](Attributes.md) and want a custom template for a specific property.
diff --git a/docs/validators/Time.md b/docs/validators/Time.md
index acec3468..0a139c1b 100644
--- a/docs/validators/Time.md
+++ b/docs/validators/Time.md
@@ -23,15 +23,29 @@ allowed:
When a `$format` is not given its default value is `H:i:s`.
```php
-v::time()->isValid('00:00:00'); // true
-v::time()->isValid('23:20:59'); // true
-v::time('H:i')->isValid('23:59'); // true
-v::time('g:i A')->isValid('8:13 AM'); // true
-v::time('His')->isValid(232059); // true
+v::time()->assert('00:00:00');
+// Validation passes successfully
-v::time()->isValid('24:00:00'); // false
-v::time()->isValid(new DateTime()); // false
-v::time()->isValid(new DateTimeImmutable()); // false
+v::time()->assert('23:20:59');
+// Validation passes successfully
+
+v::time('H:i')->assert('23:59');
+// Validation passes successfully
+
+v::time('g:i A')->assert('8:13 AM');
+// Validation passes successfully
+
+v::time('His')->assert(232059);
+// Validation passes successfully
+
+v::time()->assert('24:00:00');
+// → "24:00:00" must be a valid time in the format "23:59:59"
+
+v::time()->assert(new DateTime());
+// → `DateTime { 2024-01-01T12:00:00+00:00 }` must be a valid time in the format "23:59:59"
+
+v::time()->assert(new DateTimeImmutable());
+// → `DateTimeImmutable { 2024-01-01T12:00:00+00:00 }` must be a valid time in the format "23:59:59"
```
## Templates
diff --git a/docs/validators/Tld.md b/docs/validators/Tld.md
index c633791b..bdb9be01 100644
--- a/docs/validators/Tld.md
+++ b/docs/validators/Tld.md
@@ -5,10 +5,17 @@
Validates whether the input is a top-level domain.
```php
-v::tld()->isValid('com'); // true
-v::tld()->isValid('ly'); // true
-v::tld()->isValid('org'); // true
-v::tld()->isValid('COM'); // true
+v::tld()->assert('com');
+// Validation passes successfully
+
+v::tld()->assert('ly');
+// Validation passes successfully
+
+v::tld()->assert('org');
+// Validation passes successfully
+
+v::tld()->assert('COM');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/TrueVal.md b/docs/validators/TrueVal.md
index d72bda4d..0575216e 100644
--- a/docs/validators/TrueVal.md
+++ b/docs/validators/TrueVal.md
@@ -5,14 +5,29 @@
Validates if a value is considered as `true`.
```php
-v::trueVal()->isValid(true); // true
-v::trueVal()->isValid(1); // true
-v::trueVal()->isValid('1'); // true
-v::trueVal()->isValid('true'); // true
-v::trueVal()->isValid('on'); // true
-v::trueVal()->isValid('yes'); // true
-v::trueVal()->isValid('0.5'); // false
-v::trueVal()->isValid('2'); // false
+v::trueVal()->assert(true);
+// Validation passes successfully
+
+v::trueVal()->assert(1);
+// Validation passes successfully
+
+v::trueVal()->assert('1');
+// Validation passes successfully
+
+v::trueVal()->assert('true');
+// Validation passes successfully
+
+v::trueVal()->assert('on');
+// Validation passes successfully
+
+v::trueVal()->assert('yes');
+// Validation passes successfully
+
+v::trueVal()->assert('0.5');
+// → "0.5" must evaluate to `true`
+
+v::trueVal()->assert('2');
+// → "2" must evaluate to `true`
```
## Templates
diff --git a/docs/validators/Undef.md b/docs/validators/Undef.md
index f78d930d..16517b78 100644
--- a/docs/validators/Undef.md
+++ b/docs/validators/Undef.md
@@ -7,26 +7,54 @@ Validates if the given input is undefined. By _undefined_ we consider `null` or
We recommend you to check [Comparing empty values](../comparing-empty-values.md) for more details.
```php
-v::undef()->isValid(''); // true
-v::undef()->isValid(null); // true
+v::undef()->assert('');
+// Validation passes successfully
+
+v::undef()->assert(null);
+// Validation passes successfully
```
Other values similar to _undefined_ values are considered _defined_:
```php
-v::undef()->isValid([]); // false
-v::undef()->isValid(' '); // false
-v::undef()->isValid(0); // false
-v::undef()->isValid('0'); // false
-v::undef()->isValid('0.0'); // false
-v::undef()->isValid(false); // false
-v::undef()->isValid(['']); // false
-v::undef()->isValid([' ']); // false
-v::undef()->isValid([0]); // false
-v::undef()->isValid(['0']); // false
-v::undef()->isValid([false]); // false
-v::undef()->isValid([[''], [0]]); // false
-v::undef()->isValid(new stdClass()); // false
+v::undef()->assert([]);
+// → `[]` must be undefined
+
+v::undef()->assert(' ');
+// → " " must be undefined
+
+v::undef()->assert(0);
+// → 0 must be undefined
+
+v::undef()->assert('0');
+// → "0" must be undefined
+
+v::undef()->assert('0.0');
+// → "0.0" must be undefined
+
+v::undef()->assert(false);
+// → `false` must be undefined
+
+v::undef()->assert(['']);
+// → `[""]` must be undefined
+
+v::undef()->assert([' ']);
+// → `[" "]` must be undefined
+
+v::undef()->assert([0]);
+// → `[0]` must be undefined
+
+v::undef()->assert(['0']);
+// → `["0"]` must be undefined
+
+v::undef()->assert([false]);
+// → `[false]` must be undefined
+
+v::undef()->assert([[''], [0]]);
+// → `[[""], [0]]` must be undefined
+
+v::undef()->assert(new stdClass());
+// → `stdClass {}` must be undefined
```
## Templates
diff --git a/docs/validators/UndefOr.md b/docs/validators/UndefOr.md
index 1b04b05c..e445b707 100644
--- a/docs/validators/UndefOr.md
+++ b/docs/validators/UndefOr.md
@@ -9,11 +9,17 @@ This validator can be particularly useful when validating form fields.
## Usage
```php
-v::undefOr(v::alpha())->isValid(''); // true
-v::undefOr(v::digit())->isValid(null); // true
+v::undefOr(v::alpha())->assert('');
+// Validation passes successfully
-v::undefOr(v::alpha())->isValid('username'); // true
-v::undefOr(v::alpha())->isValid('has1number'); // false
+v::undefOr(v::digit())->assert(null);
+// Validation passes successfully
+
+v::undefOr(v::alpha())->assert('username');
+// Validation passes successfully
+
+v::undefOr(v::alpha())->assert('has1number');
+// → "has1number" must contain only letters (a-z) or must be undefined
```
## Prefix
@@ -21,8 +27,11 @@ v::undefOr(v::alpha())->isValid('has1number'); // false
For convenience, you can use the `undefOr` as a prefix to any validator:
```php
-v::undefOrEmail()->isValid('not an email'); // false
-v::undefOrBetween(1, 3)->isValid(2); // true
+v::undefOrEmail()->assert('not an email');
+// → "not an email" must be a valid email address or must be undefined
+
+v::undefOrBetween(1, 3)->assert(2);
+// Validation passes successfully
```
## Templates
@@ -40,10 +49,10 @@ The template serves as a suffix to the template of the inner validator.
```php
v::undefOr(v::alpha())->assert('has1number');
-// "has1number" must contain only letters (a-z) or must be undefined
+// → "has1number" must contain only letters (a-z) or must be undefined
v::not(v::undefOr(v::alpha()))->assert("alpha");
-// "alpha" must not contain letters (a-z) and must not be undefined
+// → "alpha" must not contain letters (a-z) and must not be undefined
```
## Template placeholders
diff --git a/docs/validators/Unique.md b/docs/validators/Unique.md
index f1bdb78e..6155ac6e 100644
--- a/docs/validators/Unique.md
+++ b/docs/validators/Unique.md
@@ -5,10 +5,17 @@
Validates whether the input array contains only unique values.
```php
-v::unique()->isValid([]); // true
-v::unique()->isValid([1, 2, 3]); // true
-v::unique()->isValid([1, 2, 2, 3]); // false
-v::unique()->isValid([1, 2, 3, 1]); // false
+v::unique()->assert([]);
+// Validation passes successfully
+
+v::unique()->assert([1, 2, 3]);
+// Validation passes successfully
+
+v::unique()->assert([1, 2, 2, 3]);
+// → `[1, 2, 2, 3]` must not contain duplicates
+
+v::unique()->assert([1, 2, 3, 1]);
+// → `[1, 2, 3, 1]` must not contain duplicates
```
## Templates
diff --git a/docs/validators/Uploaded.md b/docs/validators/Uploaded.md
index 31a143e8..601d382e 100644
--- a/docs/validators/Uploaded.md
+++ b/docs/validators/Uploaded.md
@@ -5,7 +5,8 @@
Validates if the given data is a file that was uploaded via HTTP POST.
```php
-v::uploaded()->isValid('/path/of/an/uploaded/file'); // true
+v::uploaded()->assert('/path/of/an/uploaded/file');
+// → "/path/of/an/uploaded/file" must be an uploaded file
```
## Templates
diff --git a/docs/validators/Uppercase.md b/docs/validators/Uppercase.md
index 1475861a..b0a608f1 100644
--- a/docs/validators/Uppercase.md
+++ b/docs/validators/Uppercase.md
@@ -5,7 +5,8 @@
Validates whether the characters in the input are uppercase.
```php
-v::uppercase()->isValid('W3C'); // true
+v::uppercase()->assert('W3C');
+// Validation passes successfully
```
This validator does not validate if the input a numeric value, so `123` and `%` will
@@ -13,9 +14,14 @@ be valid. Please add more validations to the chain if you want to refine your
validation.
```php
-v::not(v::numericVal())->uppercase()->isValid('42'); // false
-v::alnum()->uppercase()->isValid('#$%!'); // false
-v::not(v::numericVal())->alnum()->uppercase()->isValid('W3C'); // true
+v::not(v::numericVal())->uppercase()->assert('42');
+// → "42" must not be a numeric value
+
+v::alnum()->uppercase()->assert('#$%!');
+// → "#$%!" must contain only letters (a-z) and digits (0-9)
+
+v::not(v::numericVal())->alnum()->uppercase()->assert('W3C');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Url.md b/docs/validators/Url.md
index 7ad6f805..1e1f7689 100644
--- a/docs/validators/Url.md
+++ b/docs/validators/Url.md
@@ -5,11 +5,20 @@
Validates whether the input is a URL.
```php
-v::url()->isValid('http://example.com'); // true
-v::url()->isValid('https://www.youtube.com/watch?v=6FOUqQt3Kg0'); // true
-v::url()->isValid('ldap://[::1]'); // true
-v::url()->isValid('mailto:john.doe@example.com'); // true
-v::url()->isValid('news:new.example.com'); // true
+v::url()->assert('http://example.com');
+// Validation passes successfully
+
+v::url()->assert('https://www.youtube.com/watch?v=6FOUqQt3Kg0');
+// Validation passes successfully
+
+v::url()->assert('ldap://[::1]');
+// Validation passes successfully
+
+v::url()->assert('mailto:john.doe@example.com');
+// Validation passes successfully
+
+v::url()->assert('news:new.example.com');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Uuid.md b/docs/validators/Uuid.md
index 89931dbc..2b06d116 100644
--- a/docs/validators/Uuid.md
+++ b/docs/validators/Uuid.md
@@ -7,13 +7,26 @@ Validates whether the input is a valid UUID. It also supports validation of
specific versions 1 to 8.
```php
-v::uuid()->isValid('Hello World!'); // false
-v::uuid()->isValid('eb3115e5-bd16-4939-ab12-2b95745a30f3'); // true
-v::uuid()->isValid('eb3115e5bd164939ab122b95745a30f3'); // true
-v::uuid(1)->isValid('eb3115e5-bd16-4939-ab12-2b95745a30f3'); // false
-v::uuid(4)->isValid('eb3115e5-bd16-4939-ab12-2b95745a30f3'); // true
-v::uuid(8)->isValid('00112233-4455-8677-8899-aabbccddeeff'); // true
-v::uuid(4)->isValid(new \Ramsey\Uuid\Uuid::fromString('eb3115e5-bd16-4939-ab12-2b95745a30f3')); // true
+v::uuid()->assert('Hello World!');
+// → "Hello World!" must be a valid UUID
+
+v::uuid()->assert('eb3115e5-bd16-4939-ab12-2b95745a30f3');
+// Validation passes successfully
+
+v::uuid()->assert('eb3115e5bd164939ab122b95745a30f3');
+// Validation passes successfully
+
+v::uuid(1)->assert('eb3115e5-bd16-4939-ab12-2b95745a30f3');
+// → "eb3115e5-bd16-4939-ab12-2b95745a30f3" must be a valid UUID version 1
+
+v::uuid(4)->assert('eb3115e5-bd16-4939-ab12-2b95745a30f3');
+// Validation passes successfully
+
+v::uuid(8)->assert('00112233-4455-8677-8899-aabbccddeeff');
+// Validation passes successfully
+
+v::uuid(4)->assert(\Ramsey\Uuid\Uuid::fromString('eb3115e5-bd16-4939-ab12-2b95745a30f3'));
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/Version.md b/docs/validators/Version.md
index 24f54438..827ca6fa 100644
--- a/docs/validators/Version.md
+++ b/docs/validators/Version.md
@@ -5,7 +5,8 @@
Validates version numbers using Semantic Versioning.
```php
-v::version()->isValid('1.0.0');
+v::version()->assert('1.0.0');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/VideoUrl.md b/docs/validators/VideoUrl.md
index 36c29a9f..ebdabe4a 100644
--- a/docs/validators/VideoUrl.md
+++ b/docs/validators/VideoUrl.md
@@ -6,23 +6,50 @@
Validates if the input is a video URL value.
```php
-v::videoUrl()->isValid('https://player.vimeo.com/video/71787467'); // true
-v::videoUrl()->isValid('https://vimeo.com/71787467'); // true
-v::videoUrl()->isValid('https://www.youtube.com/embed/netHLn9TScY'); // true
-v::videoUrl()->isValid('https://www.youtube.com/watch?v=netHLn9TScY'); // true
-v::videoUrl()->isValid('https://youtu.be/netHLn9TScY'); // true
-v::videoUrl()->isValid('https://www.twitch.tv/videos/320689092'); // true
-v::videoUrl()->isValid('https://clips.twitch.tv/BitterLazyMangetoutHumbleLife'); // true
+v::videoUrl()->assert('https://player.vimeo.com/video/71787467');
+// Validation passes successfully
-v::videoUrl('youtube')->isValid('https://www.youtube.com/watch?v=netHLn9TScY'); // true
-v::videoUrl('vimeo')->isValid('https://vimeo.com/71787467'); // true
-v::videoUrl('twitch')->isValid('https://www.twitch.tv/videos/320689092'); // true
-v::videoUrl('twitch')->isValid('https://clips.twitch.tv/BitterLazyMangetoutHumbleLife'); // true
+v::videoUrl()->assert('https://vimeo.com/71787467');
+// Validation passes successfully
-v::videoUrl()->isValid('https://youtube.com'); // false
-v::videoUrl('youtube')->isValid('https://vimeo.com/71787467'); // false
-v::videoUrl('twitch')->isValid('https://clips.twitch.tv/videos/90210'); // false
-v::videoUrl('twitch')->isValid('https://twitch.tv/TakeTeaAndNoTea'); // false
+v::videoUrl()->assert('https://www.youtube.com/embed/netHLn9TScY');
+// Validation passes successfully
+
+v::videoUrl()->assert('https://www.youtube.com/watch?v=netHLn9TScY');
+// Validation passes successfully
+
+v::videoUrl()->assert('https://youtu.be/netHLn9TScY');
+// Validation passes successfully
+
+v::videoUrl()->assert('https://www.twitch.tv/videos/320689092');
+// Validation passes successfully
+
+v::videoUrl()->assert('https://clips.twitch.tv/BitterLazyMangetoutHumbleLife');
+// Validation passes successfully
+
+v::videoUrl('youtube')->assert('https://www.youtube.com/watch?v=netHLn9TScY');
+// Validation passes successfully
+
+v::videoUrl('vimeo')->assert('https://vimeo.com/71787467');
+// Validation passes successfully
+
+v::videoUrl('twitch')->assert('https://www.twitch.tv/videos/320689092');
+// Validation passes successfully
+
+v::videoUrl('twitch')->assert('https://clips.twitch.tv/BitterLazyMangetoutHumbleLife');
+// Validation passes successfully
+
+v::videoUrl()->assert('https://youtube.com');
+// → "https://youtube.com" must be a valid video URL
+
+v::videoUrl('youtube')->assert('https://vimeo.com/71787467');
+// → "https://vimeo.com/71787467" must be a valid youtube video URL
+
+v::videoUrl('twitch')->assert('https://clips.twitch.tv/videos/90210');
+// → "https://clips.twitch.tv/videos/90210" must be a valid twitch video URL
+
+v::videoUrl('twitch')->assert('https://twitch.tv/TakeTeaAndNoTea');
+// → "https://twitch.tv/TakeTeaAndNoTea" must be a valid twitch video URL
```
The services accepted are:
diff --git a/docs/validators/Vowel.md b/docs/validators/Vowel.md
index 1378b614..f9dfddce 100644
--- a/docs/validators/Vowel.md
+++ b/docs/validators/Vowel.md
@@ -6,7 +6,8 @@
Validates whether the input contains only vowels.
```php
-v::vowel()->isValid('aei'); // true
+v::vowel()->assert('aei');
+// Validation passes successfully
```
## Templates
diff --git a/docs/validators/When.md b/docs/validators/When.md
index 62134583..68612b54 100644
--- a/docs/validators/When.md
+++ b/docs/validators/When.md
@@ -9,11 +9,17 @@ When the `$if` validates, returns validation for `$then`.
When the `$if` doesn't validate, returns validation for `$else`, if defined.
```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::when(v::intVal(), v::positive(), v::notBlank())->assert(1);
+// Validation passes successfully
-v::when(v::intVal(), v::positive(), v::notBlank())->isValid(-1); // false
-v::when(v::intVal(), v::positive(), v::notBlank())->isValid(''); // false
+v::when(v::intVal(), v::positive(), v::notBlank())->assert('non-blank string');
+// Validation passes successfully
+
+v::when(v::intVal(), v::positive(), v::notBlank())->assert(-1);
+// → -1 must be a positive number
+
+v::when(v::intVal(), v::positive(), v::notBlank())->assert('');
+// → "" must not be blank
```
In the sample above, if `$input` is an integer, then it must be positive.
diff --git a/docs/validators/Writable.md b/docs/validators/Writable.md
index 95851859..119b1769 100644
--- a/docs/validators/Writable.md
+++ b/docs/validators/Writable.md
@@ -5,7 +5,11 @@
Validates if the given input is writable file.
```php
-v::writable()->isValid('file.txt'); // true
+v::writable()->assert('/path/to/file');
+// Validation passes successfully
+
+v::writable()->assert('/path/to/non-writable');
+// → "/path/to/non-writable" must be writable
```
## Templates
diff --git a/docs/validators/Xdigit.md b/docs/validators/Xdigit.md
index b3909593..d56aa81f 100644
--- a/docs/validators/Xdigit.md
+++ b/docs/validators/Xdigit.md
@@ -6,13 +6,15 @@
Validates whether the input is an hexadecimal number or not.
```php
-v::xdigit()->isValid('abc123'); // true
+v::xdigit()->assert('abc123');
+// Validation passes successfully
```
Notice, however, that it doesn't accept strings starting with 0x:
```php
-v::xdigit()->isValid('0x1f'); // false
+v::xdigit()->assert('0x1f');
+// → "0x1f" must only contain hexadecimal digits
```
## Templates
diff --git a/src-dev/Markdown/Linters/AssertionMessageLinter.php b/src-dev/Markdown/Linters/AssertionMessageLinter.php
new file mode 100644
index 00000000..6cf0b3ab
--- /dev/null
+++ b/src-dev/Markdown/Linters/AssertionMessageLinter.php
@@ -0,0 +1,361 @@
+
+ * SPDX-License-Identifier: MIT
+ */
+
+declare(strict_types=1);
+
+namespace Respect\Dev\Markdown\Linters;
+
+use ArrayObject;
+use DateTimeImmutable;
+use PhpParser\Node;
+use PhpParser\Node\Expr\MethodCall;
+use PhpParser\Node\Expr\StaticCall;
+use PhpParser\Node\Identifier;
+use PhpParser\Node\Name;
+use PhpParser\Node\Stmt\Expression;
+use PhpParser\ParserFactory;
+use PhpParser\PrettyPrinter\Standard as PrettyPrinter;
+use Respect\Dev\Markdown\Content;
+use Respect\Dev\Markdown\File;
+use Respect\Dev\Markdown\Linter;
+use Respect\Validation\Exceptions\ValidationException;
+use Throwable;
+use UnexpectedValueException;
+
+use function array_keys;
+use function array_merge;
+use function array_pop;
+use function array_slice;
+use function array_values;
+use function count;
+use function date;
+use function explode;
+use function implode;
+use function preg_match;
+use function sprintf;
+use function str_contains;
+use function str_ends_with;
+use function str_replace;
+use function str_starts_with;
+use function substr;
+use function substr_count;
+use function trim;
+
+use const PHP_EOL;
+
+final readonly class AssertionMessageLinter implements Linter
+{
+ private const string FIXED_DATETIME = '2024-01-01 12:00:00+00:00';
+
+ public function lint(File $file): File
+ {
+ if (!str_contains($file->filename, '/validators/') || !str_ends_with($file->filename, '.md')) {
+ return $file;
+ }
+
+ $processedContent = $this->processContent($file->content);
+
+ if ($file->content->build() === $processedContent->build()) {
+ return $file;
+ }
+
+ return $file->withContent($processedContent);
+ }
+
+ private function processContent(Content $content): Content
+ {
+ $context = new ArrayObject();
+ $newContent = new Content();
+ $inCodeBlock = false;
+ $currentCodeBlock = [];
+
+ foreach ($content as $line) {
+ if (str_starts_with($line, '```php')) {
+ $inCodeBlock = true;
+ $currentCodeBlock = [$line];
+ continue;
+ }
+
+ if ($inCodeBlock && str_starts_with($line, '```')) {
+ $currentCodeBlock[] = $line;
+ $processedLines = $this->processCodeBlock($currentCodeBlock, $context);
+
+ foreach ($processedLines as $processedLine) {
+ $newContent->raw($processedLine);
+ }
+
+ $inCodeBlock = false;
+ $currentCodeBlock = [];
+ continue;
+ }
+
+ if ($inCodeBlock) {
+ $currentCodeBlock[] = $line;
+ continue;
+ }
+
+ $newContent->raw($line);
+ }
+
+ return $newContent;
+ }
+
+ /**
+ * @param string[] $lines
+ *
+ * @return string[]
+ */
+ private function processCodeBlock(array $lines, ArrayObject $context): array
+ {
+ $openingLine = $lines[0];
+ $closingLine = $lines[count($lines) - 1];
+ $codeLines = array_slice($lines, 1, -1);
+ $code = implode("\n", $codeLines);
+
+ $processedCodeLines = $this->processCode($code, $context);
+
+ return [
+ $openingLine,
+ ...$processedCodeLines,
+ $closingLine,
+ ];
+ }
+
+ /** @return string[] */
+ private function processCode(string $code, ArrayObject $context): array
+ {
+ $cleanedCode = $this->stripOutputComments($code);
+
+ $parser = (new ParserFactory())->createForNewestSupportedVersion();
+ $printer = new PrettyPrinter();
+
+ $phpTagLength = 6;
+ $fullCode = 'parse($fullCode);
+ } catch (Throwable $exception) {
+ throw new UnexpectedValueException(sprintf('Failed to parse code block: %s', $code), 0, $exception);
+ }
+
+ $processedLines = [];
+ $lastEndPos = $phpTagLength;
+ $lastWasAssertion = false;
+
+ foreach ($statements as $statement) {
+ $startPos = $statement->getStartFilePos();
+ $endPos = $statement->getEndFilePos();
+
+ if ($startPos > $lastEndPos && !$lastWasAssertion) {
+ $between = substr($fullCode, $lastEndPos, $startPos - $lastEndPos);
+ $newlineCount = substr_count($between, "\n");
+ for ($i = 1; $i < $newlineCount; $i++) {
+ $processedLines[] = '';
+ }
+ }
+
+ if ($startPos >= 0 && $endPos >= 0) {
+ $statementCode = substr($fullCode, $startPos, $endPos - $startPos + 1);
+ $restOfCode = substr($fullCode, $endPos + 1);
+ if (preg_match('/^(\h*\/\/[^\n]*)/u', $restOfCode, $matches)) {
+ $statementCode .= $matches[1];
+ }
+ } else {
+ $statementCode = $printer->prettyPrint([$statement]);
+ }
+
+ $isAssertion = $this->isValidationAssertion($statement);
+ if ($isAssertion) {
+ $processedLines[] = $statementCode;
+ $contextHasClass = $this->contextContainsClass($context);
+ $result = $this->executeStatement($statementCode, $context, $printer);
+ $processedLines = array_merge($processedLines, $result);
+
+ if ($contextHasClass) {
+ $context->exchangeArray([]);
+ }
+ } else {
+ $context->append($printer->prettyPrint([$statement]));
+ $processedLines[] = $statementCode;
+ }
+
+ $lastEndPos = $endPos + 1;
+ $lastWasAssertion = $isAssertion;
+ }
+
+ while (count($processedLines) > 0 && trim($processedLines[count($processedLines) - 1]) === '') {
+ array_pop($processedLines);
+ }
+
+ return $processedLines;
+ }
+
+ private function stripOutputComments(string $code): string
+ {
+ $lines = explode("\n", $code);
+ $filteredLines = [];
+
+ foreach ($lines as $line) {
+ $trimmed = trim($line);
+
+ if ($trimmed === '// Validation passes successfully') {
+ continue;
+ }
+
+ if (str_starts_with($trimmed, '// →')) {
+ continue;
+ }
+
+ $filteredLines[] = $line;
+ }
+
+ $result = [];
+ $lastWasEmpty = false;
+ foreach ($filteredLines as $line) {
+ $isEmpty = trim($line) === '';
+ if ($isEmpty && $lastWasEmpty) {
+ continue;
+ }
+
+ $result[] = $line;
+ $lastWasEmpty = $isEmpty;
+ }
+
+ while (count($result) > 0 && trim($result[count($result) - 1]) === '') {
+ array_pop($result);
+ }
+
+ return implode("\n", $result);
+ }
+
+ private function isValidationAssertion(Node $statement): bool
+ {
+ if (!$statement instanceof Expression) {
+ return false;
+ }
+
+ $expr = $statement->expr;
+
+ if (!$expr instanceof MethodCall) {
+ return false;
+ }
+
+ $methodName = $expr->name;
+ if (!$methodName instanceof Identifier) {
+ return false;
+ }
+
+ if ($methodName->name !== 'assert') {
+ return false;
+ }
+
+ return $this->originatesFromV($expr) || $this->originatesFromVariable($expr);
+ }
+
+ private function originatesFromV(Node $node): bool
+ {
+ if ($node instanceof StaticCall) {
+ $class = $node->class;
+
+ return $class instanceof Name && $class->toString() === 'v';
+ }
+
+ if ($node instanceof MethodCall) {
+ return $this->originatesFromV($node->var);
+ }
+
+ return false;
+ }
+
+ private function originatesFromVariable(Node $node): bool
+ {
+ if ($node instanceof Node\Expr\Variable) {
+ return true;
+ }
+
+ if ($node instanceof MethodCall) {
+ return $this->originatesFromVariable($node->var);
+ }
+
+ return false;
+ }
+
+ private function contextContainsClass(ArrayObject $context): bool
+ {
+ $fullContext = implode("\n", $context->getArrayCopy());
+
+ return (bool) preg_match('/^(final\s+)?class\s+[A-Za-z_][A-Za-z0-9_]*/m', $fullContext);
+ }
+
+ /** @return string[] */
+ private function executeStatement(string $statementCode, ArrayObject $context, PrettyPrinter $printer): array
+ {
+ $fullCode = implode("\n", [...$context->getArrayCopy(), $statementCode]);
+ $fullCode = $this->replacePlaceholders($fullCode);
+
+ $resultLines = [];
+
+ try {
+ eval($fullCode);
+
+ if (str_contains($statementCode, 'assert(')) {
+ $resultLines[] = '// Validation passes successfully';
+ }
+ } catch (ValidationException $e) {
+ $fullMessage = $e->getFullMessage();
+ if (str_contains($fullMessage, PHP_EOL)) {
+ foreach (explode(PHP_EOL, trim($fullMessage)) as $line) {
+ $resultLines[] = '// → ' . $this->formatExceptionMessage($line);
+ }
+ } else {
+ $resultLines[] = '// → ' . $this->formatExceptionMessage($e->getMessage());
+ }
+ } catch (Throwable $e) {
+ $resultLines[] = '// 𝙭 ' . $this->formatExceptionMessage($e->getMessage());
+ }
+
+ if (count($resultLines) > 0) {
+ $resultLines[] = '';
+ }
+
+ return $resultLines;
+ }
+
+ private function replacePlaceholders(string $code): string
+ {
+ return str_replace(array_keys($this->getReplacements()), array_values($this->getReplacements()), $code);
+ }
+
+ private function formatExceptionMessage(string $line): string
+ {
+ return str_replace(array_values($this->getReplacements()), array_keys($this->getReplacements()), $line);
+ }
+
+ /** @return array */
+ private function getReplacements(): array
+ {
+ $dateTime = new DateTimeImmutable(self::FIXED_DATETIME);
+
+ return [
+ '/path/to/file.txt' => 'tests/fixtures/file.txt',
+ '/path/to/file' => 'tests/fixtures/file',
+ '/path/to/symbolic-link' => 'tests/fixtures/symbolic-link',
+ '/path/to/executable' => 'tests/fixtures/executable',
+ '/path/to/image.gif' => 'tests/fixtures/valid-image.gif',
+ '/path/to/image.png' => 'tests/fixtures/valid-image.png',
+ '/path/to/image.jpg' => 'tests/fixtures/valid-image.jpg',
+ '/path/to/dir' => 'tests/fixtures',
+ '__FILE__' => '"tests/fixtures/file"',
+ '__DIR__' => '"tests/fixtures"',
+ 'new DateTime()' => 'new DateTime(\'' . self::FIXED_DATETIME . '\')',
+ 'new DateTimeImmutable()' => 'new DateTimeImmutable(\'' . self::FIXED_DATETIME . '\')',
+ date('d/m/Y') => $dateTime->format('d/m/Y'),
+ $dateTime->format('d/m/Y') => date('d/m/Y'),
+ 'new ClassWithToString()' => 'new \Respect\Validation\Test\Stubs\ToStringStub("string")',
+ ];
+ }
+}
diff --git a/tests/fixtures/file b/tests/fixtures/file
new file mode 100644
index 00000000..96b4a656
--- /dev/null
+++ b/tests/fixtures/file
@@ -0,0 +1,5 @@
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque nec enim vitae velit elementum viverra. Donec luctus quis nibh nec placerat. Nulla facilisi. Suspendisse sagittis enim id posuere tincidunt. Sed efficitur erat sed est tristique laoreet. Pellentesque luctus dapibus suscipit. Mauris nisl arcu, egestas sit amet risus eu, commodo iaculis dolor. In luctus tortor ac ante fermentum mattis. Vestibulum pretium mi in mauris iaculis, in viverra purus consequat. Nam ultricies cursus luctus.
+
+Etiam pretium et lectus in scelerisque. Fusce maximus magna eu sapien gravida, eget tincidunt metus pulvinar. Phasellus faucibus pharetra arcu ornare ultricies. Sed venenatis ex sit amet quam mollis, quis posuere ligula interdum. Nunc mattis lectus sit amet sagittis varius. Quisque pretium mauris ac orci dignissim placerat nec sit amet ligula. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Cras quis libero imperdiet, dapibus eros mattis, consectetur neque. Nullam dictum mauris dolor, vitae semper magna aliquam a. Donec a nulla ut elit tincidunt ornare quis sit amet lorem. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Sed eu orci at ligula sodales iaculis semper ac urna.
+
+Nam laoreet ipsum nisl, nec auctor eros lobortis eget. Nulla felis libero, laoreet ut iaculis non, euismod vel erat. Aliquam id nibh eget turpis commodo ullamcorper. Fusce a euismod augue. Aliquam neque magna, lacinia vitae erat id, eleifend tristique velit. Morbi iaculis eleifend lectus in scelerisque. Duis tincidunt velit consequat, volutpat dolor non, faucibus augue. Cras convallis magna id nulla euismod tempus. Suspendisse bibendum porta arcu, eget fringilla enim congue a. Mauris mollis maximus justo, convallis viverra nisl rhoncus porta. Praesent quam magna, euismod sit amet condimentum vel, interdum nec orci. Sed ac tincidunt ligula. Maecenas eget tristique elit, quis tincidunt justo. Ut malesuada velit in auctor tellus.
diff --git a/tests/fixtures/file.txt b/tests/fixtures/file.txt
new file mode 100644
index 00000000..84102df4
--- /dev/null
+++ b/tests/fixtures/file.txt
@@ -0,0 +1 @@
+The quick brown fox jumps over the lazy dog