Add formatter shorthand aliases using formattedAs* prefix

Introduce FormattedPrefixTransformer to support shorthand method names
like formattedAsMask(), formattedAsPattern(), and formattedAsDate().
These expand internally to formatted(FormatterBuilder::mask(...), validator),
removing the need to manually construct FormatterBuilder instances.

The formattedAs* prefix pattern avoids conflicts with validators that
share names with formatters (e.g., date validator vs date formatter).
The transformer handles both direct calls (formattedAsMask) and prefixed
calls (notFormattedAsMask) where the prefix transformer capitalizes the
remainder to FormattedAsMask.

The LintMixinCommand scans formatter classes from the string-formatter
package and generates corresponding alias methods across all mixin
interfaces, ensuring the first parameter is always mandatory and
including docblocks from formatter constructors.

Assisted-by: Claude Code (claude-opus-4-5-20251101)

Author: henriquemoody

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

@@ -674,6 +674,20 @@ v::formatted(f::pattern('#### #### #### ####'), v::creditCard())->assert('123412
 // → "1234 1234 1234 1234" must be a credit card number
 ```
 
+Shorthand aliases are available that combine formatter creation with the validator:
+
+```php
+v::formattedAsMask('1-4', v::email())->assert('not an email');
+v::formattedAsPattern('#### #### #### ####', v::creditCard())->assert('1234123412341234');
+```
+
+These aliases work with all prefixes (`not`, `nullOr`, `key`, `property`, etc.):
+
+```php
+v::notFormattedAsMask('1-4', v::email())->assert('user@example.com');
+v::keyFormattedAsPattern('cc', '#### #### #### ####', v::creditCard())->assert($data);
+```
+
 #### ShortCircuit
 
 Validates input against a series of validators, stopping at the first failure. Useful for dependent validations:
@@ -866,6 +880,10 @@ v::lengthBetween(5, 10)->assert('hello'); // passes
 v::minGreaterThan(0)->assert([1, 2, 3]);  // passes
 v::maxLessThan(10)->assert([1, 2, 3]);    // passes
 
+// Formatted shortcuts
+v::formattedAsMask('1-4', v::email())->assert('invalid');     // formats as "****lid"
+v::formattedAsPattern('##/##', v::date())->assert('invalid'); // formats with pattern
+
 // Negation prefix
 v::notBlank()->assert('hello'); // passes
 ```

docs/validators/Formatted.md

@@ -30,6 +30,49 @@ This validator is useful for displaying formatted values in error messages, maki
 
 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.
 
+## Shorthand aliases
+
+For convenience, shorthand methods are available that combine the formatter creation with the `Formatted` validator:
+
+```php
+v::formatted(f::mask('1-@'), v::email())->assert('not an email');
+// → "not an email" must be an email address
+
+v::formattedAsMask('1-@', v::email())->assert('not an email');
+// → "not an email" must be an email address
+
+v::formattedAsPattern('#### #### #### ####', v::creditCard())->assert('1234123412341234');
+// → "1234 1234 1234 1234" must be a credit card number
+```
+
+These aliases follow the pattern `formattedAs{FormatterName}`. The validator position varies depending on the formatter:
+
+Available shorthand aliases:
+- `formattedAsDate(Validator $validator, string $format = 'Y-m-d H:i:s')` - validator first, all args optional
+- `formattedAsMask(string $range, Validator $validator, string $replacement = '*')` - validator after required `$range`
+- `formattedAsNumber(Validator $validator, int $decimals = 0, string $decimalSeparator = '.', string $thousandsSeparator = ',')` - validator first, all args optional
+- `formattedAsPattern(string $pattern, Validator $validator)` - validator after required `$pattern`
+
+Examples with different validator positions:
+
+```php
+v::formattedAsMask('1-4', v::email())->assert('not an email');
+// → "****an email" must be an email address
+
+v::formattedAsDate(v::equals('2020-01-01'), 'd/m/Y')->assert('2024-12-25');
+// → "25/12/2024" must be equal to "2020-01-01"
+
+v::formattedAsNumber(v::intVal(), 2, ',', '.')->assert('1234.56');
+// → "1.234,56" must be an integer
+```
+
+The aliases also work with prefixes like `not`, `nullOr`, `key`, etc.:
+
+```php
+v::notFormattedAsMask('1-@', v::email())->assert('user@example.com');
+// → "****@example.com" must not be an email address
+```
+
 ## 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.

src-dev/Commands/LintMixinCommand.php

@@ -41,6 +41,7 @@
 use Respect\Validation\Mixins\PropertyChain;
 use Respect\Validation\Mixins\UndefOrBuilder;
 use Respect\Validation\Mixins\UndefOrChain;
+use Respect\Validation\Transformers\FormattedPrefixTransformer;
 use Respect\Validation\Validator;
 use Respect\Validation\ValidatorBuilder;
 use Symfony\Component\Console\Attribute\AsCommand;
@@ -208,6 +209,30 @@ protected function execute(InputInterface $input, OutputInterface $output): int
                 );
             }
 
+            $formatters = $this->scanFormatters();
+            foreach ($formatters as [$formatterMethodName, $formatterReflection, $validatorPosition]) {
+                $this->addFormatterAliasToInterface(
+                    $staticNamespace,
+                    $formatterMethodName,
+                    $staticInterface,
+                    $formatterReflection,
+                    $validatorPosition,
+                    $prefix,
+                    $allowList,
+                    $denyList,
+                );
+                $this->addFormatterAliasToInterface(
+                    $chainedNamespace,
+                    $formatterMethodName,
+                    $chainedInterface,
+                    $formatterReflection,
+                    $validatorPosition,
+                    $prefix,
+                    $allowList,
+                    $denyList,
+                );
+            }
+
             $printer = new Printer();
             $printer->wrapLength = 300;
 
@@ -274,6 +299,94 @@ private function scanValidators(string $directory): array
         return $names;
     }
 
+    /** @return array<array{string, ReflectionClass, int}> */
+    private function scanFormatters(): array
+    {
+        $formatters = [];
+
+        foreach (FormattedPrefixTransformer::FORMATTERS as $formatterName => $validatorPosition) {
+            $className = 'Respect\\StringFormatter\\' . ucfirst($formatterName) . 'Formatter';
+            $reflection = new ReflectionClass($className);
+
+            // e.g. mask -> formattedAsMask
+            $methodName = 'formattedAs' . ucfirst($formatterName);
+
+            $formatters[] = [$methodName, $reflection, $validatorPosition];
+        }
+
+        return $formatters;
+    }
+
+    /**
+     * @param array<string> $allowList
+     * @param array<string> $denyList
+     */
+    private function addFormatterAliasToInterface(
+        PhpNamespace $namespace,
+        string $methodName,
+        InterfaceType $interfaceType,
+        ReflectionClass $formatterReflection,
+        int $validatorPosition,
+        string|null $prefix,
+        array $allowList,
+        array $denyList,
+    ): void {
+        // Apply same allow/deny logic as the Formatted validator
+        if ($allowList !== [] && !in_array('Formatted', $allowList, true)) {
+            return;
+        }
+
+        if ($denyList !== [] && in_array('Formatted', $denyList, true)) {
+            return;
+        }
+
+        $name = $prefix ? $prefix . ucfirst($methodName) : $methodName;
+        $method = $interfaceType->addMethod($name)->setPublic()->setReturnType(Chain::class);
+
+        if (str_contains($interfaceType->getName(), 'Builder')) {
+            $method->setStatic();
+        }
+
+        if ($prefix === 'key') {
+            $method->addParameter('key')->setType('int|string');
+        }
+
+        if ($prefix === 'property') {
+            $method->addParameter('propertyName')->setType('string');
+        }
+
+        $reflectionConstructor = $formatterReflection->getConstructor();
+
+        $comment = $reflectionConstructor->getDocComment();
+        if ($comment) {
+            $method->addComment(preg_replace('@(/\*\* *| +\* +| +\*/)@', '', $comment));
+        }
+
+        $formatterParams = $reflectionConstructor->getParameters();
+
+        // Add formatter constructor params, inserting Validator at the specified position
+        $validatorInserted = false;
+        foreach ($formatterParams as $index => $reflectionParameter) {
+            if ($index === $validatorPosition && !$validatorInserted) {
+                $namespace->addUse(Validator::class);
+                $method->addParameter('validator')->setType(Validator::class);
+                $validatorInserted = true;
+            }
+
+            // Make parameters before the validator position mandatory
+            $forceMandatory = $index < $validatorPosition;
+            $this->addParameterToMethod($method, $reflectionParameter, $namespace, $forceMandatory);
+        }
+
+        if ($validatorInserted) {
+            return;
+        }
+
+        // Validator goes at position 0 or after all formatter params
+        $namespace->addUse(Validator::class);
+        $method->addParameter('validator')->setType(Validator::class);
+    }
+
     /**
      * @param array<string> $allowList
      * @param array<string> $denyList
@@ -329,6 +442,7 @@ private function addParameterToMethod(
         Method $method,
         ReflectionParameter $reflectionParameter,
         PhpNamespace $namespace,
+        bool $forceMandatory = false,
     ): void {
         if ($reflectionParameter->isVariadic()) {
             $method->setVariadic();
@@ -364,6 +478,10 @@ private function addParameterToMethod(
         $parameter = $method->addParameter($reflectionParameter->getName());
         $parameter->setType(implode('|', $types));
 
+        if ($forceMandatory) {
+            return;
+        }
+
         if (!$reflectionParameter->isDefaultValueAvailable()) {
             $parameter->setNullable($reflectionParameter->isOptional());
         }

src/ContainerRegistry.php

@@ -38,7 +38,8 @@
 use Respect\Validation\Message\Parameters\PathHandler;
 use Respect\Validation\Message\Parameters\ResultHandler;
 use Respect\Validation\Message\Renderer;
-use Respect\Validation\Transformers\Prefix;
+use Respect\Validation\Transformers\FormattedPrefixTransformer;
+use Respect\Validation\Transformers\PrefixTransformer;
 use Respect\Validation\Transformers\Transformer;
 use Symfony\Contracts\Translation\TranslatorInterface;
 
@@ -55,7 +56,7 @@ public static function createContainer(array $definitions = []): Container
     {
         return new Container($definitions + [
             PhoneNumberUtil::class => factory(static fn() => PhoneNumberUtil::getInstance()),
-            Transformer::class => create(Prefix::class),
+            Transformer::class => factory(static fn() => new FormattedPrefixTransformer(new PrefixTransformer())),
             TemplateResolver::class => create(TemplateResolver::class),
             TranslatorInterface::class => autowire(BypassTranslator::class),
             Renderer::class => autowire(InterpolationRenderer::class),