feature #5426 Documented the checkDNS option of the Url validator (saro0h, javiereguiluz)

This PR was submitted for the 2.6 branch but it was merged into the 2.3 branch instead (closes #5426).

Discussion
----------

Documented the checkDNS option of the Url validator

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes
| Applies to    | 2.6+
| Fixed tickets | -

Commits
-------

1135910 Reordered the configuration blocks of the first example
5d7b2a1 Fixed some errors and made some simplifications
f13625b Added the "payload" option back (was removed by mistake)
fa7ca6d Fixed the order of the examples
07628c9 Simplified the first example and added more examples
3395e02 [Validator] Updated documentation of URL validator

Author: weaverryan

reference/constraints/Url.rst

@@ -83,11 +83,140 @@ message
 
 This message is shown if the URL is invalid.
 
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/Acme/BlogBundle/Entity/Author.php
+        namespace Acme\BlogBundle\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Author
+        {
+            /**
+             * @Assert\Url(
+             *    message = "The url '{{ value }}' is not a valid url",
+             * )
+             */
+             protected $bioUrl;
+        }
+
+    .. code-block:: yaml
+
+        # src/Acme/BlogBundle/Resources/config/validation.yml
+        Acme\BlogBundle\Entity\Author:
+            properties:
+                bioUrl:
+                    - Url:
+                        message: The url "{{ value }}" is not a valid url.
+
+    .. 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">
+
+            <class name="Acme\BlogBundle\Entity\Author">
+                <property name="bioUrl">
+                    <constraint name="Url">
+                        <option name="message">The url "{{ value }}" is not a valid url.</option>
+                    </constraint>
+                </property>
+            </class>
+        </constraint-mapping>
+
+    .. code-block:: php
+
+        // src/Acme/BlogBundle/Entity/Author.php
+        namespace Acme\BlogBundle\Entity;
+
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Author
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('bioUrl', new Assert\Url(array(
+                    'message' => 'The url "{{ value }}" is not a valid url.',
+                )));
+            }
+        }
+
 protocols
 ~~~~~~~~~
 
 **type**: ``array`` **default**: ``array('http', 'https')``
 
-The protocols that will be considered to be valid. For example, if you also
-needed ``ftp://`` type URLs to be valid, you'd redefine the ``protocols``
-array, listing ``http``, ``https`` and also ``ftp``.
+The protocols considered to be valid for the URL. For example, if you also consider
+the ``ftp://`` type URLs to be valid, redefine the ``protocols`` array, listing
+``http``, ``https``, and also ``ftp``.
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/Acme/BlogBundle/Entity/Author.php
+        namespace Acme\BlogBundle\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Author
+        {
+            /**
+             * @Assert\Url(
+             *    protocols = {"http", "https", "ftp"}
+             * )
+             */
+             protected $bioUrl;
+        }
+
+    .. code-block:: yaml
+
+        # src/Acme/BlogBundle/Resources/config/validation.yml
+        Acme\BlogBundle\Entity\Author:
+            properties:
+                bioUrl:
+                    - Url: { protocols: [http, https, ftp] }
+
+    .. 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">
+
+            <class name="Acme\BlogBundle\Entity\Author">
+                <property name="bioUrl">
+                    <constraint name="Url">
+                        <option name="protocols">
+                            <value>http</value>
+                            <value>https</value>
+                            <value>ftp</value>
+                        </option>
+                    </constraint>
+                </property>
+            </class>
+        </constraint-mapping>
+
+    .. code-block:: php
+
+        // src/Acme/BlogBundle/Entity/Author.php
+        namespace Acme\BlogBundle\Entity;
+
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Author
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('bioUrl', new Assert\Url(array(
+                    'protocols' => array('http', 'https', 'ftp'),
+                )));
+            }
+        }