feature #3724 Updated ISBN validator docs (sprain)

This PR was submitted for the master branch but it was merged into the 2.5 branch instead (closes #3724). Discussion ---------- Updated ISBN validator docs | Q | A | ------------- | --- | Doc fix? | yes | New docs? | no - symfony/symfony/pull/10546 | Applies to | 2.5 Updated the docs according to the changes in the code. Commits ------- 6d64a56 Updated ISBN validator
symfony · Jul 3, 2014 · 1938c2f · 1938c2f
2 parents 1efcdba + fcae3cd
commit 1938c2f
Showing 1 changed file with 33 additions and 30 deletions.
diff --git a/reference/constraints/Isbn.rst b/reference/constraints/Isbn.rst
@@ -4,14 +4,21 @@ Isbn
 .. versionadded:: 2.3
     The Isbn constraint was introduced in Symfony 2.3.
 
+.. caution::
+
+    The ``isbn10`` and ``isbn13`` options are deprecated since Symfony 2.5
+    and will be removed in Symfony 3.0. Use the ``type`` option instead.
+    Furthermore, when using the ``type`` option, lowercase characters are no
+    longer supported starting in Symfony 2.5, as they are not allowed in ISBNs.
+
 This constraint validates that an `International Standard Book Number (ISBN)`_
-is either a valid ISBN-10, a valid ISBN-13 or both.
+is either a valid ISBN-10 or a valid ISBN-13.
 
 +----------------+----------------------------------------------------------------------+
 | Applies to     | :ref:`property or method<validation-property-target>`                |
 +----------------+----------------------------------------------------------------------+
-| Options        | - `isbn10`_                                                          |
-|                | - `isbn13`_                                                          |
+| Options        | - `type`_                                                            |
+|                | - `message`_                                                         |
 |                | - `isbn10Message`_                                                   |
 |                | - `isbn13Message`_                                                   |
 |                | - `bothIsbnMessage`_                                                 |
@@ -25,7 +32,7 @@ Basic Usage
 -----------
 
 To use the ``Isbn`` validator, simply apply it to a property or method
-on an  object that will contain a ISBN number.
+on an  object that will contain an ISBN.
 
 .. configuration-block::
 
@@ -36,9 +43,8 @@ on an  object that will contain a ISBN number.
             properties:
                 isbn:
                     - Isbn:
-                        isbn10: true
-                        isbn13: true
-                        bothIsbnMessage: This value is neither a valid ISBN-10 nor a valid ISBN-13.
+                        type: isbn10
+                        message: This value is not  valid.
 
     .. code-block:: php-annotations
 
@@ -49,9 +55,8 @@ on an  object that will contain a ISBN number.
         {
             /**
              * @Assert\Isbn(
-             *     isbn10 = true,
-             *     isbn13 = true,
-             *     bothIsbnMessage = "This value is neither a valid ISBN-10 nor a valid ISBN-13."
+             *     type = isbn10,
+             *     message: This value is not  valid.
              * )
              */
             protected $isbn;
@@ -63,9 +68,8 @@ on an  object that will contain a ISBN number.
         <class name="Acme\BookcaseBundle\Entity\Book">
             <property name="isbn">
                 <constraint name="Isbn">
-                    <option name="isbn10">true</option>
-                    <option name="isbn13">true</option>
-                    <option name="bothIsbnMessage">This value is neither a valid ISBN-10 nor a valid ISBN-13.</option>
+                    <option name="type">isbn10</option>
+                    <option name="message">This value is not  valid.</option>
                 </constraint>
             </property>
         </class>
@@ -85,54 +89,53 @@ on an  object that will contain a ISBN number.
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
                 $metadata->addPropertyConstraint('isbn', new Assert\Isbn(array(
-                    'isbn10'          => true,
-                    'isbn13'          => true,
-                    'bothIsbnMessage' => 'This value is neither a valid ISBN-10 nor a valid ISBN-13.'
+                    'type'    => isbn10,
+                    'message' => 'This value is not valid.'
                 )));
             }
         }
 
 Available Options
 -----------------
 
-isbn10
-~~~~~~
+type
+~~~~
 
-**type**: ``boolean``
+**type**: ``string`` **default**: ``null``
 
-If this required option is set to ``true`` the constraint will check if the
-code is a valid ISBN-10 code.
+The type of ISBN to validate against.
+Valid values are ``isbn10``, ``isbn13`` and ``null`` to accept any kind of ISBN.
 
-isbn13
-~~~~~~
+message
+~~~~~~~
 
-**type**: ``boolean``
+**type**: ``string`` **default**: ``null``
 
-If this required option is set to ``true`` the constraint will check if the
-code is a valid ISBN-13 code.
+The message that will be shown if the value is not valid.
+If not ``null``, this message has priority over all the other messages.
 
 isbn10Message
 ~~~~~~~~~~~~~
 
 **type**: ``string`` **default**: ``This value is not a valid ISBN-10.``
 
-The message that will be shown if the `isbn10`_ option is true and the given
+The message that will be shown if the `type`_ option is ``isbn10`` and the given
 value does not pass the ISBN-10 check.
 
 isbn13Message
 ~~~~~~~~~~~~~
 
 **type**: ``string`` **default**: ``This value is not a valid ISBN-13.``
 
-The message that will be shown if the `isbn13`_ option is true and the given
+The message that will be shown if the `type`_ option is ``isbn13`` and the given
 value does not pass the ISBN-13 check.
 
 bothIsbnMessage
 ~~~~~~~~~~~~~~~
 
 **type**: ``string`` **default**: ``This value is neither a valid ISBN-10 nor a valid ISBN-13.``
 
-The message that will be shown if both the `isbn10`_ and `isbn13`_ options
-are true and the given value does not pass the ISBN-13 nor the ISBN-13 check.
+The message that will be shown if the `type`_ option is ``null`` and the given
+value does not pass any of the ISBN checks.
 
 .. _`International Standard Book Number (ISBN)`: http://en.wikipedia.org/wiki/Isbn