deprecate handling options in the base Constraint class

symfony · fabpot · Jul 8, 2025 · Jun 9, 2025 · Jul 6, 2025 · ee9112431cc044b9cf92ddb5b5424e0728a69c91
commit ee9112431cc044b9cf92ddb5b5424e0728a69c91
diff --git a/UPGRADE-7.4.md b/UPGRADE-7.4.md
@@ -39,3 +39,130 @@ Security
  * Deprecate callable firewall listeners, extend `AbstractListener` or implement `FirewallListenerInterface` instead
  * Deprecate `AbstractListener::__invoke`
  * Deprecate `LazyFirewallContext::__invoke()`
+
+Validator
+---------
+
+ * Deprecate evaluating options in the base `Constraint` class. Initialize properties in the constructor of the concrete constraint
+   class instead.
+
+   *Before*
+
+   ```php
+   class CustomConstraint extends Constraint
+   {
+       public $option1;
+       public $option2;
+
+       public function __construct(?array $options = null)
+       {
+           parent::__construct($options);
+       }
+   }
+   ```
+
+   *After*
+
+   ```php
+   use Symfony\Component\Validator\Attribute\HasNamedArguments;
+
+   class CustomConstraint extends Constraint
+   {
+       public $option1;
+       public $option2;
+
+       #[HasNamedArguments]
+       public function __construct($option1 = null, $option2 = null, ?array $groups = null, mixed $payload = null)
+       {
+           parent::__construct(null, $groups, $payload);
+
+           $this->option1 = $option1;
+           $this->option2 = $option2;
+       }
+   }
+   ```
+
+ * Deprecate the `getRequiredOptions()` method of the base `Constraint` class. Use mandatory constructor arguments instead.
+
+   *Before*
+
+   ```php
+   class CustomConstraint extends Constraint
+   {
+       public $option1;
+       public $option2;
+
+       public function __construct(?array $options = null)
+       {
+           parent::__construct($options);
+       }
+
+       public function getRequiredOptions()
+       {
+           return ['option1'];
+       }
+   }
+   ```
+
+   *After*
+
+   ```php
+   use Symfony\Component\Validator\Attribute\HasNamedArguments;
+
+   class CustomConstraint extends Constraint
+   {
+       public $option1;
+       public $option2;
+
+       #[HasNamedArguments]
+       public function __construct($option1, $option2 = null, ?array $groups = null, mixed $payload = null)
+       {
+           parent::__construct(null, $groups, $payload);
+
+           $this->option1 = $option1;
+           $this->option2 = $option2;
+       }
+   }
+   ```
+ * Deprecate the `normalizeOptions()` and `getDefaultOption()` methods of the base `Constraint` class without replacements.
+   Overriding them in child constraint will not have any effects starting with Symfony 8.0.
+ * Deprecate passing an array of options to the `Composite` constraint class. Initialize the properties referenced with `getNestedConstraints()`
+   in child classes before calling the constructor of `Composite`.
+
+   *Before*
+
+   ```php
+   class CustomCompositeConstraint extends Composite
+   {
+       public array $constraints = [];
+
+       public function __construct(?array $options = null)
+       {
+           parent::__construct($options);
+       }
+
+       protected function getCompositeOption(): string
+       {
+           return 'constraints';
+       }
+   }
+   ```
+
+   *After*
+
+   ```php
+   use Symfony\Component\Validator\Attribute\HasNamedArguments;
+
+   class CustomCompositeConstraint extends Composite
+   {
+       public array $constraints = [];
+
+       #[HasNamedArguments]
+       public function __construct(array $constraints, ?array $groups = null, mixed $payload = null)
+       {
+           $this->constraints = $constraints;
+
+           parent::__construct(null, $groups, $payload);
+       }
+   }
+   ```
diff --git a/src/Symfony/Bridge/Doctrine/Validator/Constraints/UniqueEntity.php b/src/Symfony/Bridge/Doctrine/Validator/Constraints/UniqueEntity.php
@@ -66,18 +66,21 @@ public function __construct(
             trigger_deprecation('symfony/validator', '7.3', 'Passing an array of options to configure the "%s" constraint is deprecated, use named arguments instead.', static::class);
 
             $options = array_merge($fields, $options ?? []);
+            $fields = null;
         } else {
             if (\is_array($options)) {
                 trigger_deprecation('symfony/validator', '7.3', 'Passing an array of options to configure the "%s" constraint is deprecated, use named arguments instead.', static::class);
+
+                $options['fields'] = $fields;
+                $fields = null;
             } else {
-                $options = [];
+                $options = null;
             }
-
-            $options['fields'] = $fields;
         }
 
         parent::__construct($options, $groups, $payload);
 
+        $this->fields = $fields ?? $this->fields;
         $this->message = $message ?? $this->message;
         $this->service = $service ?? $this->service;
         $this->em = $em ?? $this->em;

diff --git a/src/Symfony/Bridge/Doctrine/composer.json b/src/Symfony/Bridge/Doctrine/composer.json
@@ -41,7 +41,7 @@
         "symfony/translation": "^6.4|^7.0|^8.0",
         "symfony/type-info": "^7.1|^8.0",
         "symfony/uid": "^6.4|^7.0|^8.0",
-        "symfony/validator": "^6.4|^7.0|^8.0",
+        "symfony/validator": "^7.4|^8.0",
         "symfony/var-dumper": "^6.4|^7.0|^8.0",
         "doctrine/collections": "^1.8|^2.0",
         "doctrine/data-fixtures": "^1.1|^2",
@@ -64,7 +64,7 @@
         "symfony/property-info": "<6.4",
         "symfony/security-bundle": "<6.4",
         "symfony/security-core": "<6.4",
-        "symfony/validator": "<6.4"
+        "symfony/validator": "<7.4"
     },
     "autoload": {
         "psr-4": { "Symfony\\Bridge\\Doctrine\\": "" },

@@ -35,8 +35,6 @@ public function testValidatedByService(UserPassword $constraint)
 
     public static function provideServiceValidatedConstraints(): iterable
     {
-        yield 'Doctrine style' => [new UserPassword(['service' => 'my_service'])];
-
         yield 'named arguments' => [new UserPassword(service: 'my_service')];
 
         $metadata = new ClassMetadata(UserPasswordDummy::class);
@@ -45,6 +43,14 @@ public static function provideServiceValidatedConstraints(): iterable
         yield 'attribute' => [$metadata->properties['b']->constraints[0]];
     }
 
+    /**
+     * @group legacy
+     */
+    public function testValidatedByServiceDoctrineStyle()
+    {
+        self::assertSame('my_service', (new UserPassword(['service' => 'my_service']))->validatedBy());
+    }
+
     public function testAttributes()
     {
         $metadata = new ClassMetadata(UserPasswordDummy::class);

diff --git a/src/Symfony/Component/Validator/CHANGELOG.md b/src/Symfony/Component/Validator/CHANGELOG.md
@@ -1,6 +1,133 @@
 CHANGELOG
 =========
 
+7.4
+---
+
+ * Deprecate evaluating options in the base `Constraint` class. Initialize properties in the constructor of the concrete constraint
+   class instead.
+
+   Before:
+
+   ```php
+   class CustomConstraint extends Constraint
+   {
+       public $option1;
+       public $option2;
+
+       public function __construct(?array $options = null)
+       {
+           parent::__construct($options);
+       }
+   }
+   ```
+
+   After:
+
+   ```php
+   use Symfony\Component\Validator\Attribute\HasNamedArguments;
+
+   class CustomConstraint extends Constraint
+   {
+       public $option1;
+       public $option2;
+
+       #[HasNamedArguments]
+       public function __construct($option1 = null, $option2 = null, ?array $groups = null, mixed $payload = null)
+       {
+           parent::__construct(null, $groups, $payload);
+
+           $this->option1 = $option1;
+           $this->option2 = $option2;
+       }
+   }
+   ```
+
+ * Deprecate the `getRequiredOptions()` method of the base `Constraint` class. Use mandatory constructor arguments instead.
+
+   Before:
+
+   ```php
+   class CustomConstraint extends Constraint
+   {
+       public $option1;
+       public $option2;
+
+       public function __construct(?array $options = null)
+       {
+           parent::__construct($options);
+       }
+
+       public function getRequiredOptions()
+       {
+           return ['option1'];
+       }
+   }
+   ```
+
+   After:
+
+   ```php
+   use Symfony\Component\Validator\Attribute\HasNamedArguments;
+
+   class CustomConstraint extends Constraint
+   {
+       public $option1;
+       public $option2;
+
+       #[HasNamedArguments]
+       public function __construct($option1, $option2 = null, ?array $groups = null, mixed $payload = null)
+       {
+           parent::__construct(null, $groups, $payload);
+
+           $this->option1 = $option1;
+           $this->option2 = $option2;
+       }
+   }
+   ```
+ * Deprecate the `normalizeOptions()` and `getDefaultOption()` methods of the base `Constraint` class without replacements.
+   Overriding them in child constraint will not have any effects starting with Symfony 8.0.
+ * Deprecate passing an array of options to the `Composite` constraint class. Initialize the properties referenced with `getNestedConstraints()`
+   in child classes before calling the constructor of `Composite`.
+
+   Before:
+
+   ```php
+   class CustomCompositeConstraint extends Composite
+   {
+       public array $constraints = [];
+
+       public function __construct(?array $options = null)
+       {
+           parent::__construct($options);
+       }
+
+       protected function getCompositeOption(): string
+       {
+           return 'constraints';
+       }
+   }
+   ```
+
+   After:
+
+   ```php
+   use Symfony\Component\Validator\Attribute\HasNamedArguments;
+
+   class CustomCompositeConstraint extends Composite
+   {
+       public array $constraints = [];
+
+       #[HasNamedArguments]
+       public function __construct(array $constraints, ?array $groups = null, mixed $payload = null)
+       {
+           $this->constraints = $constraints;
+
+           parent::__construct(null, $groups, $payload);
+       }
+   }
+   ```
+
 7.3
 ---
 

diff --git a/src/Symfony/Component/Validator/Constraint.php b/src/Symfony/Component/Validator/Constraint.php
@@ -110,6 +110,17 @@ public function __construct(mixed $options = null, ?array $groups = null, mixed
     {
         unset($this->groups); // enable lazy initialization
 
+        if (null === $options && (\func_num_args() > 0 || (new \ReflectionMethod($this, 'getRequiredOptions'))->getDeclaringClass()->getName() === self::class)) {
+            if (null !== $groups) {
+                $this->groups = $groups;
+            }
+            $this->payload = $payload;
+
+            return;
+        }
+
+        trigger_deprecation('symfony/validator', '7.4', 'Support for evaluating options in the base Constraint class is deprecated. Initialize properties in the constructor of %s instead.', static::class);
+
         $options = $this->normalizeOptions($options);
         if (null !== $groups) {
             $options['groups'] = $groups;
@@ -122,6 +133,8 @@ public function __construct(mixed $options = null, ?array $groups = null, mixed
     }
 
     /**
+     * @deprecated since Symfony 7.4
+     *
      * @return array<string, mixed>
      */
     protected function normalizeOptions(mixed $options): array
@@ -241,6 +254,8 @@ public function addImplicitGroupName(string $group): void
      *
      * Override this method to define a default option.
      *
+     * @deprecated since Symfony 7.4
+     *
      * @see __construct()
      */
     public function getDefaultOption(): ?string
@@ -255,6 +270,8 @@ public function getDefaultOption(): ?string
      *
      * @return string[]
      *
+     * @deprecated since Symfony 7.4
+     *
      * @see __construct()
      */
     public function getRequiredOptions(): array