Add doc linter to check validator constructors

henriquemoody · henriquemoody · commit d38736d16785 · 2026-01-13T23:37:05.000-07:00
When we make changes to the code, renaming variables, or adding
parameters to a validator, it's easy to forget to update the
documentation.

With this change, we avoid having a disparity between the documentation
and the code.
diff --git 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\ValidatorHeaderLinter;
 use Respect\Dev\Markdown\Linters\ValidatorIndexLinter;
 use SebastianBergmann\Diff\Differ;
 use SebastianBergmann\Diff\Output\UnifiedDiffOutputBuilder;
@@ -29,6 +30,7 @@ return (static function () {
     $application->addCommand(new CreateMixinCommand());
     $application->addCommand(new DocsLintCommand($differ, new CompositeLinter(
         new ValidatorIndexLinter(),
+        new ValidatorHeaderLinter(),
     )));
     $application->addCommand(new UpdateDomainSuffixesCommand());
     $application->addCommand(new UpdateDomainToplevelCommand());
diff --git a/docs/validators/AllOf.md b/docs/validators/AllOf.md
@@ -1,6 +1,7 @@
 # AllOf
 
-- `AllOf(Validator $validator1, Validator $validator2, Validator ...$validator)`
+- `AllOf(Validator $validator1, Validator $validator2)`
+- `AllOf(Validator $validator1, Validator $validator2, Validator ...$validators)`
 
 Will validate if all inner validators validates.
 
diff --git a/docs/validators/AnyOf.md b/docs/validators/AnyOf.md
@@ -1,6 +1,7 @@
 # AnyOf
 
-- `AnyOf(Validator $validator1, Validator $validator2, Validator ...$validator)`
+- `AnyOf(Validator $validator1, Validator $validator2)`
+- `AnyOf(Validator $validator1, Validator $validator2, Validator ...$validators)`
 
 This is a group validator that acts as an OR operator.
 
diff --git a/docs/validators/Base.md b/docs/validators/Base.md
@@ -1,6 +1,7 @@
 # Base
 
-- `Base(string $base)`
+- `Base(int $base)`
+- `Base(int $base, string $chars)`
 
 Validate numbers in any base, even with non regular bases.
 
diff --git a/docs/validators/Between.md b/docs/validators/Between.md
@@ -1,6 +1,6 @@
 # Between
 
-- `Between(mixed $minimum, mixed $maximum)`
+- `Between(mixed $minValue, mixed $maxValue)`
 
 Validates whether the input is between two other values.
 
diff --git a/docs/validators/Callback.md b/docs/validators/Callback.md
@@ -1,6 +1,7 @@
 # Callback
 
 - `Callback(callable $callback)`
+- `Callback(callable $callback, mixed ...$arguments)`
 
 Validates the input using the return of a given callable.
 
diff --git a/docs/validators/Charset.md b/docs/validators/Charset.md
@@ -1,6 +1,7 @@
 # Charset
 
-- `Charset(string ...$charset)`
+- `Charset(string $charset)`
+- `Charset(string $charset, string ...$charsets)`
 
 Validates if a string is in a specific charset.
 
diff --git a/docs/validators/Circuit.md b/docs/validators/Circuit.md
@@ -1,6 +1,7 @@
 # Circuit
 
-- `Circuit(Validator $validator1, Validator $validator2, Validator ...$validator)`
+- `Circuit(Validator $validator1, Validator $validator2)`
+- `Circuit(Validator $validator1, Validator $validator2, Validator ...$validators)`
 
 Validates the input against a series of validators until the first fails.
 
diff --git a/docs/validators/Contains.md b/docs/validators/Contains.md
@@ -1,7 +1,7 @@
 # Contains
 
-- `Contains(mixed $expectedValue)`
-- `Contains(mixed $expectedValue, bool $identical)`
+- `Contains(mixed $containsValue)`
+- `Contains(mixed $containsValue, bool $identical)`
 
 Validates if the input contains some value.
 
diff --git a/docs/validators/ContainsAny.md b/docs/validators/ContainsAny.md
@@ -1,7 +1,7 @@
 # ContainsAny
 
-- `ContainsAny(array $needles)`
-- `ContainsAny(array $needles, bool $identical)`
+- `ContainsAny(non-empty-array<mixed> $needles)`
+- `ContainsAny(non-empty-array<mixed> $needles, bool $identical)`
 
 Validates if the input contains at least one of defined values
 
diff --git a/docs/validators/DateTimeDiff.md b/docs/validators/DateTimeDiff.md
@@ -1,8 +1,8 @@
 # DateTimeDiff
 
-- `DateTimeDiff(string $type, Validator $validator)`
-- `DateTimeDiff(string $type, Validator $validator, string $format)`
-- `DateTimeDiff(string $type, Validator $validator, string $format, DateTimeImmutable $now)`
+- `DateTimeDiff("years"|"months"|"days"|"hours"|"minutes"|"seconds"|"microseconds" $type, Validator $validator)`
+- `DateTimeDiff("years"|"months"|"days"|"hours"|"minutes"|"seconds"|"microseconds" $type, Validator $validator, string $format)`
+- `DateTimeDiff("years"|"months"|"days"|"hours"|"minutes"|"seconds"|"microseconds" $type, Validator $validator, string $format, DateTimeImmutable $now)`
 
 Validates the difference of date/time against a specific validator.
 
diff --git a/docs/validators/Emoji.md b/docs/validators/Emoji.md
@@ -1,6 +1,6 @@
 # Emoji
 
-- `v::emoji()`
+- `Emoji()`
 
 Validates if the input is an emoji or a sequence of emojis.
 
diff --git a/docs/validators/EndsWith.md b/docs/validators/EndsWith.md
@@ -1,7 +1,7 @@
 # EndsWith
 
-- `EndsWith(mixed $value)`
-- `EndsWith(mixed $value, bool $identical)`
+- `EndsWith(mixed $endValue)`
+- `EndsWith(mixed $endValue, bool $identical)`
 
 This validator is similar to `Contains()`, but validates
 only if the value is at the end of the input.
diff --git a/docs/validators/Iban.md b/docs/validators/Iban.md
@@ -1,6 +1,6 @@
 # Iban
 
-- `v::iban()`
+- `Iban()`
 
 Validates whether the input is a valid [IBAN][] (International Bank Account
 Number) or not.
diff --git a/docs/validators/Identical.md b/docs/validators/Identical.md
@@ -1,6 +1,6 @@
 # Identical
 
-- `Identical(mixed $value)`
+- `Identical(mixed $compareTo)`
 
 Validates if the input is identical to some value.
 
diff --git a/docs/validators/Image.md b/docs/validators/Image.md
@@ -1,7 +1,6 @@
 # Image
 
 - `Image()`
-- `Image(finfo $fileInfo)`
 
 Validates if the file is a valid image by checking its MIME type.
 
diff --git a/docs/validators/In.md b/docs/validators/In.md
@@ -1,7 +1,7 @@
 # In
 
 - `In(mixed $haystack)`
-- `In(mixed $haystack, bool $identical)`
+- `In(mixed $haystack, bool $compareIdentical)`
 
 Validates if the input is contained in a specific haystack.
 
diff --git a/docs/validators/Instance.md b/docs/validators/Instance.md
@@ -1,6 +1,6 @@
 # Instance
 
-- `Instance(string $instanceName)`
+- `Instance(class-string $class)`
 
 Validates if the input is an instance of the given class or interface.
 
diff --git a/docs/validators/Isbn.md b/docs/validators/Isbn.md
@@ -1,6 +1,6 @@
 # Isbn
 
-- `v::isbn()`
+- `Isbn()`
 
 Validates whether the input is a valid [ISBN][] or not.
 
diff --git a/docs/validators/Key.md b/docs/validators/Key.md
@@ -1,6 +1,6 @@
 # Key
 
-- `Key(int|string $key, Validator $validator)`
+- `Key(string|int $key, Validator $validator)`
 
 Validates the value of an array against a given validator.
 
diff --git a/docs/validators/KeyExists.md b/docs/validators/KeyExists.md
@@ -1,6 +1,6 @@
 # KeyExists
 
-- `KeyExists(int|string $key)`
+- `KeyExists(string|int $key)`
 
 Validates if the given key exists in an array.
 
diff --git a/docs/validators/KeyOptional.md b/docs/validators/KeyOptional.md
@@ -1,6 +1,6 @@
 # KeyOptional
 
-- `KeyOptional(int|string $key, Validator $validator)`
+- `KeyOptional(string|int $key, Validator $validator)`
 
 Validates the value of an array against a given validator when the key exists.
 
diff --git a/docs/validators/KeySet.md b/docs/validators/KeySet.md
@@ -1,6 +1,7 @@
 # KeySet
 
-- `KeySet(KeyRelated $validator, KeyRelated ...$validators)`
+- `KeySet(Validator $validator)`
+- `KeySet(Validator $validator, Validator ...$validators)`
 
 Validates a keys in a defined structure.
 
diff --git a/docs/validators/Lazy.md b/docs/validators/Lazy.md
@@ -1,6 +1,6 @@
 # Lazy
 
-- `Lazy(callable(mixed $input): Validator $validatorCreator)`
+- `Lazy(callable(mixed): Validator $validatorCreator)`
 
 Validates the input using a validator that is created from a callback.
 
diff --git a/docs/validators/Named.md b/docs/validators/Named.md
@@ -1,6 +1,6 @@
 # Named
 
-- `Named(string $name, Validator $validator)`
+- `Named(Name|string $name, Validator $validator)`
 
 Validates the input with the given validator, and uses the custom name in the error message.
 
diff --git a/docs/validators/NfeAccessKey.md b/docs/validators/NfeAccessKey.md
@@ -1,6 +1,6 @@
 # NfeAccessKey
 
-- `NfeAccessKey(string $accessKey)`
+- `NfeAccessKey()`
 
 Validates the access key of the Brazilian electronic invoice (NFe).
 
diff --git a/docs/validators/Nif.md b/docs/validators/Nif.md
@@ -1,4 +1,4 @@
-# NIF
+# Nif
 
 - `Nif()`
 
diff --git a/docs/validators/Nip.md b/docs/validators/Nip.md
@@ -1,6 +1,6 @@
 # Nip
 
-- `Nip(string $countryCode)`
+- `Nip()`
 
 Validates whether the input is a Polish VAT identification number (NIP).
 
diff --git a/docs/validators/NoneOf.md b/docs/validators/NoneOf.md
@@ -1,6 +1,7 @@
 # NoneOf
 
-- `NoneOf(Validator $validator1, Validator $validator2, Validator ...$validator)`
+- `NoneOf(Validator $validator1, Validator $validator2)`
+- `NoneOf(Validator $validator1, Validator $validator2, Validator ...$validators)`
 
 Validates if NONE of the given validators validate:
 
diff --git a/docs/validators/OneOf.md b/docs/validators/OneOf.md
@@ -1,6 +1,7 @@
 # OneOf
 
-- `OneOf(Validator $validator1, Validator $validator2, Validator ...$validator)`
+- `OneOf(Validator $validator1, Validator $validator2)`
+- `OneOf(Validator $validator1, Validator $validator2, Validator ...$validators)`
 
 Will validate if exactly one inner validator passes.
 
diff --git a/docs/validators/Phone.md b/docs/validators/Phone.md
@@ -1,6 +1,7 @@
 # Phone
 
 - `Phone()`
+- `Phone(string $countryCode)`
 
 Validates whether the input is a valid phone number. This validator requires
 the `giggsey/libphonenumber-for-php-lite` package.
diff --git a/docs/validators/PostalCode.md b/docs/validators/PostalCode.md
@@ -1,6 +1,7 @@
 # PostalCode
 
-- `PostalCode(string $countryCode, bool $formatted = false)`
+- `PostalCode(string $countryCode)`
+- `PostalCode(string $countryCode, bool $formatted)`
 
 Validates whether the input is a valid postal code or not.
 
diff --git a/docs/validators/Size.md b/docs/validators/Size.md
@@ -1,6 +1,6 @@
 # Size
 
-- `Size(string $unit, Validator $validator)`
+- `Size("B"|"KB"|"MB"|"GB"|"TB"|"PB"|"EB"|"ZB"|"YB" $unit, Validator $validator)`
 
 Validates whether the input is a file that is of a certain size or not.
 
diff --git a/docs/validators/StartsWith.md b/docs/validators/StartsWith.md
@@ -1,7 +1,7 @@
 # StartsWith
 
-- `StartsWith(mixed $value)`
-- `StartsWith(mixed $value, bool $identical)`
+- `StartsWith(mixed $startValue)`
+- `StartsWith(mixed $startValue, bool $identical)`
 
 Validates whether the input starts with a given value.
 
diff --git a/docs/validators/Subset.md b/docs/validators/Subset.md
@@ -1,6 +1,6 @@
 # Subset
 
-- `Subset(array $superset)`
+- `Subset(mixed[] $superset)`
 
 Validates whether the input is a subset of a given value.
 
diff --git a/docs/validators/Type.md b/docs/validators/Type.md
diff --git a/docs/validators/When.md b/docs/validators/When.md
@@ -1,7 +1,7 @@
 # When
 
-- `When(Validator $if, Validator $then)`
-- `When(Validator $if, Validator $then, Validator $else)`
+- `When(Validator $when, Validator $then)`
+- `When(Validator $when, Validator $then, Validator $else)`
 
 A ternary validator that accepts three parameters.
 
diff --git a/docs/validators/index.md b/docs/validators/index.md
@@ -300,7 +300,6 @@ In this page you will find a list of validators by their category.
 - [ScalarVal](validators/ScalarVal.md)
 - [StringType](validators/StringType.md)
 - [StringVal](validators/StringVal.md)
-- [Type](validators/Type.md)
 
 ## Alphabetically
 
@@ -451,7 +450,6 @@ In this page you will find a list of validators by their category.
 - [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)
diff --git a/src-dev/Markdown/Linters/ValidatorHeaderLinter.php b/src-dev/Markdown/Linters/ValidatorHeaderLinter.php
