[reference][constraints] Tweaks for new Size and SizeLength constraints - see symfony#1252

weaverryan · weaverryan · commit 36edead1f0ae · 2012-04-21T15:29:34.000-05:00
diff --git a/reference/constraints.rst b/reference/constraints.rst
@@ -16,12 +16,14 @@ Validation Constraints Reference
    constraints/Email
    constraints/MinLength
    constraints/MaxLength
+   constraints/SizeLength
    constraints/Url
    constraints/Regex
    constraints/Ip
 
    constraints/Max
    constraints/Min
+   constraints/Size
 
    constraints/Date
    constraints/DateTime
@@ -41,8 +43,6 @@ Validation Constraints Reference
    constraints/All
    constraints/UserPassword
    constraints/Valid
-   constraints/Size
-   constraints/SizeLength
 
 The Validator is designed to validate objects against *constraints*.
 In real life, a constraint could be: "The cake must not be burned". In
diff --git a/reference/constraints/Size.rst b/reference/constraints/Size.rst
@@ -28,10 +28,14 @@ the following:
     .. code-block:: yaml
 
         # src/Acme/EventBundle/Resources/config/validation.yml
-        Acme\EventBundle\Entity\Height:
+        Acme\EventBundle\Entity\Participant:
             properties:
                 height:
-                    - Size: { min: 120, max: 180, minMessage: You must be at least 120cm tall to enter, maxMessage: You cannot be taller than 180cm to enter }
+                    - Size:
+                        min: 120
+                        max: 180
+                        minMessage: You must be at least 120cm tall to enter
+                        maxMessage: You cannot be taller than 180cm to enter
 
     .. code-block:: php-annotations
 
@@ -41,7 +45,12 @@ the following:
         class Participant
         {
             /**
-             * @Assert\Size(min = "120", max = "180", minMessage = "You must be at least 120cm tall to enter", maxMessage="You cannot be taller than 180cm to enter")
+             * @Assert\Size(
+             *      min = "120",
+             *      max = "180",
+             *      minMessage = "You must be at least 120cm tall to enter",
+             *      maxMessage="You cannot be taller than 180cm to enter"
+             * )
              */
              protected $height;
         }
@@ -63,28 +72,28 @@ max
 **type**: ``integer`` [:ref:`default option<validation-default-option>`]
 
 This required option is the "max" value. Validation will fail if the given
-value is **more** than this max value.
+value is **greater** than this max value.
 
 minMessage
 ~~~~~~~~~~
 
-**type**: ``string`` **default**: ``This value should be {{ limit }} or more``
+**type**: ``string`` **default**: ``This value should be {{ limit }} or more.``
 
-The message that will be shown if the underlying value is less than the `limit`_
+The message that will be shown if the underlying value is less than the `min`_
 option.
 
 maxMessage
 ~~~~~~~~~~
 
-**type**: ``string`` **default**: ``This value should be {{ limit }} or less``
+**type**: ``string`` **default**: ``This value should be {{ limit }} or less.``
 
-The message that will be shown if the underlying value is more than the `limit`_
+The message that will be shown if the underlying value is more than the `max`_
 option.
 
 invalidMessage
 ~~~~~~~~~~~~~~
 
-**type**: ``string`` **default**: ``This value should be a valid number``
+**type**: ``string`` **default**: ``This value should be a valid number.``
 
 The message that will be shown if the underlying value is not a number (per
 the `is_numeric`_ PHP function).
diff --git a/reference/constraints/SizeLength.rst b/reference/constraints/SizeLength.rst
@@ -21,8 +21,8 @@ Validates that a given string length is *between* some minimum and maximum value
 Basic Usage
 -----------
 
-To verify that the "firstname" field length of a class is between "2" and "50", you might add
-the following:
+To verify that the ``firstName`` field length of a class is between "2" and
+"50", you might add the following:
 
 .. configuration-block::
 
@@ -31,8 +31,12 @@ the following:
         # src/Acme/EventBundle/Resources/config/validation.yml
         Acme\EventBundle\Entity\Height:
             properties:
-                firstname:
-                    - SizeLength: { min: 2, max: 50, minMessage: Firstname must be at least 2 characters length, maxMessage: Firstname cannot be longer than than 50 characters length }
+                firstName:
+                    - SizeLength:
+                        min: 2
+                        max: 50
+                        minMessage: Your first name must be at least 2 characters length
+                        maxMessage: Your first name cannot be longer than than 50 characters length
 
     .. code-block:: php-annotations
 
@@ -42,9 +46,14 @@ the following:
         class Participant
         {
             /**
-             * @Assert\SizeLength(min = "2", max = "50", minMessage = "Firstname must be at least 2 characters length", maxMessage="Firstname cannot be longer than than 50 characters length")
+             * @Assert\SizeLength(
+             *      min = "2",
+             *      max = "50",
+             *      minMessage = "Your first name must be at least 2 characters length",
+             *      maxMessage="Your first name cannot be longer than than 50 characters length"
+             * )
              */
-             protected $firstname;
+             protected $firstName;
         }
 
 Options
@@ -64,14 +73,17 @@ max
 **type**: ``integer`` [:ref:`default option<validation-default-option>`]
 
 This required option is the "max" length value. Validation will fail if the given
-value's length is **less** than this max value.
+value's length is **greater** than this max value.
 
 charset
 ~~~~~~~
 
 **type**: ``string``  **default**: ``UTF-8``
 
-Charset to be used when computing value's length per the `grapheme_strlen`_ PHP function, fallback to the `mb_strlen`_ PHP function, fallback to the `strlen`_ PHP function.
+The charset to be used when computing value's length. The `grapheme_strlen`_ PHP
+function is used if available. If not, the the `mb_strlen`_ PHP function
+is used if available. If neither are available, the `strlen`_ PHP function
+is used.
 
 .. _`grapheme_strlen`: http://www.php.net/manual/en/function.grapheme_strlen.php
 .. _`mb_strlen`: http://www.php.net/manual/en/function.mb_strlen.php
@@ -80,22 +92,23 @@ Charset to be used when computing value's length per the `grapheme_strlen`_ PHP
 minMessage
 ~~~~~~~~~~
 
-**type**: ``string`` **default**: ``This value is too short. It should have {{ limit }} characters or more``
+**type**: ``string`` **default**: ``This value is too short. It should have {{ limit }} characters or more.``
 
-The message that will be shown if the underlying value's length is less than the `limit`_
+The message that will be shown if the underlying value's length is less than the `min`_
 option.
 
 maxMessage
 ~~~~~~~~~~
 
-**type**: ``string`` **default**: ``This value is too long. It should have {{ limit }} characters or less``
+**type**: ``string`` **default**: ``This value is too long. It should have {{ limit }} characters or less.``
 
-The message that will be shown if the underlying value's length is more than the `limit`_
+The message that will be shown if the underlying value's length is more than the `max`_
 option.
 
 exactMessage
-~~~~~~~~~~~~~~
+~~~~~~~~~~~~
 
-**type**: ``string`` **default**: ``This value should have exactly {{ limit }} characters``
+**type**: ``string`` **default**: ``This value should have exactly {{ limit }} characters.``
 
-The message that will be shown if min and max values equal and the underlying value's length is not exactly this value
+The message that will be shown if min and max values are equal and the underlying
+value's length is not exactly this value.
diff --git a/reference/constraints/map.rst.inc b/reference/constraints/map.rst.inc
@@ -18,6 +18,7 @@ String Constraints
 * :doc:`Email </reference/constraints/Email>`
 * :doc:`MinLength </reference/constraints/MinLength>`
 * :doc:`MaxLength </reference/constraints/MaxLength>`
+* :doc:`SizeLength </reference/constraints/SizeLength>`
 * :doc:`Url </reference/constraints/Url>`
 * :doc:`Regex </reference/constraints/Regex>`
 * :doc:`Ip </reference/constraints/Ip>`
@@ -27,6 +28,7 @@ Number Constraints
 
 * :doc:`Max </reference/constraints/Max>`
 * :doc:`Min </reference/constraints/Min>`
+* :doc:`Size </reference/constraints/Size>`
 
 Date Constraints
 ~~~~~~~~~~~~~~~~
