Add GitHub action to check outdated templates

henriquemoody · henriquemoody · commit 7a1aa61e3d12 · 2026-01-12T07:08:14.000-07:00
We don't often change the tempaltes of validators, but when we do it's
extremely important that the documentation of the validators match the
exact template the validator has.

This commit will create a console command to the GitHub workflow that
will ensure that the documentation of validators are always aligned with
the templates they have.
diff --git a/.github/workflows/continuous-integration-docs.yml b/.github/workflows/continuous-integration-docs.yml
@@ -35,5 +35,8 @@ jobs:
       - name: Validator headers
         run: bin/console docs:validators:headers
 
+      - name: Validator templates
+        run: bin/console docs:validators:templates
+
       - name: Related validators
         run: bin/console docs:validators:related
diff --git a/bin/console b/bin/console
@@ -14,6 +14,7 @@ use Respect\Dev\Commands\CreateMixinCommand;
 use Respect\Dev\Commands\DocsValidatorsHeadersCommand;
 use Respect\Dev\Commands\DocsValidatorsListCommand;
 use Respect\Dev\Commands\DocsValidatorsRelatedCommand;
+use Respect\Dev\Commands\DocsValidatorsTemplatesCommand;
 use Respect\Dev\Commands\UpdateDomainSuffixesCommand;
 use Respect\Dev\Commands\UpdateDomainToplevelCommand;
 use Respect\Dev\Commands\UpdatePostalCodesCommand;
@@ -30,6 +31,7 @@ return (static function () {
     $application->addCommand(new DocsValidatorsHeadersCommand($differ));
     $application->addCommand(new DocsValidatorsListCommand($differ));
     $application->addCommand(new DocsValidatorsRelatedCommand($differ));
+    $application->addCommand(new DocsValidatorsTemplatesCommand($differ));
     $application->addCommand(new UpdateDomainSuffixesCommand());
     $application->addCommand(new UpdateDomainToplevelCommand());
     $application->addCommand(new UpdatePostalCodesCommand());
diff --git a/composer.json b/composer.json
@@ -75,6 +75,7 @@
         "docs:validators:headers": "bin/console docs:validators:headers",
         "docs:validators:index": "bin/console docs:validators:index",
         "docs:validators:related": "bin/console docs:validators:related",
+        "docs:validators:templates": "bin/console docs:validators:templates",
         "docheader": "vendor/bin/docheader check library/ tests/",
         "phpcs": "vendor/bin/phpcs",
         "phpstan": "vendor/bin/phpstan analyze",
@@ -83,7 +84,8 @@
         "docs": [
             "@docs:validators:headers",
             "@docs:validators:index",
-            "@docs:validators:related"
+            "@docs:validators:related",
+            "@docs:validators:templates"
         ],
         "qa": [
             "@docheader",
diff --git a/docs/validators/All.md b/docs/validators/All.md
@@ -24,7 +24,9 @@ This validator uses [Length](Length.md) with [GreaterThan][GreaterThan.md] inter
 | `default`  | Every item in |
 | `inverted` | Every item in |
 
-This template serve as message prefixes.:
+## Template as prefix
+
+The template serves as a prefix to the template of the inner validator.
 
 ```php
 v::all(v::floatType())->assert([1.5, 2]);
diff --git a/docs/validators/DateTimeDiff.md b/docs/validators/DateTimeDiff.md
@@ -31,16 +31,6 @@ The supported types are:
 
 ## Templates
 
-The first two templates serve as message suffixes:
-
-```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::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
-```
-
 ### `DateTimeDiff::TEMPLATE_STANDARD`
 
 Used when `$format` and `$now` are not defined.
@@ -54,10 +44,17 @@ Used when `$format` and `$now` are not defined.
 
 Used when `$format` or `$now` are defined.
 
-| Mode       | Template                                                       |
-| ---------- | -------------------------------------------------------------- |
-| `default`  | The number of {{type&#124;trans}} between {{now&#124;raw}} and |
-| `inverted` | The number of {{type&#124;trans}} between {{now&#124;raw}} and |
+| Mode       | Template                                              |
+| ---------- | ----------------------------------------------------- |
+| `default`  | The number of {{type&#124;trans}} between {{now}} and |
+| `inverted` | The number of {{type&#124;trans}} between {{now}} and |
+
+### `DateTimeDiff::TEMPLATE_NOT_A_DATE`
+
+| Mode       | Template                                                                       |
+| ---------- | ------------------------------------------------------------------------------ |
+| `default`  | For comparison with {{now&#124;raw}}, {{subject}} must be a valid datetime     |
+| `inverted` | For comparison with {{now&#124;raw}}, {{subject}} must not be a valid datetime |
 
 ### `DateTimeDiff::TEMPLATE_WRONG_FORMAT`
 
@@ -68,6 +65,18 @@ Used when the input cannot be parsed with the given format.
 | `default`  | For comparison with {{now&#124;raw}}, {{subject}} must be a valid datetime in the format {{sample&#124;raw}}     |
 | `inverted` | For comparison with {{now&#124;raw}}, {{subject}} must not be a valid datetime in the format {{sample&#124;raw}} |
 
+## Template as prefix
+
+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::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
 
 | Placeholder | Description                                                      |
diff --git a/docs/validators/Instance.md b/docs/validators/Instance.md
@@ -17,8 +17,8 @@ Message template for this validator includes `{{instanceName}}`.
 
 | Mode       | Template                                                    |
 | ---------- | ----------------------------------------------------------- |
-| `default`  | {{subject}} must be an instance of `{{class&#124;raw}}`     |
-| `inverted` | {{subject}} must not be an instance of `{{class&#124;raw}}` |
+| `default`  | {{subject}} must be an instance of {{class&#124;quote}}     |
+| `inverted` | {{subject}} must not be an instance of {{class&#124;quote}} |
 
 ## Template placeholders
 
diff --git a/docs/validators/Length.md b/docs/validators/Length.md
@@ -31,7 +31,16 @@ Used when it's possible to get the length of the input.
 | `default`  | The length of |
 | `inverted` | The length of |
 
-This template serve as message prefixes.:
+### `Length::TEMPLATE_WRONG_TYPE`
+
+| Mode       | Template                                              |
+| ---------- | ----------------------------------------------------- |
+| `default`  | {{subject}} must be a countable value or a string     |
+| `inverted` | {{subject}} must not be a countable value or a string |
+
+## Template as prefix
+
+The template serves as a prefix to the template of the inner validator.
 
 ```php
 v::length(v::equals(3))->assert('tulip');
diff --git a/docs/validators/Max.md b/docs/validators/Max.md
@@ -28,6 +28,10 @@ This validator uses [Length](Length.md) with [GreaterThan][GreaterThan.md] inter
 | `default`  | The maximum of |
 | `inverted` | The maximum of |
 
+## Template as prefix
+
+The template serves as a prefix to the template of the inner validator.
+
 ## Template placeholders
 
 | Placeholder | Description                                                      |
diff --git a/docs/validators/Min.md b/docs/validators/Min.md
@@ -28,6 +28,10 @@ This validator uses [Length](Length.md) with [GreaterThan][GreaterThan.md] inter
 | `default`  | The minimum of |
 | `inverted` | The minimum of |
 
+## Template as prefix
+
+The template serves as a prefix to the template of the inner validator.
+
 ## Template placeholders
 
 | Placeholder | Description                                                      |
diff --git a/docs/validators/NullOr.md b/docs/validators/NullOr.md
@@ -31,7 +31,9 @@ v::nullOrBetween(1, 3)->isValid(null); // true
 | `default`  | or must be null      |
 | `inverted` | and must not be null |
 
-The templates from this validator serve as message suffixes:
+## Template as suffix
+
+The template serves as a suffix to the template of the inner validator.
 
 ```php
 v::nullOr(v::alpha())->assert('has1number');
diff --git a/docs/validators/Regex.md b/docs/validators/Regex.md
@@ -16,8 +16,8 @@ Message template for this validator includes `{{regex}}`.
 
 | Mode       | Template                                                    |
 | ---------- | ----------------------------------------------------------- |
-| `default`  | {{subject}} must match the pattern `{{regex&#124;raw}}`     |
-| `inverted` | {{subject}} must not match the pattern `{{regex&#124;raw}}` |
+| `default`  | {{subject}} must match the pattern {{regex&#124;quote}}     |
+| `inverted` | {{subject}} must not match the pattern {{regex&#124;quote}} |
 
 ## Template placeholders
 
diff --git a/docs/validators/Size.md b/docs/validators/Size.md
@@ -28,16 +28,6 @@ This validator will accept:
 | `default`  | The size in {{unit&#124;trans}} of |
 | `inverted` | The size in {{unit&#124;trans}} of |
 
-This template serve as message prefix:
-
-```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('KB', v::not(v::equals(56)))->assert('filename.txt')
-// Message: The size in kilobytes of "filename.txt" must not be equal to 56
-```
-
 ### `Size::TEMPLATE_WRONG_TYPE`
 
 Used when the input is not a valid file path, a `SplFileInfo` object, or a PSR-7 interface.
@@ -47,6 +37,18 @@ Used when the input is not a valid file path, a `SplFileInfo` object, or a PSR-7
 | `default`  | {{subject}} must be a filename or an instance of SplFileInfo or a PSR-7 interface     |
 | `inverted` | {{subject}} must not be a filename or an instance of SplFileInfo or a PSR-7 interface |
 
+## Template as prefix
+
+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('KB', v::not(v::equals(56)))->assert('filename.txt')
+// Message: The size in kilobytes of "filename.txt" must not be equal to 56
+```
+
 ## Template placeholders
 
 | Placeholder | Description                                                      |
diff --git a/docs/validators/UndefOr.md b/docs/validators/UndefOr.md
@@ -34,7 +34,9 @@ v::undefOrBetween(1, 3)->isValid(2); // true
 | `default`  | or must be undefined      |
 | `inverted` | and must not be undefined |
 
-The templates from this validator serve as message suffixes:
+## Template as suffix
+
+The template serves as a suffix to the template of the inner validator.
 
 ```php
 v::undefOr(v::alpha())->assert('has1number');
diff --git a/src-dev/Commands/DocsValidatorsTemplatesCommand.php b/src-dev/Commands/DocsValidatorsTemplatesCommand.php
@@ -0,0 +1,157 @@
+<?php
+
+/*
+ * Copyright (c) Alexandre Gomes Gaigalas <alganet@gmail.com>
+ * SPDX-License-Identifier: MIT
+ */
+
+declare(strict_types=1);
+
+namespace Respect\Dev\Commands;
+
+use ReflectionClass;
+use Respect\Dev\Markdown\Builder;
+use Respect\Dev\Markdown\Differ;
+use Respect\Validation\Message\Template;
+use Symfony\Component\Console\Attribute\AsCommand;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+use Symfony\Component\Finder\Finder;
+use UnexpectedValueException;
+
+use function array_find_key;
+use function array_slice;
+use function count;
+use function dirname;
+use function explode;
+use function implode;
+use function preg_match;
+use function preg_replace;
+use function sprintf;
+use function str_starts_with;
+
+use const PHP_EOL;
+
+#[AsCommand(
+    name: 'docs:validators:templates',
+    description: 'Update the tables with templates of each validator documentation file',
+)]
+final class DocsValidatorsTemplatesCommand extends Command
+{
+    public function __construct(
+        private readonly Differ $differ,
+    ) {
+        parent::__construct();
+    }
+
+    protected function execute(InputInterface $input, OutputInterface $output): int
+    {
+        $diffs = [];
+        foreach ($this->getGroupedTemplates() as $validator => $templates) {
+            $diff = $this->updateMarkdown($validator, $templates);
+            if ($diff === null) {
+                continue;
+            }
+
+            $diffs[] = $diff;
+        }
+
+        if ($diffs === []) {
+            $output->writeln('<info>No changes needed.</info>');
+
+            return Command::SUCCESS;
+        }
+
+        $output->writeln(sprintf('<comment>Changed needed in %d files.</comment>', count($diffs)));
+        $output->writeln(implode(PHP_EOL, $diffs));
+
+        return Command::FAILURE;
+    }
+
+    /** @param array<string, Template> $templates */
+    private function updateMarkdown(string $validator, array $templates): string|null
+    {
+        if ($templates === []) {
+            return null;
+        }
+
+        $builder = new Builder(sprintf('%s/validators/%s.md', dirname(__DIR__, 2) . '/docs', $validator));
+
+        $existingLines = explode(PHP_EOL, $builder->existingContent);
+
+        $sectionStart = array_find_key($existingLines, static fn($line) => $line === '## Templates');
+        if ($sectionStart === null) {
+            throw new UnexpectedValueException('Does not have ## Templates');
+        }
+
+        $sectionEnd = null;
+        $descriptions = [];
+        for ($i = $sectionStart + 1; $i < count($existingLines); $i++) {
+            $currentLine = $existingLines[$i];
+            if (str_starts_with($currentLine, '### ')) {
+                $id = preg_replace('/^### `.+::([A-Z_]+)`/', '$1', $currentLine);
+                $descriptionKey = $i + 2;
+                if (isset($existingLines[$descriptionKey]) && preg_match('/^[A-Z]/', $existingLines[$descriptionKey])) {
+                    $descriptions[$id] = $existingLines[$descriptionKey];
+                }
+            }
+
+            if (str_starts_with($currentLine, '## ')) {
+                $sectionEnd = $i;
+                break;
+            }
+        }
+
+        // Extract before and after sections
+        $before = $sectionStart !== null ? array_slice($existingLines, 0, $sectionStart) : $existingLines;
+        $after = $sectionEnd !== null ? array_slice($existingLines, $sectionEnd) : [];
+
+        $builder->raw(...$before);
+        $builder->newLine();
+        $builder->h2('Templates');
+        foreach ($templates as $id => $template) {
+            $builder->h3(sprintf('`%s::%s`', $validator, $id));
+            if (isset($descriptions[$id])) {
+                $builder->paragraph($descriptions[$id]);
+                $builder->newLine();
+            }
+
+            $builder->table(['Mode', 'Template'], [
+                ['`default`', $template->default],
+                ['`inverted`', $template->inverted],
+            ]);
+        }
+
+        $builder->raw(...$after);
+
+        $diff = $this->differ->diff($builder);
+        if ($diff !== null) {
+            $builder->save();
+        }
+
+        return $diff;
+    }
+
+    /** @return array<array<Template>> */
+    private function getGroupedTemplates(): array
+    {
+        $finder = new Finder();
+        $finder->in(dirname(__DIR__, 2) . '/library/Validators')->depth(0)->files()->name('*.php')->sortByName();
+
+        $templates = [];
+        foreach ($finder as $file) {
+            $validator = $file->getBasename('.php');
+            $reflection = new ReflectionClass('Respect\\Validation\\Validators\\' . $validator);
+            $constants = $reflection->getConstants();
+
+            foreach ($reflection->getAttributes(Template::class) as $attribute) {
+                $template = $attribute->newInstance();
+                $id = array_find_key($constants, static fn($constant) => $template->id === $constant);
+                $templates[$validator][$id] = $template;
+            }
+        }
+
+        return $templates;
+    }
+}
