[Validator] Add the Conditional constraint and validator docs

Author: wuchen90

reference/constraints.rst

@@ -71,6 +71,7 @@ Validation Constraints Reference
    constraints/Compound
    constraints/Callback
    constraints/Expression
+   constraints/Conditional
    constraints/All
    constraints/UserPassword
    constraints/NotCompromisedPassword

reference/constraints/Conditional.rst

@@ -0,0 +1,202 @@
+Conditional
+===========
+
+This constraint allows you to apply constraints validation only if the provided condition is matched.
+See `Basic Usage`_ for an example.
+
+==========  ===================================================================
+Applies to  :ref:`class <validation-class-target>`
+            or :ref:`property/method <validation-property-target>`
+Options     - :ref:`condition <reference-constraint-condition-option>`
+            - :ref:`constraints <reference-constraint-constraints-option>`
+            - `groups`_
+            - `payload`_
+            - `values`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Conditional`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\ConditionalValidator`
+==========  ===================================================================
+
+Basic Usage
+-----------
+
+Imagine you have a class ``Discount`` with ``type`` and ``value``
+properties::
+
+    // src/Model/Discount.php
+    namespace App\Model;
+
+    use Symfony\Component\Validator\Constraints as Assert;
+
+    class Discount
+    {
+        private $type;
+
+        private $value;
+
+        // ...
+
+        public function getType()
+        {
+            return $this->type;
+        }
+
+        public function getValue()
+        {
+            return $this->value;
+        }
+
+        // ...
+    }
+
+To validate the object, you have some requirements:
+
+A) If ``type`` is ``percent``, then ``value`` must be less than 100;
+B) If ``type`` is ``absolute``, then ``value`` can be anything;
+C) No matter the value of ``type``, the ``value`` must be greater than 0.
+
+One way to accomplish this is with the Conditional constraint:
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/Model/Discount.php
+        namespace App\Model;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Discount
+        {
+            /**
+             * @Assert\GreaterThan(0)
+             * @Assert\Conditional(
+             *     condition="this.type == 'percent'",
+             *     constraints={@LessThan(100, message="The value should be between 0 and 100!")}
+             * )
+             */
+            private $value;
+            // ...
+        }
+
+    .. code-block:: yaml
+
+        # config/validator/validation.yaml
+        App\Model\Discount:
+            properties:
+                value:
+                    - GreaterThan: 0
+                    - Conditional:
+                        condition: "this.type == 'percent'"
+                        constraints:
+                            - LessThan:
+                                value: 100
+                                message: "The value should be between 0 and 100!"
+
+    .. 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\Model\Discount">
+                <property name="value">
+                    <constraint name="GreaterThan">
+                        0
+                    </constraint>
+                    <constraint name="Conditional">
+                        <option name="condition">
+                            this.type == 'percent'
+                        </option>
+                        <option name="constraints">
+                            <constraint name="LessThan">
+                                <option name="value">100</option>
+                                <option name="message">The value should be between 0 and 100!</option>
+                            </constraint>
+                        </option>
+                    </constraint>
+                </property>
+            </class>
+        </constraint-mapping>
+
+    .. code-block:: php
+
+        // src/Model/Discount.php
+        namespace App\Model;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+
+        class Discount
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint(new Assert\GreaterThan(0));
+                $metadata->addPropertyConstraint(new Assert\Conditional([
+                    'condition' => 'this.type == "percent"',
+                    'constraints' => [
+                        new Assert\LessThan([
+                            'value' => 100,
+                        ]),
+                    ],
+                ]));
+            }
+
+            // ...
+        }
+
+The :ref:`condition <reference-constraint-condition-option>` option is the
+expression that must return true in order to trigger the validation of the attached constraints.
+To learn more about the expression language syntax, see
+:doc:`/components/expression_language/syntax`.
+
+For more information about the expression and what variables are available
+to you, see the :ref:`condition <reference-constraint-condition-option>`
+option details below.
+
+Options
+-------
+
+.. _reference-constraint-condition-option:
+
+``condition``
+~~~~~~~~~~~~~~
+
+**type**: ``string``
+
+The condition written with the expression language syntax that will be evaluated.
+If the expression evaluates to a false value (using ``==``, not ``===``),
+validation of constraints won't be triggered.
+
+To learn more about the expression language syntax, see
+:doc:`/components/expression_language/syntax`.
+
+Inside of the expression, you have access to up to 2 variables:
+
+Depending on how you use the constraint, you have access to 1 or 2 variables
+in your expression:
+
+* ``this``: The object being validated (e.g. an instance of Discount);
+* ``value``: The value of the property being validated (only available when
+  the constraint is applied directly to a property);
+
+.. _reference-constraint-constraints-option:
+
+``constraints``
+~~~~~~~~~~~~~~~
+
+**type**: ``array``
+
+The constraints that are applied if the condition is true.
+
+.. include:: /reference/constraints/_groups-option.rst.inc
+
+.. include:: /reference/constraints/_payload-option.rst.inc
+
+``values``
+~~~~~~~~~~
+
+**type**: ``array`` **default**: ``[]``
+
+The values of the custom variables used in the condition. Values can be of any
+type (numeric, boolean, strings, null, etc.)