Add formatter shorthand aliases for the Formatted validator

Introduce a FormattedSuffix transformer that decorates the existing
Prefix transformer to support shorthand method names like
maskFormatted(), patternFormatted(), and placeholderFormatted(). These
expand internally to formatted(FormatterBuilder::mask(...), validator),
removing the need to manually construct FormatterBuilder instances.

The transformer intercepts specs whose name ends with "Formatted",
extracts the formatter name from the prefix, pops the Validator from
the second argument position, and delegates the remaining arguments to
FormatterBuilder::__callStatic() to build the Formatter instance.
This composes cleanly with the Prefix transformer, so combinations
like notMaskFormatted() and keyPatternFormatted() work automatically.

The LintMixinCommand is updated to scan formatter classes from the
string-formatter package and generate corresponding alias methods
across all mixin interfaces, following the same allow/deny list logic
as the Formatted validator itself. Feature test expectations are also
updated to match the current message templates.

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

Author: henriquemoody

src-dev/Commands/LintMixinCommand.php

@@ -22,6 +22,7 @@
 use ReflectionUnionType;
 use Respect\Dev\Differ\ConsoleDiffer;
 use Respect\Dev\Differ\Item;
+use Respect\StringFormatter\Formatter;
 use Respect\Validation\Mixins\AllBuilder;
 use Respect\Validation\Mixins\AllChain;
 use Respect\Validation\Mixins\Chain;
@@ -64,7 +65,10 @@
 use function preg_replace;
 use function sprintf;
 use function str_contains;
+use function str_ends_with;
 use function str_starts_with;
+use function strlen;
+use function substr;
 use function trim;
 use function ucfirst;
 
@@ -207,6 +211,28 @@ protected function execute(InputInterface $input, OutputInterface $output): int
                 );
             }
 
+            $formatters = $this->scanFormatters();
+            foreach ($formatters as [$formatterMethodName, $formatterReflection]) {
+                $this->addFormatterAliasToInterface(
+                    $staticNamespace,
+                    $formatterMethodName,
+                    $staticInterface,
+                    $formatterReflection,
+                    $prefix,
+                    $allowList,
+                    $denyList,
+                );
+                $this->addFormatterAliasToInterface(
+                    $chainedNamespace,
+                    $formatterMethodName,
+                    $chainedInterface,
+                    $formatterReflection,
+                    $prefix,
+                    $allowList,
+                    $denyList,
+                );
+            }
+
             $printer = new Printer();
             $printer->wrapLength = 300;
 
@@ -273,6 +299,111 @@ private function scanValidators(string $directory): array
         return $names;
     }
 
+    /** @return array<array{string, ReflectionClass}> */
+    private function scanFormatters(): array
+    {
+        $formatters = [];
+        $formatterDir = dirname(__DIR__, 2) . '/vendor/respect/string-formatter/src';
+
+        foreach (new DirectoryIterator($formatterDir) as $file) {
+            if (!$file->isFile()) {
+                continue;
+            }
+
+            $basename = $file->getBasename('.php');
+            if (!str_ends_with($basename, 'Formatter') || $basename === 'FormatterBuilder') {
+                continue;
+            }
+
+            $className = 'Respect\\StringFormatter\\' . $basename;
+            $reflection = new ReflectionClass($className);
+
+            if (!$reflection->implementsInterface(Formatter::class)) {
+                continue;
+            }
+
+            if ($reflection->isAbstract() || $reflection->getConstructor() === null) {
+                continue;
+            }
+
+            // e.g. MaskFormatter -> maskFormatted
+            $shortName = $reflection->getShortName();
+            $formatterName = lcfirst(substr($shortName, 0, -strlen('Formatter')));
+            $methodName = $formatterName . 'Formatted';
+
+            $formatters[] = [$methodName, $reflection];
+        }
+
+        return $formatters;
+    }
+
+    /**
+     * @param array<string> $allowList
+     * @param array<string> $denyList
+     */
+    private function addFormatterAliasToInterface(
+        PhpNamespace $namespace,
+        string $methodName,
+        InterfaceType $interfaceType,
+        ReflectionClass $formatterReflection,
+        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 as 2nd parameter
+        // The first parameter must always be mandatory
+        $validatorInserted = false;
+        foreach ($formatterParams as $index => $reflectionParameter) {
+            if ($index === 1 && !$validatorInserted) {
+                $namespace->addUse(Validator::class);
+                $method->addParameter('validator')->setType(Validator::class);
+                $validatorInserted = true;
+            }
+
+            $this->addParameterToMethod($method, $reflectionParameter, $namespace, $index === 0);
+        }
+
+        if ($validatorInserted) {
+            return;
+        }
+
+        $namespace->addUse(Validator::class);
+        $method->addParameter('validator')->setType(Validator::class);
+    }
+
     /**
      * @param array<string> $allowList
      * @param array<string> $denyList
@@ -328,6 +459,7 @@ private function addParameterToMethod(
         Method $method,
         ReflectionParameter $reflectionParameter,
         PhpNamespace $namespace,
+        bool $forceMandatory = false,
     ): void {
         if ($reflectionParameter->isVariadic()) {
             $method->setVariadic();
@@ -363,6 +495,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\FormattedSuffixTransformer;
+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 FormattedSuffixTransformer(new PrefixTransformer())),
             TemplateResolver::class => create(TemplateResolver::class),
             TranslatorInterface::class => autowire(BypassTranslator::class),
             Renderer::class => autowire(InterpolationRenderer::class),