symfony · weaverryan · Jun 30, 2013 · Jun 6, 2013 · Jun 6, 2013
diff --git a/reference/constraints.rst b/reference/constraints.rst
@@ -46,6 +46,7 @@ Validation Constraints Reference
    constraints/Image
 
    constraints/CardScheme
+   constraints/Currency
    constraints/Luhn
    constraints/Iban
    constraints/Isbn

diff --git a/reference/constraints/Currency.rst b/reference/constraints/Currency.rst
@@ -0,0 +1,85 @@
+Currency
+========
+
+.. versionadded:: 2.3
+    This constraint is new in version 2.3.
+
+Validates that a value is a valid `3-letter ISO 4217`_ currency name.
+
++----------------+---------------------------------------------------------------------------+
+| Applies to     | :ref:`property or method<validation-property-target>`                     |
++----------------+---------------------------------------------------------------------------+
+| Options        | - `message`_                                                              |
++----------------+---------------------------------------------------------------------------+
+| Class          | :class:`Symfony\\Component\\Validator\\Constraints\\Currency`             |
++----------------+---------------------------------------------------------------------------+
+| Validator      | :class:`Symfony\\Component\\Validator\\Constraints\\CurrencyValidator`    |
++----------------+---------------------------------------------------------------------------+
+
+Basic Usage
+-----------
+
+If you want to ensure that the ``currency`` property of an ``Order`` is a valid
+currency, you could do the following:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # src/EcommerceBundle/Resources/config/validation.yml
+        Acme\EcommerceBundle\Entity\Order:
+            properties:
+                currency:
+                    - Currency: ~
+
+    .. code-block:: php-annotations
+
+        // src/Acme/EcommerceBundle/Entity/Order.php
+        namespace Acme\EcommerceBundle\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Order
+        {
+            /**
+             * @Assert\Currency
+             */
+            protected $currency;
+        }
+
+    .. code-block:: xml
+
+        <!-- src/Acme/EcommerceBundle/Resources/config/validation.xml -->
+        <class name="Acme\EcommerceBundle\Entity\Order">
+            <property name="currency">
+                <constraint name="Currency" />
+            </property>
+        </class>
+
+    .. code-block:: php
+
+        // src/Acme/EcommerceBundle/Entity/Order.php
+        namespace Acme\SocialBundle\Entity;
+
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Order
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('currency', new Assert\Currency());
+            }
+        }
+
+Options
+-------
+
+message
+~~~~~~~
+
+**type**: ``string`` **default**: ``This value is not a valid currency.``
+
+This is the message that will be shown if the value is not a valid currency.
+
+.. _`3-letter ISO 4217`: http://en.wikipedia.org/wiki/ISO_4217 
diff --git a/reference/constraints/map.rst.inc b/reference/constraints/map.rst.inc
@@ -66,6 +66,7 @@ Financial and other Number Constraints
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * :doc:`CardScheme </reference/constraints/CardScheme>`
+* :doc:`Currency </reference/constraints/Currency>`
 * :doc:`Luhn </reference/constraints/Luhn>`
 * :doc:`Iban </reference/constraints/Iban>`
 * :doc:`Isbn </reference/constraints/Isbn>`

diff --git a/reference/forms/types.rst b/reference/forms/types.rst
@@ -14,6 +14,7 @@ Form Types Reference
    types/choice
    types/collection
    types/country
+   types/currency
    types/date
    types/datetime
    types/email

diff --git a/reference/forms/types/currency.rst b/reference/forms/types/currency.rst
@@ -0,0 +1,75 @@
+.. index::
+    single: Forms; Fields; currency
+
+currency Field Type
+===================
+
+The ``currency`` type is a subset of the
+:doc:`choice type </reference/forms/types/choice` that allows the user to
+select from a large list of `3-letter ISO 4217`_ currencies.
+
+Unlike the ``choice`` type, you don't need to specify a ``choices`` or
+``choice_list`` option as the field type automatically uses a large list of
+currencies. You *can* specify either of these options manually, but then you
+should just use the ``choice`` type directly.
+
++-------------+------------------------------------------------------------------------+
+| Rendered as | can be various tags (see :ref:`forms-reference-choice-tags`)           |
++-------------+------------------------------------------------------------------------+
+| Overridden  | - `choices`_                                                           |
+| Options     |                                                                        |
++-------------+------------------------------------------------------------------------+
+| Inherited   | - `multiple`_                                                          |
+| options     | - `expanded`_                                                          |
+|             | - `preferred_choices`_                                                 |
+|             | - `empty_value`_                                                       |
+|             | - `error_bubbling`_                                                    |
+|             | - `required`_                                                          |
+|             | - `label`_                                                             |
+|             | - `read_only`_                                                         |
+|             | - `disabled`_                                                          |
+|             | - `mapped`_                                                            |
++-------------+------------------------------------------------------------------------+
+| Parent type | :doc:`choice </reference/forms/types/choice>`                          |
++-------------+------------------------------------------------------------------------+
+| Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\CurrencyType` |
++-------------+------------------------------------------------------------------------+
+
+Overridden Options
+------------------
+
+choices
+~~~~~~~
+
+**default**: ``Symfony\Component\Intl\Intl::getCurrencyBundle()->getCurrencyNames()``
+
+The choices option defaults to all currencies.
+
+Inherited options
+-----------------
+
+These options inherit from the :doc:`choice</reference/forms/types/choice>` type:
+
+.. include:: /reference/forms/types/options/multiple.rst.inc
+
+.. include:: /reference/forms/types/options/expanded.rst.inc
+
+.. include:: /reference/forms/types/options/preferred_choices.rst.inc
+
+.. include:: /reference/forms/types/options/empty_value.rst.inc
+
+.. include:: /reference/forms/types/options/error_bubbling.rst.inc
+
+These options inherit from the :doc:`date</reference/forms/types/form>` type:
+
+.. include:: /reference/forms/types/options/required.rst.inc
+
+.. include:: /reference/forms/types/options/label.rst.inc
+
+.. include:: /reference/forms/types/options/read_only.rst.inc
+
+.. include:: /reference/forms/types/options/disabled.rst.inc
+
+.. include:: /reference/forms/types/options/mapped.rst.inc
+
+.. _`3-letter ISO 4217`: http://en.wikipedia.org/wiki/ISO_4217
diff --git a/reference/forms/types/map.rst.inc b/reference/forms/types/map.rst.inc
@@ -21,6 +21,7 @@ Choice Fields
 * :doc:`language</reference/forms/types/language>`
 * :doc:`locale</reference/forms/types/locale>`
 * :doc:`timezone</reference/forms/types/timezone>`
+* :doc:`currency</reference/forms/types/currency>`
 
 Date and Time Fields
 ~~~~~~~~~~~~~~~~~~~~