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 console command that updates the Markdown files with the
correct message.

Author: henriquemoody

.github/workflows/continuous-integration.yml

@@ -92,3 +92,24 @@ jobs:
 
       - name: Run PHPStan
         run: vendor/bin/phpstan analyze
+
+  doc-check:
+    name: Documentation Check
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Install PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: 8.5
+          coverage: none
+
+      - name: Install dependencies
+        run: composer install --prefer-dist
+
+      - name: Run doc:assertions
+        run: bin/console update:doc:assertions

bin/console

@@ -11,6 +11,7 @@ declare(strict_types=1);
 require __DIR__ . '/../vendor/autoload.php';
 
 use Respect\Dev\Commands\CreateMixinCommand;
+use Respect\Dev\Commands\UpdateDocAssertionCommand;
 use Respect\Dev\Commands\UpdateDocLinksCommand;
 use Respect\Dev\Commands\UpdateDomainSuffixesCommand;
 use Respect\Dev\Commands\UpdateDomainToplevelCommand;
@@ -20,6 +21,7 @@ use Symfony\Component\Console\Application;
 return (static function () {
     $application = new Application('Respect/Validation', '3.0');
     $application->addCommand(new CreateMixinCommand());
+    $application->addCommand(new UpdateDocAssertionCommand());
     $application->addCommand(new UpdateDocLinksCommand());
     $application->addCommand(new UpdateDomainSuffixesCommand());
     $application->addCommand(new UpdateDomainToplevelCommand());

composer.json

@@ -41,6 +41,7 @@
         "psr/http-message": "^1.0 || ^2.0",
         "ramsey/uuid": "^4",
         "respect/coding-standard": "^5.0",
+        "sebastian/diff": "^7.0",
         "sokil/php-isocodes": "^4.2.1",
         "sokil/php-isocodes-db-only": "^4.0",
         "squizlabs/php_codesniffer": "^4.0",

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/list-of-validators-by-category.md

@@ -298,7 +298,6 @@
 - [ScalarVal](validators/ScalarVal.md)
 - [StringType](validators/StringType.md)
 - [StringVal](validators/StringVal.md)
-- [Type](validators/Type.md)
 
 ## Alphabetically
 
@@ -449,7 +448,6 @@
 - [Time](validators/Time.md)
 - [Tld](validators/Tld.md)
 - [TrueVal](validators/TrueVal.md)
-- [Type](validators/Type.md)
 - [Undef](validators/Undef.md)
 - [UndefOr](validators/UndefOr.md)
 - [Unique](validators/Unique.md)

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.
@@ -28,10 +31,10 @@ This template serve as message prefixes.:
 
 ```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

@@ -5,7 +5,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