Create "Masked" validator

henriquemoody · henriquemoody · commit 4861e532256a · 2026-01-30T20:30:45.000+01:00
The Masked validator decorates other validators to mask sensitive input
values in error messages while still validating the original unmasked
data.

This validator is essential for applications handling sensitive
information such as passwords, credit cards, or email addresses. Without
it, users would need to implement a custom layer between Validation and
the end user to prevent PII from appearing in error messages or logs.

With Masked, sensitive data protection is built directly into the
validation workflow with no additional abstraction required.

Assisted-by: Claude Code (Opus 4.5)
diff --git a/docs/validators.md b/docs/validators.md
@@ -23,6 +23,8 @@ In this page you will find a list of validators by their category.
 
 **Core**: [Named][] - [Not][] - [Templated][]
 
+**Cosmetic**: [Masked][] - [Named][] - [Templated][]
+
 **Date and Time**: [Date][] - [DateTime][] - [DateTimeDiff][] - [LeapDate][] - [LeapYear][] - [Time][]
 
 **File system**: [Directory][] - [Executable][] - [Exists][] - [Extension][] - [File][] - [Image][] - [Mimetype][] - [Readable][] - [Size][] - [SymbolicLink][] - [Writable][]
@@ -37,7 +39,7 @@ In this page you will find a list of validators by their category.
 
 **Math**: [Factor][] - [Finite][] - [Infinite][] - [Multiple][] - [Negative][] - [Positive][]
 
-**Miscellaneous**: [Blank][] - [Falsy][] - [Named][] - [Templated][] - [Undef][]
+**Miscellaneous**: [Blank][] - [Falsy][] - [Masked][] - [Named][] - [Templated][] - [Undef][]
 
 **Nesting**: [AllOf][] - [AnyOf][] - [Call][] - [Circuit][] - [Each][] - [Key][] - [KeySet][] - [Lazy][] - [NoneOf][] - [Not][] - [NullOr][] - [OneOf][] - [Property][] - [PropertyOptional][] - [UndefOr][] - [When][]
 
@@ -47,7 +49,7 @@ In this page you will find a list of validators by their category.
 
 **Strings**: [Alnum][] - [Alpha][] - [Base64][] - [Charset][] - [Consonant][] - [Contains][] - [ContainsAny][] - [ContainsCount][] - [Control][] - [Digit][] - [Emoji][] - [EndsWith][] - [Graph][] - [HexRgbColor][] - [In][] - [Json][] - [Lowercase][] - [Phone][] - [PostalCode][] - [Printable][] - [Punct][] - [Regex][] - [Slug][] - [Sorted][] - [Space][] - [Spaced][] - [StartsWith][] - [StringType][] - [StringVal][] - [Uppercase][] - [Uuid][] - [Version][] - [Vowel][] - [Xdigit][]
 
-**Structures**: [Attributes][] - [Key][] - [KeyExists][] - [KeyOptional][] - [KeySet][] - [Named][] - [Property][] - [PropertyExists][] - [PropertyOptional][] - [Templated][]
+**Structures**: [Attributes][] - [Key][] - [KeyExists][] - [KeyOptional][] - [KeySet][] - [Property][] - [PropertyExists][] - [PropertyOptional][]
 
 **Transformations**: [All][] - [Call][] - [Each][] - [Length][] - [Max][] - [Min][] - [Size][]
 
@@ -147,6 +149,7 @@ In this page you will find a list of validators by their category.
 - [Lowercase][] - `v::stringType()->lowercase()->assert('xkcd');`
 - [Luhn][] - `v::luhn()->assert('2222400041240011');`
 - [MacAddress][] - `v::macAddress()->assert('00:11:22:33:44:55');`
+- [Masked][] - `v::masked(v::email())->assert('foo@example.com');`
 - [Max][] - `v::max(v::equals(30))->assert([10, 20, 30]);`
 - [Mimetype][] - `v::mimetype('image/png')->assert('/path/to/image.png');`
 - [Min][] - `v::min(v::equals(10))->assert([10, 20, 30]);`
@@ -302,6 +305,7 @@ In this page you will find a list of validators by their category.
 [Lowercase]: validators/Lowercase.md "Validates whether the characters in the input are lowercase."
 [Luhn]: validators/Luhn.md "Validate whether a given input is a Luhn number."
 [MacAddress]: validators/MacAddress.md "Validates whether the input is a valid MAC address."
+[Masked]: validators/Masked.md "Decorates a validator to mask input values in error messages while still validating the original unmasked input."
 [Max]: validators/Max.md "Validates the maximum value of the input against a given validator."
 [Mimetype]: validators/Mimetype.md "Validates if the input is a file and if its MIME type matches the expected one."
 [Min]: validators/Min.md "Validates the minimum value of the input against a given validator."
diff --git a/docs/validators/Masked.md b/docs/validators/Masked.md
@@ -0,0 +1,52 @@
+<!--
+SPDX-FileCopyrightText: (c) Respect Project Contributors
+SPDX-License-Identifier: MIT
+-->
+
+# Masked
+
+- `Masked(Validator $validator)`
+- `Masked(Validator $validator, string $range)`
+- `Masked(Validator $validator, string $range, string $replacement)`
+
+Decorates a validator to mask input values in error messages while still validating the original unmasked input.
+
+```php
+v::masked(v::email())->assert('foo@example.com');
+// Validation passes successfully
+
+v::masked(v::lengthGreaterThan(10))->assert('password');
+// → The length of "********" must be greater than 10
+
+v::masked(v::email(), '1-@')->assert('invalid username@domain.com');
+// → "****************@domain.com" must be a valid email address
+
+v::masked(v::creditCard(), '6-12', 'X')->assert('4111111111111211');
+// → "41111XXXXXXX1211" must be a valid credit card number
+```
+
+This validator is useful for security-sensitive applications where error messages should not expose sensitive data like credit card numbers, passwords, or email addresses.
+
+It uses [request/string-formatter](https://github.com/Respect/StringFormatter) as the underlying masking engine. See the section the documentation of [MaskFormatter](https://github.com/Respect/StringFormatter/blob/main/docs/MaskFormatter.md) for more information.
+
+## Categorization
+
+- Cosmetic
+- Miscellaneous
+
+## Behavior
+
+The validator first ensures the input is a valid string using `StringVal`. If the input passes string validation, it validates the original unmasked input using the inner validator. If validation fails, it applies masking to the input value shown in error messages.
+
+## Important Notes
+
+- **Positions are 1-based**: Position `1` refers to the first character, not position `0`
+- **Empty ranges mask everything**: `range = ''` defaults to masking the entire string
+- **Range end is exclusive**: `1-@` masks up to (but not including) the `@` character
+- **Duplicate positions**: Repeated ranges in the specification are automatically handled
+
+## Changelog
+
+| Version | Description |
+| ------: | :---------- |
+|   3.0.0 | Created     |
diff --git a/docs/validators/Named.md b/docs/validators/Named.md
@@ -39,7 +39,7 @@ This validator does not have any templates, as it will use the template of the g
 ## Categorization
 
 - Core
-- Structures
+- Cosmetic
 - Miscellaneous
 
 ## Changelog
diff --git a/docs/validators/Templated.md b/docs/validators/Templated.md
@@ -40,7 +40,7 @@ This validator does not have any templates, as you must define the templates you
 ## Categorization
 
 - Core
-- Structures
+- Cosmetic
 - Miscellaneous
 
 ## Changelog
diff --git a/src-dev/Commands/LintMixinCommand.php b/src-dev/Commands/LintMixinCommand.php
@@ -63,6 +63,7 @@
 use function preg_replace;
 use function sprintf;
 use function str_contains;
+use function str_ends_with;
 use function str_starts_with;
 use function trim;
 use function ucfirst;
@@ -348,6 +349,7 @@ private function addParameterToMethod(
             $types[] = $type->getName();
             if (
                 str_starts_with($type->getName(), 'Sokil')
+                || str_ends_with($type->getName(), 'TextMasker')
                 || str_starts_with($type->getName(), 'Egulias')
                 || $type->getName() === 'finfo'
             ) {
diff --git a/src-dev/Markdown/Linters/ValidatorHeaderLinter.php b/src-dev/Markdown/Linters/ValidatorHeaderLinter.php
@@ -172,6 +172,7 @@ private function getParameter(ReflectionParameter $reflection): array|null
         } elseif ($type instanceof ReflectionNamedType) {
             if (
                 str_starts_with($type->getName(), 'Sokil')
+                || str_ends_with($type->getName(), 'TextMasker')
                 || str_starts_with($type->getName(), 'Egulias')
                 || $type->getName() === 'finfo'
             ) {
diff --git a/src/Mixins/AllBuilder.php b/src/Mixins/AllBuilder.php
@@ -193,6 +193,8 @@ public static function allLuhn(): Chain;
 
     public static function allMacAddress(): Chain;
 
+    public static function allMasked(Validator $validator, string $range = '1-', string $replacement = '*'): Chain;
+
     public static function allMax(Validator $validator): Chain;
 
     public static function allMimetype(string $mimetype): Chain;
diff --git a/src/Mixins/AllChain.php b/src/Mixins/AllChain.php
@@ -193,6 +193,8 @@ public function allLuhn(): Chain;
 
     public function allMacAddress(): Chain;
 
+    public function allMasked(Validator $validator, string $range = '1-', string $replacement = '*'): Chain;
+
     public function allMax(Validator $validator): Chain;
 
     public function allMimetype(string $mimetype): Chain;
diff --git a/src/Mixins/Builder.php b/src/Mixins/Builder.php
@@ -208,6 +208,8 @@ public static function luhn(): Chain;
 
     public static function macAddress(): Chain;
 
+    public static function masked(Validator $validator, string $range = '1-', string $replacement = '*'): Chain;
+
     public static function max(Validator $validator): Chain;
 
     public static function mimetype(string $mimetype): Chain;
diff --git a/src/Mixins/Chain.php b/src/Mixins/Chain.php
@@ -210,6 +210,8 @@ public function luhn(): Chain;
 
     public function macAddress(): Chain;
 
+    public function masked(Validator $validator, string $range = '1-', string $replacement = '*'): Chain;
+
     public function max(Validator $validator): Chain;
 
     public function mimetype(string $mimetype): Chain;
diff --git a/src/Mixins/KeyBuilder.php b/src/Mixins/KeyBuilder.php
@@ -195,6 +195,13 @@ public static function keyLuhn(int|string $key): Chain;
 
     public static function keyMacAddress(int|string $key): Chain;
 
+    public static function keyMasked(
+        int|string $key,
+        Validator $validator,
+        string $range = '1-',
+        string $replacement = '*',
+    ): Chain;
+
     public static function keyMax(int|string $key, Validator $validator): Chain;
 
     public static function keyMimetype(int|string $key, string $mimetype): Chain;
diff --git a/src/Mixins/KeyChain.php b/src/Mixins/KeyChain.php
@@ -195,6 +195,13 @@ public function keyLuhn(int|string $key): Chain;
 
     public function keyMacAddress(int|string $key): Chain;
 
+    public function keyMasked(
+        int|string $key,
+        Validator $validator,
+        string $range = '1-',
+        string $replacement = '*',
+    ): Chain;
+
     public function keyMax(int|string $key, Validator $validator): Chain;
 
     public function keyMimetype(int|string $key, string $mimetype): Chain;
diff --git a/src/Mixins/NotBuilder.php b/src/Mixins/NotBuilder.php
@@ -205,6 +205,8 @@ public static function notLuhn(): Chain;
 
     public static function notMacAddress(): Chain;
 
+    public static function notMasked(Validator $validator, string $range = '1-', string $replacement = '*'): Chain;
+
     public static function notMax(Validator $validator): Chain;
 
     public static function notMimetype(string $mimetype): Chain;
diff --git a/src/Mixins/NotChain.php b/src/Mixins/NotChain.php
@@ -205,6 +205,8 @@ public function notLuhn(): Chain;
 
     public function notMacAddress(): Chain;
 
+    public function notMasked(Validator $validator, string $range = '1-', string $replacement = '*'): Chain;
+
     public function notMax(Validator $validator): Chain;
 
     public function notMimetype(string $mimetype): Chain;
diff --git a/src/Mixins/NullOrBuilder.php b/src/Mixins/NullOrBuilder.php
@@ -205,6 +205,12 @@ public static function nullOrLuhn(): Chain;
 
     public static function nullOrMacAddress(): Chain;
 
+    public static function nullOrMasked(
+        Validator $validator,
+        string $range = '1-',
+        string $replacement = '*',
+    ): Chain;
+
     public static function nullOrMax(Validator $validator): Chain;
 
     public static function nullOrMimetype(string $mimetype): Chain;
diff --git a/src/Mixins/NullOrChain.php b/src/Mixins/NullOrChain.php
@@ -205,6 +205,8 @@ public function nullOrLuhn(): Chain;
 
     public function nullOrMacAddress(): Chain;
 
+    public function nullOrMasked(Validator $validator, string $range = '1-', string $replacement = '*'): Chain;
+
     public function nullOrMax(Validator $validator): Chain;
 
     public function nullOrMimetype(string $mimetype): Chain;
diff --git a/src/Mixins/PropertyBuilder.php b/src/Mixins/PropertyBuilder.php
@@ -195,6 +195,13 @@ public static function propertyLuhn(string $propertyName): Chain;
 
     public static function propertyMacAddress(string $propertyName): Chain;
 
+    public static function propertyMasked(
+        string $propertyName,
+        Validator $validator,
+        string $range = '1-',
+        string $replacement = '*',
+    ): Chain;
+
     public static function propertyMax(string $propertyName, Validator $validator): Chain;
 
     public static function propertyMimetype(string $propertyName, string $mimetype): Chain;
diff --git a/src/Mixins/PropertyChain.php b/src/Mixins/PropertyChain.php
@@ -195,6 +195,13 @@ public function propertyLuhn(string $propertyName): Chain;
 
     public function propertyMacAddress(string $propertyName): Chain;
 
+    public function propertyMasked(
+        string $propertyName,
+        Validator $validator,
+        string $range = '1-',
+        string $replacement = '*',
+    ): Chain;
+
     public function propertyMax(string $propertyName, Validator $validator): Chain;
 
     public function propertyMimetype(string $propertyName, string $mimetype): Chain;
diff --git a/src/Mixins/UndefOrBuilder.php b/src/Mixins/UndefOrBuilder.php
@@ -203,6 +203,12 @@ public static function undefOrLuhn(): Chain;
 
     public static function undefOrMacAddress(): Chain;
 
+    public static function undefOrMasked(
+        Validator $validator,
+        string $range = '1-',
+        string $replacement = '*',
+    ): Chain;
+
     public static function undefOrMax(Validator $validator): Chain;
 
     public static function undefOrMimetype(string $mimetype): Chain;
diff --git a/src/Mixins/UndefOrChain.php b/src/Mixins/UndefOrChain.php
@@ -203,6 +203,8 @@ public function undefOrLuhn(): Chain;
 
     public function undefOrMacAddress(): Chain;
 
+    public function undefOrMasked(Validator $validator, string $range = '1-', string $replacement = '*'): Chain;
+
     public function undefOrMax(Validator $validator): Chain;
 
     public function undefOrMimetype(string $mimetype): Chain;
diff --git a/src/Validators/Masked.php b/src/Validators/Masked.php
@@ -0,0 +1,47 @@
+<?php
+
+/*
+ * SPDX-License-Identifier: MIT
+ * SPDX-FileCopyrightText: (c) Respect Project Contributors
+ * SPDX-FileContributor: Henrique Moody <henriquemoody@gmail.com>
+ */
+
+declare(strict_types=1);
+
+namespace Respect\Validation\Validators;
+
+use Attribute;
+use Respect\StringFormatter\InvalidFormatterException;
+use Respect\StringFormatter\MaskFormatter;
+use Respect\Validation\Exceptions\InvalidValidatorException;
+use Respect\Validation\Result;
+use Respect\Validation\Validator;
+
+#[Attribute(Attribute::TARGET_PROPERTY | Attribute::IS_REPEATABLE)]
+final readonly class Masked implements Validator
+{
+    private MaskFormatter $maskFormatter;
+
+    public function __construct(
+        private Validator $validator,
+        private string $range = '1-',
+        private string $replacement = '*',
+    ) {
+        try {
+            $this->maskFormatter = new MaskFormatter($this->range, $this->replacement);
+        } catch (InvalidFormatterException $exception) {
+            throw new InvalidValidatorException($exception->getMessage());
+        }
+    }
+
+    public function evaluate(mixed $input): Result
+    {
+        $stringVal = new StringVal();
+        $stringValResult = $stringVal->evaluate($input);
+        if (!$stringValResult->hasPassed) {
+            return $stringValResult->withNameFrom($this->validator)->withIdFrom($this->validator);
+        }
+
+        return $this->validator->evaluate($input)->withInput($this->maskFormatter->format((string) $input));
+    }
+}
diff --git a/tests/feature/Validators/MaskedTest.php b/tests/feature/Validators/MaskedTest.php
@@ -0,0 +1,25 @@
+<?php
+
+/*
+ * SPDX-License-Identifier: MIT
+ * SPDX-FileCopyrightText: (c) Respect Project Contributors
+ * SPDX-FileContributor: Henrique Moody <henriquemoody@gmail.com>
+ */
+
+declare(strict_types=1);
+
+test('input is not a string', catchAll(
+    fn() => v::masked(v::email(), '1-@')->assert(new stdClass()),
+    fn(string $message, string $fullMessage, array $messages) => expect()
+        ->and($message)->toBe('`stdClass {}` must be a string value')
+        ->and($fullMessage)->toBe('- `stdClass {}` must be a string value')
+        ->and($messages)->toBe(['email' => '`stdClass {}` must be a string value']),
+));
+
+test('failed validator', catchAll(
+    fn() => v::masked(v::email(), '1-@')->assert('in valid@email.com'),
+    fn(string $message, string $fullMessage, array $messages) => expect()
+        ->and($message)->toBe('"********@email.com" must be a valid email address')
+        ->and($fullMessage)->toBe('- "********@email.com" must be a valid email address')
+        ->and($messages)->toBe(['email' => '"********@email.com" must be a valid email address']),
+));
diff --git a/tests/fixtures/data-provider.php b/tests/fixtures/data-provider.php
diff --git a/tests/src/Stubs/ToStringStub.php b/tests/src/Stubs/ToStringStub.php
diff --git a/tests/src/TestCase.php b/tests/src/TestCase.php
diff --git a/tests/unit/Validators/MaskedTest.php b/tests/unit/Validators/MaskedTest.php
