Create "Formatted" validator

The Formatted validator decorates another validator to transform how
input values appear in error messages, while still validating the
original unmodified input.

This is useful for improving the readability of error messages by
displaying values in a user-friendly formatd.

The validator accepts any Respect\StringFormatter\Formatter implementation,
allowing direct use of StringFormatter's fluent builder. As StringFormatter
expands with more formatters in future releases, users will automatically
benefit from the full range of formatting options.

Assisted-by: Claude Code (Opus 4.5)

Author: henriquemoody

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

@@ -585,6 +585,7 @@ 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                              |
@@ -659,6 +660,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:

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][] - [Masked][] - [Named][] - [Templated][]
 
 **File system**: [Directory][] - [Executable][] - [Exists][] - [Extension][] - [File][] - [Image][] - [Mimetype][] - [Readable][] - [Size][] - [SymbolicLink][] - [Writable][]
 
@@ -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);`
@@ -275,6 +276,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."

docs/validators/Formatted.md

@@ -0,0 +1,52 @@
+<!--
+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
+
+- [Masked](Masked.md)
+- [Named](Named.md)
+- [Templated](Templated.md)

src-dev/Commands/LintMixinCommand.php

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