feature #15541 [Validator] Add attributes documentation of composite constraints (alexandre-daubois)

This PR was merged into the 5.4 branch.

Discussion
----------

[Validator] Add attributes documentation of composite constraints

Related pull-request: symfony/symfony#41994

Not really sure how to precise it only works for attributes in PHP 8.1, not 8.0. If you have a solution, please let me know!

Commits
-------

7099e3f [Validator] Add attributes documentation of composite constraints

Author: wouterj

reference/constraints/All.rst

@@ -36,6 +36,23 @@ entry in that array:
             protected $favoriteColors = [];
         }
 
+    .. code-block:: php-attributes
+
+        // src/Entity/User.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        // IMPORTANT: nested attributes requires PHP 8.1 or higher
+        class User
+        {
+            #[Assert\All([
+                new Assert\NotBlank,
+                new Assert\Length(min: 5),
+            ])]
+            protected $favoriteColors = [];
+        }
+
     .. code-block:: yaml
 
         # config/validator/validation.yaml
@@ -90,6 +107,11 @@ entry in that array:
             }
         }
 
+.. versionadded:: 5.4
+
+    The ``#[All]`` PHP attribute was introduced in Symfony 5.4 and requires
+    PHP 8.1 (which added nested attribute support).
+
 Now, each entry in the ``favoriteColors`` array will be validated to not
 be blank and to be at least 5 characters long.
 

reference/constraints/AtLeastOneOf.rst

@@ -54,6 +54,31 @@ The following constraints ensure that:
             protected $grades;
         }
 
+    .. code-block:: php-attributes
+
+        // src/Entity/Student.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        // IMPORTANT: nested attributes requires PHP 8.1 or higher
+        class Student
+        {
+            #[Assert\AtLeastOneOf([
+                new Assert\Regex('/#/'),
+                new Assert\Length(min: 10),
+            ])]
+            protected $plainPassword;
+
+            #[Assert\AtLeastOneOf([
+                new Assert\Count(min: 3),
+                new Assert\All(
+                    new Assert\GreaterThanOrEqual(5)
+                ),
+            ])]
+            protected $grades;
+        }
+
     .. code-block:: yaml
 
         # config/validator/validation.yaml
@@ -143,6 +168,11 @@ The following constraints ensure that:
             }
         }
 
+.. versionadded:: 5.4
+
+    The ``#[AtLeastOneOf]`` PHP attribute was introduced in Symfony 5.4 and
+    requires PHP 8.1 (which added nested attribute support).
+
 Options
 -------
 

reference/constraints/Collection.rst

@@ -81,6 +81,35 @@ following:
             ];
         }
 
+    .. code-block:: php-attributes
+
+        // src/Entity/Author.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        // IMPORTANT: nested attributes requires PHP 8.1 or higher
+        class Author
+        {
+            #[Assert\Collection(
+                fields: [
+                    'personal_email' => new Assert\Email,
+                    'short_bio' => [
+                        new Assert\NotBlank,
+                        new Assert\Length(
+                            max: 100,
+                            maxMessage: 'Your short bio is too long!'
+                        )
+                    ]
+                ],
+                allowMissingFields: true,
+            )]
+            protected $profileData = [
+                'personal_email' => '...',
+                'short_bio' => '...',
+            ];
+        }
+
     .. code-block:: yaml
 
         # config/validator/validation.yaml
@@ -155,6 +184,11 @@ following:
             }
         }
 
+.. versionadded:: 5.4
+
+    The ``#[Collection]`` PHP attribute was introduced in Symfony 5.4 and
+    requires PHP 8.1 (which added nested attribute support).
+
 Presence and Absence of Fields
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

reference/constraints/Sequentially.rst

@@ -64,6 +64,27 @@ You can validate each of these constraints sequentially to solve these issues:
             public $address;
         }
 
+    .. code-block:: php-attributes
+
+        // src/Localization/Place.php
+        namespace App\Localization;
+
+        use App\Validator\Constraints as AcmeAssert;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        // IMPORTANT: nested attributes requires PHP 8.1 or higher
+        class Place
+        {
+            #[Assert\Sequentially([
+                new Assert\NotNull,
+                new Assert\Type('string'),
+                new Assert\Length(min: 10),
+                new Assert\Regex(Place::ADDRESS_REGEX),
+                new AcmeAssert\Geolocalizable,
+            ])]
+            public $address;
+        }
+
     .. code-block:: yaml
 
         # config/validator/validation.yaml
@@ -125,6 +146,11 @@ You can validate each of these constraints sequentially to solve these issues:
             }
         }
 
+.. versionadded:: 5.4
+
+    The ``#[Sequentially]`` PHP attribute was introduced in Symfony 5.4 and
+    requires PHP 8.1 (which added nested attribute support).
+
 Options
 -------