From 0984459916babda81915d9f41246e2d13dac6dc9 Mon Sep 17 00:00:00 2001
From: Javier Eguiluz <javier.eguiluz@gmail.com>
Date: Fri, 15 May 2020 16:58:26 +0200
Subject: [PATCH] [Validator] Documented the ExpressionLanguageSyntax
 constraint

---
 reference/constraints.rst                     |   1 +
 .../constraints/ExpressionLanguageSyntax.rst  | 129 ++++++++++++++++++
 reference/constraints/map.rst.inc             |   1 +
 3 files changed, 131 insertions(+)
 create mode 100644 reference/constraints/ExpressionLanguageSyntax.rst

diff --git a/reference/constraints.rst b/reference/constraints.rst
index faa5ed3cac2..1aeaca354e7 100644
--- a/reference/constraints.rst
+++ b/reference/constraints.rst
@@ -14,6 +14,7 @@ Validation Constraints Reference
    constraints/Type
 
    constraints/Email
+   constraints/ExpressionLanguageSyntax
    constraints/Length
    constraints/Url
    constraints/Regex
diff --git a/reference/constraints/ExpressionLanguageSyntax.rst b/reference/constraints/ExpressionLanguageSyntax.rst
new file mode 100644
index 00000000000..61a32b901e9
--- /dev/null
+++ b/reference/constraints/ExpressionLanguageSyntax.rst
@@ -0,0 +1,129 @@
+ExpressionLanguageSyntax
+========================
+
+This constraint checks that the value is valid as an `ExpressionLanguage`_
+expression.
+
+.. versionadded:: 5.1
+
+    The ``ExpressionLanguageSyntax`` constraint was introduced in Symfony 5.1.
+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Options     - `allowedVariables`_
+            - `groups`_
+            - `message`_
+            - `payload`_
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\ExpressionLanguageSyntax`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\ExpressionLanguageSyntaxValidator`
+==========  ===================================================================
+
+Basic Usage
+-----------
+
+The following constraints ensure that:
+
+* the ``promotion`` propery stores a value which is valid as an
+  ExpressionLanguage expression;
+* the ``shippingOptions`` property also ensures that the expression only uses
+  certain variables.
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/Entity/Order.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Order
+        {
+            /**
+             * @Assert\ExpressionLanguageSyntax()
+             */
+            protected $promotion;
+
+            /**
+             * @Assert\ExpressionLanguageSyntax(
+             *     allowedVariables = ['user', 'shipping_centers']
+             * )
+             */
+            protected $shippingOptions;
+        }
+
+    .. code-block:: yaml
+
+        # config/validator/validation.yaml
+        App\Entity\Order:
+            properties:
+                promotion:
+                    - ExpressionLanguageSyntax: ~
+                shippingOptions:
+                    - ExpressionLanguageSyntax:
+                        allowedVariables: ['user', 'shipping_centers']
+
+    .. 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\Order">
+                <property name="promotion">
+                    <constraint name="ExpressionLanguageSyntax"/>
+                </property>
+                <property name="shippingOptions">
+                    <constraint name="ExpressionLanguageSyntax">
+                        <option name="allowedVariables">['user', 'shipping_centers']</option>
+                    </constraint>
+                </property>
+            </class>
+        </constraint-mapping>
+
+    .. code-block:: php
+
+        // src/Entity/Student.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+
+        class Order
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('promotion', new Assert\ExpressionLanguageSyntax());
+
+                $metadata->addPropertyConstraint('shippingOptions', new Assert\ExpressionLanguageSyntax([
+                    'allowedVariables' => ['user', 'shipping_centers'],
+                ]));
+            }
+        }
+
+Options
+-------
+
+allowedVariables
+~~~~~~~~~~~~~~~~
+
+**type**: ``array`` or ``null`` **default**: ``null``
+
+If this option is defined, the expression can only use the variables whose names
+are included in this option. Unset this option or set its value to ``null`` to
+allow any variables.
+
+.. include:: /reference/constraints/_groups-option.rst.inc
+
+message
+~~~~~~~
+
+**type**: ``string`` **default**: ``This value should be a valid expression.``
+
+This is the message displayed when the validation fails.
+
+.. include:: /reference/constraints/_payload-option.rst.inc
+
+.. _`ExpressionLanguage`: https://symfony.com/components/ExpressionLanguage
diff --git a/reference/constraints/map.rst.inc b/reference/constraints/map.rst.inc
index 05e820db8ee..2d16e7e34ee 100644
--- a/reference/constraints/map.rst.inc
+++ b/reference/constraints/map.rst.inc
@@ -16,6 +16,7 @@ String Constraints
 ~~~~~~~~~~~~~~~~~~
 
 * :doc:`Email </reference/constraints/Email>`
+* :doc:`ExpressionLanguageSyntax </reference/constraints/ExpressionLanguageSyntax>`
 * :doc:`Length </reference/constraints/Length>`
 * :doc:`Url </reference/constraints/Url>`
 * :doc:`Regex </reference/constraints/Regex>`