Merge remote-tracking branch 'origin/2.4' into 2.4

Grégory Quatannens · Grégory Quatannens · commit a9c157012bbe · 2014-06-10T08:57:27.000+02:00
diff --git a/reference/constraints/Callback.rst b/reference/constraints/Callback.rst
@@ -1,7 +1,12 @@
 Callback
 ========
 
-Le but de l'assertion Callback est de vous permettre de créer entièrement des
+.. versionadded:: 2.4
+    L'assertion ``Callback`` a été simplifiée dans Symfony 2.4. Pour des exemples
+    d'utilisation avec des versions antérieures de Symfony, lisez les versions
+    correspondantes de cette page.
+
+Le but de la contrainte Callback est de vous permettre de créer entièrement des
 règles de validation personnalisées et d'assigner des erreurs de validation à
 des champs spécifiques de votre objet. Si vous utilisez la validation de formulaires,
 cela signifie que vous pouvez faire en sorte que ces erreurs personnalisées s'affichent
@@ -18,9 +23,9 @@ sorte de choses, incluant la création et l'assignation d'erreurs de validation.
     possibilité d'ajouter directement des « violations » de validateur.
 
 +----------------+------------------------------------------------------------------------+
-| S'applique à   | :ref:`classe<validation-class-target>`                                 |
+| S'applique à   | :ref:`class <validation-class-target>`                                 |
 +----------------+------------------------------------------------------------------------+
-| Options        | - `methods`_                                                           |
+| Options        | - :ref:`callback <callback-option>`                                    |
 +----------------+------------------------------------------------------------------------+
 | Classe         | :class:`Symfony\\Component\\Validator\\Constraints\\Callback`          |
 +----------------+------------------------------------------------------------------------+
@@ -37,31 +42,39 @@ Configuration
         # src/Acme/BlogBundle/Resources/config/validation.yml
         Acme\BlogBundle\Entity\Author:
             constraints:
-                - Callback:
-                    methods:   [isAuthorValid]
+                - Callback: [validate]
 
     .. code-block:: php-annotations
 
         // src/Acme/BlogBundle/Entity/Author.php
+        namespace Acme\BlogBundle\Entity;
+
         use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\ExecutionContextInterface;
 
-        /**
-         * @Assert\Callback(methods={"isAuthorValid"})
-         */
         class Author
         {
+            /**
+             * @Assert\Callback
+             */
+            public function validate(ExecutionContextInterface $context)
+            {
+                // ...
+            }
         }
 
     .. code-block:: xml
 
         <!-- src/Acme/BlogBundle/Resources/config/validation.xml -->
-        <class name="Acme\BlogBundle\Entity\Author">
-            <constraint name="Callback">
-                <option name="methods">
-                    <value>isAuthorValid</value>
-                </option>
-            </constraint>
-        </class>
+        <?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 http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+
+            <class name="Acme\BlogBundle\Entity\Author">
+                <constraint name="Callback">validate</constraint>
+            </class>
+        </constraint-mapping>
 
     .. code-block:: php
 
@@ -75,9 +88,7 @@ Configuration
         {
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
-                $metadata->addConstraint(new Assert\Callback(array(
-                    'methods' => array('isAuthorValid'),
-                )));
+                $metadata->addConstraint(new Assert\Callback('validate'));
             }
         }
 
@@ -96,118 +107,178 @@ quel champ ces erreurs seront attribuées ::
         // ...
         private $firstName;
 
-        public function isAuthorValid(ExecutionContextInterface $context)
+        public function validate(ExecutionContextInterface $context)
         {
-            // Vous avez un tableau de « faux noms »
-            $fakeNames = array();
+            // Imaginons que vous avez un tableau de noms bidons
+            $fakeNames = array(/* ... */);
 
-            // vérifie si le nom est un faux
+            // Vérifie si le nom est bidon
             if (in_array($this->getFirstName(), $fakeNames)) {
-                $context->addViolationAt('firstname', 'This name sounds totally fake!', array(), null);
+                $context->addViolationAt(
+                    'firstName',
+                    'Ce nom me semble complètement bidon !',
+                    array(),
+                    null
+                );
             }
         }
     }
 
-Options
--------
+Callbacks statiques
+-------------------
 
-methods
-~~~~~~~
+Vous pouvez aussi utiliser cette contrainte avec des méthodes statiques.
+Étant donné que les méthodes statiques n'ont pas accès à l'instance de l'objet,
+elles reçoivent l'objet en premier argument::
 
-**type**: ``array`` **default**: ``array()`` [:ref:`option par défaut<validation-default-option>`]
+    public static function validate($object, ExecutionContextInterface $context)
+    {
+        // Imaginons que vous avez un tableau de noms bidons
+        $fakeNames = array(/* ... */);
+
+        // Vérifie si le nom est bidon
+        if (in_array($object->getFirstName(), $fakeNames)) {
+            $context->addViolationAt(
+                'firstName',
+                'Ce nom me semble complètement bidon !',
+                array(),
+                null
+            );
+        }
+    }
 
-Il s'agit d'un tableau de méthodes qui doivent être exécutées durant le
-processus de validation. Chacune de ces méthodes peut avoir l'un des formats
-suivants :
+Callbacks externes et closures
+------------------------------
 
-1) **Nom de la méthode sous forme de chaîne de caractères**
+Si vous voulez exécuter une callback statique qui ne se trouve pas dans la classe
+de l'objet validé, vous pouvez configurer la contrainte pour qu'elle utilise un 
+tableau de type callable tel que supporté par la fonction PHP :phpfunction:`call_user_func`.
+Supposez que votre fonction de validation est ``Vendor\Package\Validator::validate()``::
 
-    Si le nom de la méthode est une simple chaîne de caractères (par exemple : ``isAuthorValid``),
-    cette méthode sera appelée sur le même objet que celui qui est en train d'être validé
-    et ``ExecutionContext`` sera le seul argument (voyez l'exemple ci-dessus).
+    namespace Vendor\Package;
 
-2) **Tableau statique**
+    use Symfony\Component\Validator\ExecutionContextInterface;
 
-    Chaque méthode peut également être spécifiée sous forme de tableau standard :
+    class Validator
+    {
+        public static function validate($object, ExecutionContextInterface $context)
+        {
+            // ...
+        }
+    }
 
-    .. configuration-block::
+Vous pouvez alors utiliser la configuration suivante pour invoquer ce validateur :
 
-        .. code-block:: yaml
+.. configuration-block::
 
-            # src/Acme/BlogBundle/Resources/config/validation.yml
-            Acme\BlogBundle\Entity\Author:
-                constraints:
-                    - Callback:
-                        methods:
-                            -    [Acme\BlogBundle\MyStaticValidatorClass, isAuthorValid]
+    .. code-block:: yaml
 
-        .. code-block:: php-annotations
+        # src/Acme/BlogBundle/Resources/config/validation.yml
+        Acme\BlogBundle\Entity\Author:
+            constraints:
+                - Callback: [Vendor\Package\Validator, validate]
 
-            // src/Acme/BlogBundle/Entity/Author.php
-            use Symfony\Component\Validator\Constraints as Assert;
+    .. code-block:: php-annotations
 
-            /**
-             * @Assert\Callback(methods={
-             *     { "Acme\BlogBundle\MyStaticValidatorClass", "isAuthorValid"}
-             * })
-             */
-            class Author
-            {
-            }
+        // src/Acme/BlogBundle/Entity/Author.php
+        namespace Acme\BlogBundle\Entity;
 
-        .. code-block:: xml
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        /**
+         * @Assert\Callback({"Vendor\Package\Validator", "validate"})
+         */
+        class Author
+        {
+        }
+
+    .. code-block:: xml
+
+        <!-- src/Acme/BlogBundle/Resources/config/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 http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
-            <!-- src/Acme/BlogBundle/Resources/config/validation.xml -->
             <class name="Acme\BlogBundle\Entity\Author">
                 <constraint name="Callback">
-                    <option name="methods">
-                        <value>Acme\BlogBundle\MyStaticValidatorClass</value>
-                        <value>isAuthorValid</value>
-                    </option>
+                    <value>Vendor\Package\Validator</value>
+                    <value>validate</value>
                 </constraint>
             </class>
+        </constraint-mapping>
 
-        .. code-block:: php
+    .. code-block:: php
 
-            // src/Acme/BlogBundle/Entity/Author.php
+        // src/Acme/BlogBundle/Entity/Author.php
+        namespace Acme\BlogBundle\Entity;
 
-            use Symfony\Component\Validator\Mapping\ClassMetadata;
-            use Symfony\Component\Validator\Constraints\Callback;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+        use Symfony\Component\Validator\Constraints as Assert;
 
-            class Author
+        class Author
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
-                public $name;
-
-                public static function loadValidatorMetadata(ClassMetadata $metadata)
-                {
-                    $metadata->addConstraint(new Callback(array(
-                        'methods' => array('isAuthorValid'),
-                    )));
-                }
+                $metadata->addConstraint(new Assert\Callback(array(
+                    'Vendor\Package\Validator',
+                    'validate',
+                )));
             }
+        }
 
-    Dans ce cas, la méthode statique ``isAuthorValid`` sera appelée sur la classe
-    ``Acme\BlogBundle\MyStaticValidatorClass``. Deux objets sont passés en paramètre,
-    l'objet en cours de validation (par exemple : ``Author``) et le ``ExecutionContext``::
+.. note::
+
+    La contrainte Callback ne supporte *pas* les fonctions de callback globales
+    et il n'est pas possible de spécifier une fonction globale ou une méthode
+    de :term:`service` en tant que callback. Pour valider en utilisant un service
+    vous devez :doc:`créer une contrainte de validation personnalisée
+    </cookbook/validation/custom_constraint>` et ajouter cette contrainte à votre 
+    classe.
+
+Quand vous configurez la contrainte en PHP, vous pouvez aussi passer une closure
+au constructeur de la contrainte Callback::
 
-        namespace Acme\BlogBundle;
+    // src/Acme/BlogBundle/Entity/Author.php
+    namespace Acme\BlogBundle\Entity;
 
-        use Symfony\Component\Validator\ExecutionContext;
-        use Acme\BlogBundle\Entity\Author;
+    use Symfony\Component\Validator\Mapping\ClassMetadata;
+    use Symfony\Component\Validator\Constraints as Assert;
 
-        class MyStaticValidatorClass
+    class Author
+    {
+        public static function loadValidatorMetadata(ClassMetadata $metadata)
         {
-            static public function isAuthorValid(Author $author, ExecutionContext $context)
-            {
+            $callback = function ($object, ExecutionContextInterface $context) {
                 // ...
-            }
+            };
+
+            $metadata->addConstraint(new Assert\Callback($callback));
         }
+    }
+
+Options
+-------
+
+.. _callback-option:
+
+callback
+~~~~~~~~
+
+**type**: ``string``, ``array`` ou ``Closure`` [:ref:`default option <validation-default-option>`]
+
+L'option callback accepte trois formats différents pour spécifier la méthode
+de callback :
+
+* Une **chaîne de caractères** contenant le nom d'une méthode concrète ou statique;
+
+* Un tableau de type callable au format ``array('<Class>', '<method>')``;
+
+* Une closure.
 
-    .. tip::
+Les callbacks concrètes reçoivent une instance de :class:`Symfony\\Component\\Validator\\ExecutionContextInterface`
+pour seul argument.
 
-        Si vous spécifiez votre contrainte ``Callback`` via PHP, alors vous avez
-        également le choix de faire votre callback en closure PHP, ou en non-statique.
-        Il n'est, en revanche, *pas* possible de spécifier un :term:`service` comme
-        contrainte. Pour faire de la validation en utilisant un service, vous devriez
-        :doc:`créer une contrainte de validation personnalisée</cookbook/validation/custom_constraint>`
-        et ajouter cette nouvelle contrainte à votre classe.
+Les callbacks statiques ou de type closure reçoivent l'objet validé en premier
+argument, et l'instance de :class:`Symfony\\Component\\Validator\\ExecutionContextInterface`
+en second argument.
