Create "Formatted" validator

docs/migrating-from-v2-to-v3.md

@@ -585,12 +585,12 @@ Version 3.0 introduces several new validators:
 | `BetweenExclusive` | Validates that a value is between two bounds (exclusive)   |
 | `ContainsCount`    | Validates the count of occurrences in a value              |
 | `DateTimeDiff`     | Validates date/time differences (replaces Age validators)  |
+| `Formatted`        | Formats input values in error messages                     |
 | `ShortCircuit`     | Stops at first failure instead of collecting all errors    |
 | `Hetu`             | Validates Finnish personal identity codes (henkilötunnus)  |
 | `KeyExists`        | Checks if an array key exists                              |
 | `KeyOptional`      | Validates an array key only if it exists                   |
 | `Factory`          | Creates validators dynamically based on input              |
-| `Masked`           | Masks sensitive input values in error messages             |
 | `Named`            | Customizes the subject name in error messages              |
 | `PropertyExists`   | Checks if an object property exists                        |
 | `PropertyOptional` | Validates an object property only if it exists             |
@@ -659,6 +659,20 @@ v::dateTimeDiff('years', v::greaterThanOrEqual(18))->assert('2000-01-01'); // pa
 v::dateTimeDiff('days', v::lessThan(30))->assert('2024-01-15'); // passes if less than 30 days ago
 ```
 
+#### Formatted
+
+Decorates a validator to format input values in error messages while still validating the original input:
+
+```php
+use Respect\StringFormatter\FormatterBuilder as f;
+
+v::formatted(f::mask('1-4'), v::email())->assert('not an email');
+// → "****an email" must be an email address
+
+v::formatted(f::pattern('#### #### #### ####'), v::creditCard())->assert('1234123412341234');
+// → "1234 1234 1234 1234" must be a credit card number
+```
+
 #### ShortCircuit
 
 Validates input against a series of validators, stopping at the first failure. Useful for dependent validations:
@@ -717,18 +731,6 @@ v::factory(
 )->assert(['password' => 'secret', 'confirmation' => 'secret']); // passes
 ```
 
-#### Masked
-
-Decorates a validator to mask sensitive input values in error messages while still validating the original unmasked data. This allows applications to protect sensitive information like passwords, credit cards, or emails without implementing a custom layer between Validation and end users:
-
-```php
-v::masked('1-@', v::email(),v::email())->assert('invalid@example.com');
-// → "*******@example.com" must be a valid email address
-
-v::masked('6-12', v::creditCard(), 'X')->assert('4111111111111211');
-// → "41111XXXXXXX1211" must be a valid credit card number
-```
-
 #### Named
 
 Customizes the subject name in error messages:

docs/validators.md

@@ -27,7 +27,7 @@ In this page you will find a list of validators by their category.
 
 **Date and Time**: [Date][] - [DateTime][] - [DateTimeDiff][] - [LeapDate][] - [LeapYear][] - [Time][]
 
-**Display**: [Format][] - [Masked][] - [Named][] - [Templated][]
+**Display**: [Format][] - [Formatted][] - [Named][] - [Templated][]
 
 **File system**: [Directory][] - [Executable][] - [Exists][] - [Extension][] - [File][] - [Image][] - [Mimetype][] - [Readable][] - [Size][] - [SymbolicLink][] - [Writable][]
 
@@ -41,7 +41,7 @@ In this page you will find a list of validators by their category.
 
 **Math**: [Factor][] - [Finite][] - [Infinite][] - [Multiple][] - [Negative][] - [Positive][]
 
-**Miscellaneous**: [Blank][] - [Falsy][] - [Masked][] - [Named][] - [Templated][] - [Undef][]
+**Miscellaneous**: [Blank][] - [Falsy][] - [Named][] - [Templated][] - [Undef][]
 
 **Nesting**: [After][] - [AllOf][] - [AnyOf][] - [Each][] - [Factory][] - [Key][] - [KeySet][] - [NoneOf][] - [Not][] - [NullOr][] - [OneOf][] - [Property][] - [PropertyOptional][] - [ShortCircuit][] - [UndefOr][] - [When][]
 
@@ -53,7 +53,7 @@ In this page you will find a list of validators by their category.
 
 **Structures**: [Attributes][] - [Key][] - [KeyExists][] - [KeyOptional][] - [KeySet][] - [Property][] - [PropertyExists][] - [PropertyOptional][]
 
-**Transformations**: [After][] - [All][] - [Each][] - [Length][] - [Max][] - [Min][] - [Size][]
+**Transformations**: [After][] - [All][] - [Each][] - [Formatted][] - [Length][] - [Max][] - [Min][] - [Size][]
 
 **Types**: [ArrayType][] - [ArrayVal][] - [BoolType][] - [BoolVal][] - [CallableType][] - [Countable][] - [FloatType][] - [FloatVal][] - [IntType][] - [IntVal][] - [IterableType][] - [IterableVal][] - [NullType][] - [NumericVal][] - [ObjectType][] - [ResourceType][] - [ScalarVal][] - [StringType][] - [StringVal][]
 
@@ -118,6 +118,7 @@ In this page you will find a list of validators by their category.
 - [FloatType][] - `v::floatType()->assert(1.5);`
 - [FloatVal][] - `v::floatVal()->assert(1.5);`
 - [Format][] - `v::format(f::pattern('00-00'))->assert('42-33');`
+- [Formatted][] - `v::formatted(f::mask('1-4'), v::email())->assert('foo@example.com');`
 - [Graph][] - `v::graph()->assert('LKM@#$%4;');`
 - [GreaterThan][] - `v::greaterThan(10)->assert(11);`
 - [GreaterThanOrEqual][] - `v::intVal()->greaterThanOrEqual(10)->assert(10);`
@@ -150,7 +151,6 @@ 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('1-@', 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]);`
@@ -275,6 +275,7 @@ In this page you will find a list of validators by their category.
 [FloatType]: validators/FloatType.md "Validates whether the type of the input is float."
 [FloatVal]: validators/FloatVal.md "Validate whether the input value is float."
 [Format]: validators/Format.md "Validates whether an input is already formatted as the result of applying a provided"
+[Formatted]: validators/Formatted.md "Decorates a validator to format input values in error messages while still validating the original input."
 [Graph]: validators/Graph.md "Validates if all characters in the input are printable and actually creates"
 [GreaterThan]: validators/GreaterThan.md "Validates whether the input is greater than a value."
 [GreaterThanOrEqual]: validators/GreaterThanOrEqual.md "Validates whether the input is greater than or equal to a value."
@@ -307,7 +308,6 @@ 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."

docs/validators/Format.md

@@ -62,7 +62,6 @@ stored data follows a required display format).
 
 ## See Also
 
-- [Masked](Masked.md)
 - [Templated](Templated.md)
 
 [Respect\StringFormatter]: https://github.com/Respect/StringFormatter

docs/validators/Formatted.md

@@ -0,0 +1,51 @@
+<!--
+SPDX-License-Identifier: MIT
+SPDX-FileCopyrightText: (c) Respect Project Contributors
+SPDX-FileContributor: Henrique Moody <henriquemoody@gmail.com>
+-->
+
+# Formatted
+
+- `Formatted(Formatter $formatter, Validator $validator)`
+
+Decorates a validator to format input values in error messages while still validating the original input.
+
+```php
+use Respect\StringFormatter\FormatterBuilder as f;
+
+v::formatted(f::mask('1-4'), v::email())->assert('foo@example.com');
+// Validation passes successfully
+
+v::formatted(f::mask('1-4'), v::email())->assert('not an email');
+// → "****an email" must be an email address
+
+v::formatted(f::pattern('#### #### #### ####'), v::creditCard())->assert('4111111111111111');
+// Validation passes successfully
+
+v::formatted(f::pattern('#### #### #### ####'), v::creditCard())->assert('1234123412341234');
+// → "1234 1234 1234 1234" must be a credit card number
+```
+
+This validator is useful for displaying formatted values in error messages, making them more readable for end users. For example, showing credit card numbers with spaces or phone numbers with proper formatting.
+
+It uses [respect/string-formatter](https://github.com/Respect/StringFormatter) as the underlying formatting engine. See the [StringFormatter documentation](https://github.com/Respect/StringFormatter) for available formatters.
+
+## Behavior
+
+The validator first ensures the input is a valid string using `StringVal`. If the input passes string validation, it validates the original input using the inner validator. The formatted version is only used for display in error messages.
+
+## Categorization
+
+- Display
+- Transformations
+
+## Changelog
+
+| Version | Description |
+| ------: | :---------- |
+|   3.0.0 | Created     |
+
+## See Also
+
+- [Named](Named.md)
+- [Templated](Templated.md)

docs/validators/Named.md

@@ -53,6 +53,5 @@ This validator does not have any templates, as it will use the template of the g
 ## See Also
 
 - [Attributes](Attributes.md)
-- [Masked](Masked.md)
 - [Not](Not.md)
 - [Templated](Templated.md)

docs/validators/Templated.md

@@ -54,6 +54,5 @@ This validator does not have any templates, as you must define the templates you
 ## See Also
 
 - [Attributes](Attributes.md)
-- [Masked](Masked.md)
 - [Named](Named.md)
 - [Not](Not.md)

src-dev/Commands/LintMixinCommand.php

@@ -111,6 +111,7 @@ final class LintMixinCommand extends Command
         'PropertyExists',
         'PropertyOptional',
         'Attributes',
+        'Formatted',
         'Templated',
         'Named',
     ];