Merge branch '5.4' into 6.0

* 5.4:
  [Validator] Add documentation for the CidrValidator

Author: javiereguiluz

reference/constraints/Cidr.rst

@@ -0,0 +1,155 @@
+Cidr
+====
+
+.. versionadded:: 5.4
+
+    The ``Cidr`` constraint was introduced in Symfony 5.4.
+
+Validates that a value is a valid `CIDR`_ (Classless Inter-Domain Routing) notation.
+By default, this will validate the CIDR's IP and netmask both for version 4 and 6,
+with the option of allowing only one type of IP version to be valid. It also supports
+a minimum and maximum range constraint in which the value of the netmask is valid.
+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\Cidr`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\CidrValidator`
+==========  ===================================================================
+
+Basic Usage
+-----------
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/Entity/Author.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Author
+        {
+            /**
+             * @Assert\Cidr
+             */
+            protected $cidrNotation;
+        }
+
+    .. code-block:: php-attributes
+
+        // src/Entity/Author.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Author
+        {
+            #[Assert\Cidr]
+            protected $cidrNotation;
+        }
+
+    .. code-block:: yaml
+
+        # config/validator/validation.yaml
+        App\Entity\Author:
+            properties:
+                cidrNotation:
+                    - Cidr: ~
+
+    .. 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\Author">
+                <property name="cidrNotation">
+                    <constraint name="Cidr"/>
+                </property>
+            </class>
+        </constraint-mapping>
+
+    .. code-block:: php
+
+        // src/Entity/Author.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+
+        class Author
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('cidrNotation', new Assert\Cidr());
+            }
+        }
+
+.. include:: /reference/constraints/_empty-values-are-valid.rst.inc
+
+Options
+-------
+
+.. include:: /reference/constraints/_groups-option.rst.inc
+
+``message``
+~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``This value is not a valid CIDR notation.``
+
+This message is shown if the string is not a valid CIDR notation.
+
+``netmaskMin``
+~~~~~~~~~~~
+
+**type**: ``integer`` **default**: ``0``
+
+It's a constraint for the lowest value a valid netmask may have.
+
+``netmaskMax``
+~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``32 for IPv4 or 128 for IPv6``
+
+It's a constraint for the biggest value a valid netmask may have.
+
+``netmaskRangeViolationMessage``
+~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``The value of the netmask should be between {{ min }} and {{ max }}.``
+
+This message is shown if the value of the CIDR's netmask is bigger then the value of the `max_` or lower than
+the value of the `min_`.
+
+You can use the following parameters in this message:
+
+===============  ==============================================================
+Parameter        Description
+===============  ==============================================================
+``{{ min }}``  The minimum value a CIDR netmask may have
+``{{ max }}``  The maximum value a CIDR netmask may have
+===============  ==============================================================
+
+.. include:: /reference/constraints/_payload-option.rst.inc
+
+``version``
+~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``all``
+
+This determines exactly *how* the CIDR notation is validated and can take one
+of a variety of different values:
+
+**All ranges**
+
+``4``
+    Validates for CIDR notations that have an IPv4.
+``6``
+    Validates for CIDR notations that have an IPv6.
+``all``
+    Validates all CIDR formats
+
+.. _`CIDR`: https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing

reference/constraints/map.rst.inc

@@ -22,6 +22,7 @@ String Constraints
 * :doc:`Regex </reference/constraints/Regex>`
 * :doc:`Hostname </reference/constraints/Hostname>`
 * :doc:`Ip </reference/constraints/Ip>`
+* :doc:`Cidr </reference/constraints/Cidr>`
 * :doc:`Json </reference/constraints/Json>`
 * :doc:`Uuid </reference/constraints/Uuid>`
 * :doc:`Ulid </reference/constraints/Ulid>`