From 152097ef100d3043e96a53d348aa4b38f59c07d2 Mon Sep 17 00:00:00 2001
From: Christian Flothmann <christian.flothmann@open.de>
Date: Thu, 11 Dec 2025 10:53:36 +0100
Subject: [PATCH] use named arguments to configure validation constraints

---
 reference/constraints/Collection.rst | 40 ++++++++++++++++------------
 validation/raw_values.rst            | 22 +++++++--------
 2 files changed, 34 insertions(+), 28 deletions(-)

diff --git a/reference/constraints/Collection.rst b/reference/constraints/Collection.rst
index c35a0103581..64cae139373 100644
--- a/reference/constraints/Collection.rst
+++ b/reference/constraints/Collection.rst
@@ -144,10 +144,10 @@ following:
                         'personal_email' => new Assert\Email(),
                         'short_bio' => [
                             new Assert\NotBlank(),
-                            new Assert\Length([
-                                'max' => 100,
-                                'maxMessage' => 'Your short bio is too long!',
-                            ]),
+                            new Assert\Length(
+                                max: 100,
+                                maxMessage: 'Your short bio is too long!',
+                            ),
                         ],
                     ],
                     allowMissingFields: true,
@@ -196,13 +196,13 @@ you can do the following:
         {
             #[Assert\Collection(
                 fields: [
-                    'personal_email' => new Assert\Required([
+                    'personal_email' => new Assert\Required(constraints: [
                         new Assert\NotBlank,
                         new Assert\Email,
                     ]),
-                    'alternate_email' => new Assert\Optional(
+                    'alternate_email' => new Assert\Optional(constraints: [
                         new Assert\Email
-                    ),
+                    ]),
                 ],
             )]
             protected array $profileData = ['personal_email' => 'email@example.com'];
@@ -218,11 +218,13 @@ you can do the following:
                         fields:
                             personal_email:
                                 - Required:
-                                    - NotBlank: ~
-                                    - Email: ~
+                                    constraints:
+                                        - NotBlank: ~
+                                        - Email: ~
                             alternate_email:
                                 - Optional:
-                                    - Email: ~
+                                    constraints:
+                                        - Email: ~
 
     .. code-block:: xml
 
@@ -238,13 +240,17 @@ you can do the following:
                         <option name="fields">
                             <value key="personal_email">
                                 <constraint name="Required">
-                                    <constraint name="NotBlank"/>
-                                    <constraint name="Email"/>
+                                    <option name="constraints">
+                                        <constraint name="NotBlank"/>
+                                        <constraint name="Email"/>
+                                    </option>
                                 </constraint>
                             </value>
                             <value key="alternate_email">
                                 <constraint name="Optional">
-                                    <constraint name="Email"/>
+                                    <option name="constraints">
+                                        <constraint name="Email"/>
+                                    </option>
                                 </constraint>
                             </value>
                         </option>
@@ -269,11 +275,11 @@ you can do the following:
             {
                 $metadata->addPropertyConstraint('profileData', new Assert\Collection(
                     fields: [
-                        'personal_email'  => new Assert\Required([
+                        'personal_email'  => new Assert\Required(constraints: [
                             new Assert\NotBlank(),
                             new Assert\Email(),
                         ]),
-                        'alternate_email' => new Assert\Optional(new Assert\Email()),
+                        'alternate_email' => new Assert\Optional(constraints: [new Assert\Email()]),
                     ],
                 ));
             }
@@ -293,8 +299,8 @@ groups. Take the following example::
 
     $constraint = new Assert\Collection(
         fields: [
-            'name' => new Assert\NotBlank(['groups' => 'basic']),
-            'email' => new Assert\NotBlank(['groups' => 'contact']),
+            'name' => new Assert\NotBlank(groups: ['basic']),
+            'email' => new Assert\NotBlank(groups: ['contact']),
         ],
     );
 
diff --git a/validation/raw_values.rst b/validation/raw_values.rst
index 4fecb7c44ee..03d2e2d9432 100644
--- a/validation/raw_values.rst
+++ b/validation/raw_values.rst
@@ -67,22 +67,22 @@ Validation of arrays is possible using the ``Collection`` constraint::
 
     $groups = new Assert\GroupSequence(['Default', 'custom']);
 
-    $constraint = new Assert\Collection([
+    $constraint = new Assert\Collection(fields: [
         // the keys correspond to the keys in the input array
-        'name' => new Assert\Collection([
-            'first_name' => new Assert\Length(['min' => 101]),
-            'last_name' => new Assert\Length(['min' => 1]),
+        'name' => new Assert\Collection(fields: [
+            'first_name' => new Assert\Length(min: 101),
+            'last_name' => new Assert\Length(min: 1),
         ]),
         'email' => new Assert\Email(),
-        'simple' => new Assert\Length(['min' => 102]),
+        'simple' => new Assert\Length(min: 102),
         'eye_color' => new Assert\Choice(choices: [3, 4]),
         'file' => new Assert\File(),
-        'password' => new Assert\Length(['min' => 60]),
-        'tags' => new Assert\Optional([
-            new Assert\Type('array'),
-            new Assert\Count(['min' => 1]),
+        'password' => new Assert\Length(min: 60),
+        'tags' => new Assert\Optional(constraints: [
+            new Assert\Type(type: 'array'),
+            new Assert\Count(min: 1),
             new Assert\All([
-                new Assert\Collection([
+                new Assert\Collection(constraints: [
                     'slug' => [
                         new Assert\NotBlank(),
                         new Assert\Type(['type' => 'string']),
@@ -91,7 +91,7 @@ Validation of arrays is possible using the ``Collection`` constraint::
                         new Assert\NotBlank(),
                     ],
                 ]),
-                new CustomUniqueTagValidator(['groups' => 'custom']),
+                new CustomUniqueTagValidator(groups: ['custom']),
             ]),
         ]),
     ]);