feature symfony#61528 [Validator] Allow using attributes to declare compile-time constraint metadata (nicolas-grekas)

This PR was merged into the 7.4 branch.

Discussion
----------

[Validator] Allow using attributes to declare compile-time constraint metadata

| Q             | A
| ------------- | ---
| Branch?       | 7.4
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Issues        | -
| License       | MIT

Prerequisite for symfony#61288

At the moment, validation attributes are read at runtime when `framework.validation.enable_attributes` is true.

This means they don't fit for bundles nor can't they be warmed up.

This PR fixes both issues by using a new `validator.attribute_metadata` resource tag, that's turned into a list of classes to parse for attributes at compile-time.

For apps, the tag is added by autoconfiguration: any `Constraint`-derived attributes found on a class in the `src/` folder will trigger the rule to add the tag.

For bundles (and for apps if they want to), the tag is added by explicit service configuration. In an "eat your own dog-food" spirit, this capability is used to declare the constraints of the `Form` class: instead of loading the `validation.xml` file, we now declare this service resource:
```php
        ->set('validator.form.attribute_metadata', Form::class)
            ->tag('container.excluded')
            ->tag('validator.attribute_metadata')
```

This reads the attributes added to the `Form` class:
```php
#[AssertForm()]
#[Traverse(false)]
class Form implements \IteratorAggregate, FormInterface, ClearableErrorsInterface
```

Bundles can do the same and replace their XML files by attributes.

As a next step, we could also deprecate runtime-discovery of attributes. This could be worth it if this discovery has a measurable performance impact. To be measured if one wants to dig this idea.

Side note: I'm hoping this could allow removing the yaml and xml config formats one day. For serialization metadata also (PR coming). BUT, this doesn't (yet) cover the use case of overriding metadata defined by bundles. For that, apps still have to use xml or yaml in config/validation/. I have an idea to cover this, coming to a next PR if it works.

(failures unrelated)

Commits
-------

0197b50 [Validator] Allow using attributes to declare compile-time constraint metadata

Author: nicolas-grekas

src/Symfony/Bundle/FrameworkBundle/CacheWarmer/ValidatorCacheWarmer.php

@@ -14,14 +14,15 @@
 use Symfony\Component\Cache\Adapter\ArrayAdapter;
 use Symfony\Component\Cache\Adapter\PhpArrayAdapter;
 use Symfony\Component\Validator\Mapping\Factory\LazyLoadingMetadataFactory;
+use Symfony\Component\Validator\Mapping\Loader\AttributeLoader;
 use Symfony\Component\Validator\Mapping\Loader\LoaderChain;
 use Symfony\Component\Validator\Mapping\Loader\LoaderInterface;
 use Symfony\Component\Validator\Mapping\Loader\XmlFileLoader;
 use Symfony\Component\Validator\Mapping\Loader\YamlFileLoader;
 use Symfony\Component\Validator\ValidatorBuilder;
 
 /**
- * Warms up XML and YAML validator metadata.
+ * Warms up validator metadata.
  *
  * @author Titouan Galopin <[email protected]>
  *
@@ -77,14 +78,14 @@ protected function warmUpPhpArrayAdapter(PhpArrayAdapter $phpArrayAdapter, array
     /**
      * @param LoaderInterface[] $loaders
      *
-     * @return XmlFileLoader[]|YamlFileLoader[]
+     * @return list<XmlFileLoader|YamlFileLoader|AttributeLoader>
      */
     private function extractSupportedLoaders(array $loaders): array
     {
         $supportedLoaders = [];
 
         foreach ($loaders as $loader) {
-            if ($loader instanceof XmlFileLoader || $loader instanceof YamlFileLoader) {
+            if (method_exists($loader, 'getMappedClasses')) {
                 $supportedLoaders[] = $loader;
             } elseif ($loader instanceof LoaderChain) {
                 $supportedLoaders = array_merge($supportedLoaders, $this->extractSupportedLoaders($loader->getLoaders()));

src/Symfony/Bundle/FrameworkBundle/DependencyInjection/Compiler/UnusedTagsPass.php

@@ -102,6 +102,7 @@ class UnusedTagsPass implements CompilerPassInterface
         'twig.extension',
         'twig.loader',
         'twig.runtime',
+        'validator.attribute_metadata',
         'validator.auto_mapper',
         'validator.constraint_validator',
         'validator.group_provider',

src/Symfony/Bundle/FrameworkBundle/DependencyInjection/FrameworkExtension.php

@@ -216,7 +216,9 @@
 use Symfony\Component\Uid\UuidV4;
 use Symfony\Component\Validator\Constraint;
 use Symfony\Component\Validator\Constraints\ExpressionLanguageProvider;
+use Symfony\Component\Validator\Constraints\Traverse;
 use Symfony\Component\Validator\ConstraintValidatorInterface;
+use Symfony\Component\Validator\DependencyInjection\AttributeMetadataPass as ValidatorAttributeMetadataPass;
 use Symfony\Component\Validator\GroupProviderInterface;
 use Symfony\Component\Validator\Mapping\Loader\PropertyInfoLoader;
 use Symfony\Component\Validator\ObjectInitializerInterface;
@@ -1801,22 +1803,31 @@ private function registerValidationConfiguration(array $config, ContainerBuilder
         $files = ['xml' => [], 'yml' => []];
         $this->registerValidatorMapping($container, $config, $files);
 
-        if (!empty($files['xml'])) {
+        if ($files['xml']) {
             $validatorBuilder->addMethodCall('addXmlMappings', [$files['xml']]);
         }
 
-        if (!empty($files['yml'])) {
+        if ($files['yml']) {
             $validatorBuilder->addMethodCall('addYamlMappings', [$files['yml']]);
         }
 
         $definition = $container->findDefinition('validator.email');
         $definition->replaceArgument(0, $config['email_validation_mode']);
 
-        if (\array_key_exists('enable_attributes', $config) && $config['enable_attributes']) {
+        // When attributes are disabled, it means from runtime-discovery only; autoconfiguration should still happen.
+        // And when runtime-discovery of attributes is enabled, we can skip compile-time autoconfiguration in debug mode.
+        if (class_exists(ValidatorAttributeMetadataPass::class) && (!($config['enable_attributes'] ?? false) || !$container->getParameter('kernel.debug'))) {
+            // The $reflector argument hints at where the attribute could be used
+            $container->registerAttributeForAutoconfiguration(Constraint::class, function (ChildDefinition $definition, Constraint $attribute, \ReflectionClass|\ReflectionMethod|\ReflectionProperty $reflector) {
+                $definition->addTag('validator.attribute_metadata');
+            });
+        }
+
+        if ($config['enable_attributes'] ?? false) {
             $validatorBuilder->addMethodCall('enableAttributeMapping');
         }
 
-        if (\array_key_exists('static_method', $config) && $config['static_method']) {
+        if ($config['static_method'] ?? false) {
             foreach ($config['static_method'] as $methodName) {
                 $validatorBuilder->addMethodCall('addMethodMapping', [$methodName]);
             }
@@ -1855,9 +1866,11 @@ private function registerValidatorMapping(ContainerBuilder $container, array $co
             $files['yaml' === $extension ? 'yml' : $extension][] = $path;
         };
 
-        if (ContainerBuilder::willBeAvailable('symfony/form', Form::class, ['symfony/framework-bundle', 'symfony/validator'])) {
-            $reflClass = new \ReflectionClass(Form::class);
-            $fileRecorder('xml', \dirname($reflClass->getFileName()).'/Resources/config/validation.xml');
+        if (!ContainerBuilder::willBeAvailable('symfony/form', Form::class, ['symfony/framework-bundle', 'symfony/validator'])) {
+            $container->removeDefinition('validator.form.attribute_metadata');
+        } elseif (!($r = new \ReflectionClass(Form::class))->getAttributes(Traverse::class) || !class_exists(ValidatorAttributeMetadataPass::class)) {
+            // BC with symfony/form & symfony/validator < 7.4
+            $fileRecorder('xml', \dirname($r->getFileName()).'/Resources/config/validation.xml');
         }
 
         foreach ($container->getParameter('kernel.bundles_metadata') as $bundle) {
@@ -2060,7 +2073,7 @@ private function registerSerializerConfiguration(array $config, ContainerBuilder
         }
 
         $serializerLoaders = [];
-        if (isset($config['enable_attributes']) && $config['enable_attributes']) {
+        if ($config['enable_attributes'] ?? false) {
             $attributeLoader = new Definition(AttributeLoader::class);
 
             $serializerLoaders[] = $attributeLoader;
@@ -2100,7 +2113,7 @@ private function registerSerializerConfiguration(array $config, ContainerBuilder
         $chainLoader->replaceArgument(0, $serializerLoaders);
         $container->getDefinition('serializer.mapping.cache_warmer')->replaceArgument(0, $serializerLoaders);
 
-        if (isset($config['name_converter']) && $config['name_converter']) {
+        if ($config['name_converter'] ?? false) {
             $container->setParameter('.serializer.name_converter', $config['name_converter']);
             $container->getDefinition('serializer.name_converter.metadata_aware')->setArgument(1, new Reference($config['name_converter']));
         }

src/Symfony/Bundle/FrameworkBundle/FrameworkBundle.php

@@ -75,6 +75,7 @@
 use Symfony\Component\Validator\DependencyInjection\AddAutoMappingConfigurationPass;
 use Symfony\Component\Validator\DependencyInjection\AddConstraintValidatorsPass;
 use Symfony\Component\Validator\DependencyInjection\AddValidatorInitializersPass;
+use Symfony\Component\Validator\DependencyInjection\AttributeMetadataPass;
 use Symfony\Component\VarExporter\Internal\Hydrator;
 use Symfony\Component\VarExporter\Internal\Registry;
 use Symfony\Component\Workflow\DependencyInjection\WorkflowDebugPass;
@@ -155,6 +156,7 @@ public function build(ContainerBuilder $container): void
         $container->addCompilerPass($registerListenersPass, PassConfig::TYPE_BEFORE_REMOVING);
         $this->addCompilerPassIfExists($container, AddConstraintValidatorsPass::class);
         $this->addCompilerPassIfExists($container, AddValidatorInitializersPass::class);
+        $this->addCompilerPassIfExists($container, AttributeMetadataPass::class);
         $this->addCompilerPassIfExists($container, AddConsoleCommandPass::class, PassConfig::TYPE_BEFORE_REMOVING);
         // must be registered before the AddConsoleCommandPass
         $container->addCompilerPass(new TranslationLintCommandPass(), PassConfig::TYPE_BEFORE_REMOVING, 10);

src/Symfony/Bundle/FrameworkBundle/Resources/config/validator.php

@@ -14,6 +14,7 @@
 use Symfony\Bundle\FrameworkBundle\CacheWarmer\ValidatorCacheWarmer;
 use Symfony\Component\Cache\Adapter\PhpArrayAdapter;
 use Symfony\Component\ExpressionLanguage\ExpressionLanguage;
+use Symfony\Component\Form\Form;
 use Symfony\Component\Validator\Constraints\EmailValidator;
 use Symfony\Component\Validator\Constraints\ExpressionLanguageProvider;
 use Symfony\Component\Validator\Constraints\ExpressionValidator;
@@ -127,5 +128,9 @@
                 service('property_info'),
             ])
             ->tag('validator.auto_mapper')
+
+        ->set('validator.form.attribute_metadata', Form::class)
+            ->tag('container.excluded')
+            ->tag('validator.attribute_metadata')
     ;
 };

src/Symfony/Bundle/FrameworkBundle/Tests/DependencyInjection/FrameworkExtensionTestCase.php

@@ -93,6 +93,7 @@
 use Symfony\Component\Translation\DependencyInjection\TranslatorPass;
 use Symfony\Component\Translation\LocaleSwitcher;
 use Symfony\Component\Translation\TranslatableMessage;
+use Symfony\Component\Validator\Constraints\Traverse;
 use Symfony\Component\Validator\DependencyInjection\AddConstraintValidatorsPass;
 use Symfony\Component\Validator\Validation;
 use Symfony\Component\Validator\Validator\ValidatorInterface;
@@ -1312,16 +1313,17 @@ public function testValidation()
         $projectDir = $container->getParameter('kernel.project_dir');
 
         $ref = new \ReflectionClass(Form::class);
-        $xmlMappings = [
-            \dirname($ref->getFileName()).'/Resources/config/validation.xml',
-            strtr($projectDir.'/config/validator/foo.xml', '/', \DIRECTORY_SEPARATOR),
-        ];
+        $xmlMappings = [];
+        if (!$ref->getAttributes(Traverse::class)) {
+            $xmlMappings[] = \dirname($ref->getFileName()).'/Resources/config/validation.xml';
+        }
+        $xmlMappings[] = strtr($projectDir.'/config/validator/foo.xml', '/', \DIRECTORY_SEPARATOR);
 
         $calls = $container->getDefinition('validator.builder')->getMethodCalls();
 
-        $annotations = !class_exists(FullStack::class);
+        $attributes = !class_exists(FullStack::class);
 
-        $this->assertCount($annotations ? 8 : 7, $calls);
+        $this->assertCount($attributes ? 8 : 7, $calls);
         $this->assertSame('setConstraintValidatorFactory', $calls[0][0]);
         $this->assertEquals([new Reference('validator.validator_factory')], $calls[0][1]);
         $this->assertSame('setGroupProviderLocator', $calls[1][0]);
@@ -1333,7 +1335,7 @@ public function testValidation()
         $this->assertSame('addXmlMappings', $calls[4][0]);
         $this->assertSame([$xmlMappings], $calls[4][1]);
         $i = 4;
-        if ($annotations) {
+        if ($attributes) {
             $this->assertSame('enableAttributeMapping', $calls[++$i][0]);
         }
         $this->assertSame('addMethodMapping', $calls[++$i][0]);
@@ -1408,15 +1410,19 @@ public function testValidationPaths()
         $this->assertEquals([new Reference('validator.mapping.cache.adapter')], $calls[8][1]);
 
         $xmlMappings = $calls[4][1][0];
-        $this->assertCount(3, $xmlMappings);
-        try {
-            // Testing symfony/symfony
-            $this->assertStringEndsWith('Component'.\DIRECTORY_SEPARATOR.'Form/Resources/config/validation.xml', $xmlMappings[0]);
-        } catch (\Exception $e) {
-            // Testing symfony/framework-bundle with deps=high
-            $this->assertStringEndsWith('symfony'.\DIRECTORY_SEPARATOR.'form/Resources/config/validation.xml', $xmlMappings[0]);
+
+        if (!(new \ReflectionClass(Form::class))->getAttributes(Traverse::class)) {
+            try {
+                // Testing symfony/symfony
+                $this->assertStringEndsWith('Component'.\DIRECTORY_SEPARATOR.'Form/Resources/config/validation.xml', $xmlMappings[0]);
+            } catch (\Exception $e) {
+                // Testing symfony/framework-bundle with deps=high
+                $this->assertStringEndsWith('symfony'.\DIRECTORY_SEPARATOR.'form/Resources/config/validation.xml', $xmlMappings[0]);
+            }
+            array_shift($xmlMappings);
         }
-        $this->assertStringEndsWith('TestBundle/Resources/config/validation.xml', $xmlMappings[1]);
+        $this->assertCount(2, $xmlMappings);
+        $this->assertStringEndsWith('TestBundle/Resources/config/validation.xml', $xmlMappings[0]);
 
         $yamlMappings = $calls[5][1][0];
         $this->assertCount(1, $yamlMappings);
@@ -1434,16 +1440,19 @@ public function testValidationPathsUsingCustomBundlePath()
 
         $calls = $container->getDefinition('validator.builder')->getMethodCalls();
         $xmlMappings = $calls[4][1][0];
-        $this->assertCount(3, $xmlMappings);
-
-        try {
-            // Testing symfony/symfony
-            $this->assertStringEndsWith('Component'.\DIRECTORY_SEPARATOR.'Form/Resources/config/validation.xml', $xmlMappings[0]);
-        } catch (\Exception $e) {
-            // Testing symfony/framework-bundle with deps=high
-            $this->assertStringEndsWith('symfony'.\DIRECTORY_SEPARATOR.'form/Resources/config/validation.xml', $xmlMappings[0]);
+
+        if (!(new \ReflectionClass(Form::class))->getAttributes(Traverse::class)) {
+            try {
+                // Testing symfony/symfony
+                $this->assertStringEndsWith('Component'.\DIRECTORY_SEPARATOR.'Form/Resources/config/validation.xml', $xmlMappings[0]);
+            } catch (\Exception $e) {
+                // Testing symfony/framework-bundle with deps=high
+                $this->assertStringEndsWith('symfony'.\DIRECTORY_SEPARATOR.'form/Resources/config/validation.xml', $xmlMappings[0]);
+            }
+            array_shift($xmlMappings);
         }
-        $this->assertStringEndsWith('CustomPathBundle/Resources/config/validation.xml', $xmlMappings[1]);
+        $this->assertCount(2, $xmlMappings);
+        $this->assertStringEndsWith('CustomPathBundle/Resources/config/validation.xml', $xmlMappings[0]);
 
         $yamlMappings = $calls[5][1][0];
         $this->assertCount(1, $yamlMappings);
@@ -1490,7 +1499,6 @@ public function testValidationMapping()
         $calls = $container->getDefinition('validator.builder')->getMethodCalls();
 
         $this->assertSame('addXmlMappings', $calls[4][0]);
-        $this->assertCount(3, $calls[4][1][0]);
 
         $this->assertSame('addYamlMappings', $calls[5][0]);
         $this->assertCount(3, $calls[5][1][0]);

src/Symfony/Component/Form/Extension/Validator/Constraints/Form.php

@@ -11,11 +11,13 @@
 
 namespace Symfony\Component\Form\Extension\Validator\Constraints;
 
+use Symfony\Component\Validator\Attribute\HasNamedArguments;
 use Symfony\Component\Validator\Constraint;
 
 /**
  * @author Bernhard Schussek <[email protected]>
  */
+#[\Attribute(\Attribute::TARGET_CLASS)]
 class Form extends Constraint
 {
     public const NOT_SYNCHRONIZED_ERROR = '1dafa156-89e1-4736-b832-419c2e501fca';
@@ -26,6 +28,12 @@ class Form extends Constraint
         self::NO_SUCH_FIELD_ERROR => 'NO_SUCH_FIELD_ERROR',
     ];
 
+    #[HasNamedArguments]
+    public function __construct(mixed $options = null, ?array $groups = null, mixed $payload = null)
+    {
+        parent::__construct($options, $groups, $payload);
+    }
+
     public function getTargets(): string|array
     {
         return self::CLASS_CONSTRAINT;

src/Symfony/Component/Form/Form.php

@@ -22,11 +22,13 @@
 use Symfony\Component\Form\Exception\RuntimeException;
 use Symfony\Component\Form\Exception\TransformationFailedException;
 use Symfony\Component\Form\Extension\Core\Type\TextType;
+use Symfony\Component\Form\Extension\Validator\Constraints\Form as AssertForm;
 use Symfony\Component\Form\Util\FormUtil;
 use Symfony\Component\Form\Util\InheritDataAwareIterator;
 use Symfony\Component\Form\Util\OrderedHashMap;
 use Symfony\Component\PropertyAccess\PropertyPath;
 use Symfony\Component\PropertyAccess\PropertyPathInterface;
+use Symfony\Component\Validator\Constraints\Traverse;
 
 /**
  * Form represents a form.
@@ -68,6 +70,8 @@
  *
  * @implements \IteratorAggregate<string, FormInterface>
  */
+#[AssertForm]
+#[Traverse(false)]
 class Form implements \IteratorAggregate, FormInterface, ClearableErrorsInterface
 {
     private ?FormInterface $parent = null;
@@ -301,7 +305,7 @@ public function setData(mixed $modelData): static
             if (null !== $dataClass && !$viewData instanceof $dataClass) {
                 $actualType = get_debug_type($viewData);
 
-                throw new LogicException('The form\'s view data is expected to be a "'.$dataClass.'", but it is a "'.$actualType.'". You can avoid this error by setting the "data_class" option to null or by adding a view transformer that transforms "'.$actualType.'" to an instance of "'.$dataClass.'".');
+                throw new LogicException(\sprintf('The form\'s view data is expected to be a "%s", but it is a "%s". You can avoid this error by setting the "data_class" option to null or by adding a view transformer that transforms "%2$s" to an instance of "%1$s".', $dataClass, $actualType));
             }
         }
 

src/Symfony/Component/Validator/CHANGELOG.md

@@ -4,6 +4,7 @@ CHANGELOG
 7.4
 ---
 
+ * Add `ValidatorBuilder::addAttributeMappings()` and `AttributeMetadataPass` to declare compile-time constraint metadata using attributes
  * Add the `Video` constraint for validating video files
  * Deprecate implementing `__sleep/wakeup()` on `GenericMetadata` implementations; use `__(un)serialize()` instead
  * Deprecate passing a list of choices to the first argument of the `Choice` constraint. Use the `choices` option instead

src/Symfony/Component/Validator/Constraint.php

@@ -27,6 +27,7 @@
  *
  * @author Bernhard Schussek <[email protected]>
  */
+#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_PROPERTY | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
 abstract class Constraint
 {
     /**