Merge pull request #1403 from Inori/cookbook/custom-validator

[Cookbook] Custom validator entry improvements

Author: weaverryan

cookbook/validation/custom_constraint.rst

@@ -2,40 +2,43 @@
    single: Validation; Custom constraints
 
 How to create a Custom Validation Constraint
---------------------------------------------
+============================================
 
 You can create a custom constraint by extending the base constraint class,
-:class:`Symfony\\Component\\Validator\\Constraint`. Options for your
-constraint are represented as public properties on the constraint class. For
-example, the :doc:`Url</reference/constraints/Url>` constraint includes
-the ``message`` and ``protocols`` properties:
+:class:`Symfony\\Component\\Validator\\Constraint`. 
+As an example we're going to create a simple validator that checks if string 
+contains only alphanumeric characters.
 
-.. code-block:: php
+Creating Constraint class
+-------------------------
 
-    namespace Symfony\Component\Validator\Constraints;
+First you need to create a Constraint class and extend :class:`Symfony\\Component\\Validator\\Constraint`:: 
+
+    namespace Acme\DemoBundle\Validator\Constraints;
 
     use Symfony\Component\Validator\Constraint;
 
     /**
      * @Annotation
      */
-    class Protocol extends Constraint
+    class ContainsAlphanumeric extends Constraint
     {
-        public $message = 'This value is not a valid protocol';
-        public $protocols = array('http', 'https', 'ftp', 'ftps');
+        public $message = 'Missing at least one alphanumeric character in "%string%" string';
     }
 
 .. note::
 
     The ``@Annotation`` annotation is necessary for this new constraint in
     order to make it available for use in classes via annotations.
+    Options for your constraint are represented as public properties on the constraint class. 
 
+Creating Validator itself
+-------------------------    
+    
 As you can see, a constraint class is fairly minimal. The actual validation is
 performed by a another "constraint validator" class. The constraint validator
 class is specified by the constraint's ``validatedBy()`` method, which
-includes some simple default logic:
-
-.. code-block:: php
+includes some simple default logic::
 
     // in the base Symfony\Component\Validator\Constraint class
     public function validatedBy()
@@ -47,22 +50,19 @@ In other words, if you create a custom ``Constraint`` (e.g. ``MyConstraint``),
 Symfony2 will automatically look for another class, ``MyConstraintValidator``
 when actually performing the validation.
 
-The validator class is also simple, and only has one required method: ``isValid``.
-Furthering our example, take a look at the ``ProtocolValidator`` as an example:
-
-.. code-block:: php
+The validator class is also simple, and only has one required method: ``isValid``::
 
-    namespace Symfony\Component\Validator\Constraints;
+    namespace Acme\DemoBundle\Validator\Constraints;
     
     use Symfony\Component\Validator\Constraint;
     use Symfony\Component\Validator\ConstraintValidator;
 
-    class ProtocolValidator extends ConstraintValidator
+    class ContainsAlphanumericValidator extends ConstraintValidator
     {
         public function isValid($value, Constraint $constraint)
         {
-            if (!in_array($value, $constraint->protocols)) {
-                $this->setMessage($constraint->message, array('%protocols%' => $constraint->protocols));
+            if (!preg_match('/^[a-zA-Za0-9]+$/', $value, $matches)) {
+                $this->setMessage($constraint->message, array('%string%' => $value);
 
                 return false;
             }
@@ -75,6 +75,77 @@ Furthering our example, take a look at the ``ProtocolValidator`` as an example:
 
     Don't forget to call ``setMessage`` to construct an error message when the
     value is invalid.
+    
+Using newly created validator
+-----------------------------
+
+Using custom validators is very easy, just as the ones provided by Symfony2 itself:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+        
+        # src/Acme/BlogBundle/Resources/config/validation.yml
+        Acme\DemoBundle\Entity\AcmeEntity:
+            properties:
+                name:
+                    - NotBlank: ~
+                    - Acme\DemoBundle\Validator\Constraints\ContainsAlphanumeric: ~
+
+    .. code-block:: php-annotations
+
+        // src/Acme/DemoBundle/Entity/AcmeEntity.php
+    
+        use Symfony\Component\Validator\Constraints as Assert;
+        use Acme\DemoBundle\Validator\Constraints as AcmeAssert;
+            
+        class AcmeEntity
+        {
+            // ...
+            
+            /**
+             * @Assert\NotBlank
+             * @AcmeAssert\ContainsAlphanumeric
+             */
+            protected $name;
+            
+            // ...
+        }
+
+    .. code-block:: xml
+        
+        <!-- src/Acme/DemoBundle/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">
+
+            <class name="Acme\DemoBundle\Entity\AcmeEntity">
+                <property name="name">
+                    <constraint name="NotBlank" />
+                    <constraint name="Acme\DemoBundle\Validator\Constraints\ContainsAlphanumeric" />
+                </property>
+            </class>
+        </constraint-mapping>
+
+    .. code-block:: php
+        
+        // src/Acme/DemoBundle/Entity/AcmeEntity.php
+
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+        use Symfony\Component\Validator\Constraints\NotBlank;
+        use Acme\DemoBundle\Validator\Constraints\ContainsAlphanumeric;
+
+        class AcmeEntity
+        {
+            public $name;
+
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('name', new NotBlank());
+                $metadata->addPropertyConstraint('name', new ContainsAlphanumeric());
+            }
+        }
 
 Constraint Validators with Dependencies
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -142,8 +213,9 @@ With this, the validator ``isValid()`` method gets an object as its first argume
         {
             if ($protocol->getFoo() != $protocol->getBar()) {
 
-                // bind error message on foo property
-                $this->context->addViolationAtSubPath('foo', $constraint->getMessage(), array(), null);
+                $propertyPath = $this->context->getPropertyPath() . 'foo';
+                $this->context->setPropertyPath($propertyPath);
+                $this->context->addViolation($constraint->getMessage(), array(), null);
 
                 return false;
             }