[Validator] Add Cascade constraint documentation

alexandre-daubois · alexandre-daubois · commit 5dd6f2c53d45 · 2023-02-28T21:51:52.000+01:00
diff --git a/reference/constraints/Cascade.rst b/reference/constraints/Cascade.rst
@@ -0,0 +1,120 @@
+Cascade
+=======
+
+.. versionadded:: 5.2
+
+    The :class:`Symfony\\Component\\Validator\\Constraints\\Cascade` was
+    introduced in Symfony 5.2 and requires PHP 7.4.
+
+The Cascade constraint is used to validate a whole class. It allows to
+omit to add the :doc:`/reference/constraints/Valid` constraint on each
+child object of your class you want to validate.
+
+==========  ===================================================================
+Applies to  :ref:`class <validation-class-target>`
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Cascade`
+==========  ===================================================================
+
+Basic Usage
+-----------
+
+In the following example, the
+:class:`Symfony\\Component\\Validator\\Constraints\\Cascade` constraint
+will tell the validator to validate all fields of the class, including
+constraints that are set in the child classes ``BookMetadata`` and
+``Author``:
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/Model/BookCollection.php
+        namespace App\Model;
+
+        use App\Model\Author;
+        use App\Model\BookMetadata;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        /**
+         * @Assert\Cascade
+         */
+        class BookCollection
+        {
+            /**
+             * @Assert\NotBlank
+             */
+            protected $name = '';
+
+            public BookMetadata $metadata;
+
+            public Author $author;
+
+            // ...
+        }
+
+    .. code-block:: php-attributes
+
+        // src/Model/BookCollection.php
+        namespace App\Model;
+
+        use App\Model\Author;
+        use App\Model\BookMetadata;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        #[Assert\Cascade]
+        class BookCollection
+        {
+            #[Assert\NotBlank]
+            protected $name = '';
+
+            public BookMetadata $metadata;
+
+            public Author $author;
+
+            // ...
+        }
+
+    .. code-block:: yaml
+
+        # config/validator/validation.yaml
+        App\Entity\BookCollection:
+            constraints:
+                - Cascade: ~
+
+    .. code-block:: xml
+
+        <!-- config/validator/validation.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+
+            <class name="App\Entity\BookCollection">
+                <constraint name="Cascade"/>
+            </class>
+        </constraint-mapping>
+
+    .. code-block:: php
+
+        // src/Entity/BookCollection.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+
+        class BookCollection
+        {
+            // ...
+
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addConstraint(new Assert\Cascade());
+            }
+        }
+
+Options
+-------
+
+The ``groups`` option is not available for this constraint.
+
+.. include:: /reference/constraints/_payload-option.rst.inc
diff --git a/reference/constraints/map.rst.inc b/reference/constraints/map.rst.inc
@@ -96,6 +96,7 @@ Other Constraints
 * :doc:`Expression </reference/constraints/Expression>`
 * :doc:`All </reference/constraints/All>`
 * :doc:`Valid </reference/constraints/Valid>`
+* :doc:`Cascade </reference/constraints/Cascade>`
 * :doc:`Traverse </reference/constraints/Traverse>`
 * :doc:`Collection </reference/constraints/Collection>`
 * :doc:`Count </reference/constraints/Count>`
