Replace isValid() calls with assert()

There's more value on showing how `assert()` displays the validation
messages than simply showing if `isValid()` returns `true` or `false`.

However, that increases the chances of having outdated documentation, so
I created a doc linter that updates the Markdown files with the
correct message.

Author: henriquemoody

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(),

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

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

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

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

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

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

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

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

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,