From 4ffc9aba864d1b2b7532d8fd7d8dd409bdcec32c Mon Sep 17 00:00:00 2001
From: Tim Nagel <tim@nagel.com.au>
Date: Fri, 27 Jul 2012 09:37:05 +1000
Subject: [PATCH] Luhn Validator

---
 reference/constraints.rst         |  4 +-
 reference/constraints/Luhn.rst    | 85 +++++++++++++++++++++++++++++++
 reference/constraints/map.rst.inc |  7 ++-
 3 files changed, 94 insertions(+), 2 deletions(-)
 create mode 100644 reference/constraints/Luhn.rst

diff --git a/reference/constraints.rst b/reference/constraints.rst
index f57b7b1c25c..11ae0fe351b 100644
--- a/reference/constraints.rst
+++ b/reference/constraints.rst
@@ -39,6 +39,8 @@ Validation Constraints Reference
    constraints/File
    constraints/Image
 
+   constraints/Luhn
+
    constraints/Callback
    constraints/All
    constraints/UserPassword
@@ -46,7 +48,7 @@ Validation Constraints Reference
 
 The Validator is designed to validate objects against *constraints*.
 In real life, a constraint could be: "The cake must not be burned". In
-Symfony2, constraints are similar: They are assertions that a condition is 
+Symfony2, constraints are similar: They are assertions that a condition is
 true.
 
 Supported Constraints
diff --git a/reference/constraints/Luhn.rst b/reference/constraints/Luhn.rst
new file mode 100644
index 00000000000..306e6d4d99d
--- /dev/null
+++ b/reference/constraints/Luhn.rst
@@ -0,0 +1,85 @@
+Luhn
+======
+
+This constraint is used to ensure that a creditcard number passes the Luhn algorithm.
+It is useful as a first step to validating a creditcard, before communicating with a
+payment gateway.
+
++----------------+-----------------------------------------------------------------------+
+| Applies to     | :ref:`property or method<validation-property-target>`                 |
++----------------+-----------------------------------------------------------------------+
+| Options        | - `message`_                                                          |
++----------------+-----------------------------------------------------------------------+
+| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Luhn`             |
++----------------+-----------------------------------------------------------------------+
+| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\LuhnValidator`    |
++----------------+-----------------------------------------------------------------------+
+
+Basic Usage
+-----------
+
+To use the Luhn validator, simply apply it to a property on an object that will contain
+the creditcard number submission.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # src/Acme/SubscriptionBundle/Resources/config/validation.yml
+        Acme\SubscriptionBundle\Entity\Transaction:
+            properties:
+                cardNumber:
+                    - Luhn:
+                        message: Please check your creditcard number.
+
+    .. code-block:: xml
+
+        <!-- src/Acme/SubscriptionBundle/Resources/config/validation.xml -->
+        <class name="Acme\SubscriptionBundle\Entity\Transaction">
+            <property name="cardNumber">
+                <constraint name="Luhn">
+                    <option name="message">Please check your creditcard number.</option>
+                </constraint>
+            </property>
+        </class>
+
+    .. code-block:: php-annotations
+
+        // src/Acme/SubscriptionBundle/Entity/Transaction.php
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Transaction
+        {
+            /**
+             * @Assert\Luhn(message = "Please check your creditcard number.")
+             */
+            protected $cardNumber;
+        }
+
+    .. code-block:: php
+
+        // src/Acme/SubscriptionBundle/Entity/Transaction.php
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+        use Symfony\Component\Validator\Constraints\Luhn;
+
+        class Transaction
+        {
+            protected $cardNumber;
+
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('luhn', new Luhn(array(
+                    'message' => 'Please check your creditcard number',
+                )));
+            }
+        }
+
+Available Options
+-----------------
+
+message
+~~~~~~~
+
+**type**: ``string`` **default**: ``Invalid card number``
+
+The default message supplied when the value does not pass the Luhn check.
diff --git a/reference/constraints/map.rst.inc b/reference/constraints/map.rst.inc
index d58d3aef3e4..62529b81668 100644
--- a/reference/constraints/map.rst.inc
+++ b/reference/constraints/map.rst.inc
@@ -54,10 +54,15 @@ File Constraints
 * :doc:`File </reference/constraints/File>`
 * :doc:`Image </reference/constraints/Image>`
 
+Financial Constraints
+~~~~~~~~~~~~~~~~~~~~~
+
+* :doc:`Luhn </reference/constraints/Luhn>`
+
 Other Constraints
 ~~~~~~~~~~~~~~~~~
 
 * :doc:`Callback </reference/constraints/Callback>`
 * :doc:`All </reference/constraints/All>`
 * :doc:`UserPassword </reference/constraints/UserPassword>`
-* :doc:`Valid </reference/constraints/Valid>`
\ No newline at end of file
+* :doc:`Valid </reference/constraints/Valid>`