From 969ad5ac20d5b074632d17baa5f206a9b55c30f3 Mon Sep 17 00:00:00 2001
From: Bernhard Schussek <bschussek@gmail.com>
Date: Mon, 18 Aug 2014 13:40:46 +0200
Subject: [PATCH] Added information about the new date handling in the
 comparison constraints and Range

---
 reference/constraints/EqualTo.rst            |   2 +-
 reference/constraints/GreaterThan.rst        | 166 ++++++++++++++++
 reference/constraints/GreaterThanOrEqual.rst | 166 ++++++++++++++++
 reference/constraints/LessThan.rst           | 165 ++++++++++++++++
 reference/constraints/LessThanOrEqual.rst    | 165 ++++++++++++++++
 reference/constraints/Range.rst              | 198 +++++++++++++++++++
 6 files changed, 861 insertions(+), 1 deletion(-)

diff --git a/reference/constraints/EqualTo.rst b/reference/constraints/EqualTo.rst
index 1079bd90430..81001911ad4 100644
--- a/reference/constraints/EqualTo.rst
+++ b/reference/constraints/EqualTo.rst
@@ -8,7 +8,7 @@ Validates that a value is equal to another value, defined in the options. To
 force that a value is *not* equal, see :doc:`/reference/constraints/NotEqualTo`.
 
 .. caution::
-    
+
     This constraint compares using ``==``, so ``3`` and ``"3"`` are considered
     equal. Use :doc:`/reference/constraints/IdenticalTo` to compare with
     ``===``.
diff --git a/reference/constraints/GreaterThan.rst b/reference/constraints/GreaterThan.rst
index 80439900b26..a8638acf025 100644
--- a/reference/constraints/GreaterThan.rst
+++ b/reference/constraints/GreaterThan.rst
@@ -83,6 +83,170 @@ If you want to ensure that the ``age`` of a ``Person`` class is greater than
             }
         }
 
+Comparing Dates
+---------------
+
+This constraint can be used to compare ``DateTime`` objects against any date
+string `accepted by the DateTime constructor`_. For example, you could check
+that a date must at least be the next day:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # src/OrderBundle/Resources/config/validation.yml
+        Acme\OrderBundle\Entity\Order:
+            properties:
+                deliveryDate:
+                    - GreaterThan: today
+
+    .. code-block:: php-annotations
+
+        // src/Acme/SocialBundle/Entity/Order.php
+        namespace Acme\OrderBundle\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Order
+        {
+            /**
+             * @Assert\GreaterThan("today")
+             */
+            protected $deliveryDate;
+        }
+
+    .. code-block:: xml
+
+        <!-- src/Acme/OrderBundle/Resources/config/validation.xml -->
+        <class name="Acme\OrderBundle\Entity\Order">
+            <property name="deliveryDate">
+                <constraint name="GreaterThan">today</constraint>
+            </property>
+        </class>
+
+    .. code-block:: php
+
+        // src/Acme/OrderBundle/Entity/Order.php
+        namespace Acme\OrderBundle\Entity;
+
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Order
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('deliveryDate', new Assert\GreaterThan('today'));
+            }
+        }
+
+Be aware that PHP will use the server's configured timezone to interpret these
+dates. If you want to fix the timezone, append it to the date string:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # src/OrderBundle/Resources/config/validation.yml
+        Acme\OrderBundle\Entity\Order:
+            properties:
+                deliveryDate:
+                    - GreaterThan: today UTC
+
+    .. code-block:: php-annotations
+
+        // src/Acme/SocialBundle/Entity/Order.php
+        namespace Acme\OrderBundle\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Order
+        {
+            /**
+             * @Assert\GreaterThan("today UTC")
+             */
+            protected $deliveryDate;
+        }
+
+    .. code-block:: xml
+
+        <!-- src/Acme/OrderBundle/Resources/config/validation.xml -->
+        <class name="Acme\OrderBundle\Entity\Order">
+            <property name="deliveryDate">
+                <constraint name="GreaterThan">today UTC</constraint>
+            </property>
+        </class>
+
+    .. code-block:: php
+
+        // src/Acme/OrderBundle/Entity/Order.php
+        namespace Acme\OrderBundle\Entity;
+
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Order
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('deliveryDate', new Assert\GreaterThan('today UTC'));
+            }
+        }
+
+The ``DateTime`` class also accepts relative dates or times. For example, you
+can check that the above delivery date starts at least five hours after the
+current time:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # src/OrderBundle/Resources/config/validation.yml
+        Acme\OrderBundle\Entity\Order:
+            properties:
+                deliveryDate:
+                    - GreaterThan: +5 hours
+
+    .. code-block:: php-annotations
+
+        // src/Acme/SocialBundle/Entity/Order.php
+        namespace Acme\OrderBundle\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Order
+        {
+            /**
+             * @Assert\GreaterThan("+5 hours")
+             */
+            protected $deliveryDate;
+        }
+
+    .. code-block:: xml
+
+        <!-- src/Acme/OrderBundle/Resources/config/validation.xml -->
+        <class name="Acme\OrderBundle\Entity\Order">
+            <property name="deliveryDate">
+                <constraint name="GreaterThan">+5 hours</constraint>
+            </property>
+        </class>
+
+    .. code-block:: php
+
+        // src/Acme/OrderBundle/Entity/Order.php
+        namespace Acme\OrderBundle\Entity;
+
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Order
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('deliveryDate', new Assert\GreaterThan('+5 hours'));
+            }
+        }
+
 Options
 -------
 
@@ -95,3 +259,5 @@ message
 
 This is the message that will be shown if the value is not greater than the
 comparison value.
+
+.. _`accepted by the DateTime constructor`: http://www.php.net/manual/en/datetime.formats.php
diff --git a/reference/constraints/GreaterThanOrEqual.rst b/reference/constraints/GreaterThanOrEqual.rst
index 0dfe7072dc6..bdc6f9e36cf 100644
--- a/reference/constraints/GreaterThanOrEqual.rst
+++ b/reference/constraints/GreaterThanOrEqual.rst
@@ -82,6 +82,170 @@ or equal to ``18``, you could do the following:
             }
         }
 
+Comparing Dates
+---------------
+
+This constraint can be used to compare ``DateTime`` objects against any date
+string `accepted by the DateTime constructor`_. For example, you could check
+that a date must at least be the current day:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # src/OrderBundle/Resources/config/validation.yml
+        Acme\OrderBundle\Entity\Order:
+            properties:
+                deliveryDate:
+                    - GreaterThanOrEqual: today
+
+    .. code-block:: php-annotations
+
+        // src/Acme/SocialBundle/Entity/Order.php
+        namespace Acme\OrderBundle\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Order
+        {
+            /**
+             * @Assert\GreaterThanOrEqual("today")
+             */
+            protected $deliveryDate;
+        }
+
+    .. code-block:: xml
+
+        <!-- src/Acme/OrderBundle/Resources/config/validation.xml -->
+        <class name="Acme\OrderBundle\Entity\Order">
+            <property name="deliveryDate">
+                <constraint name="GreaterThanOrEqual">today</constraint>
+            </property>
+        </class>
+
+    .. code-block:: php
+
+        // src/Acme/OrderBundle/Entity/Order.php
+        namespace Acme\OrderBundle\Entity;
+
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Order
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('deliveryDate', new Assert\GreaterThanOrEqual('today'));
+            }
+        }
+
+Be aware that PHP will use the server's configured timezone to interpret these
+dates. If you want to fix the timezone, append it to the date string:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # src/OrderBundle/Resources/config/validation.yml
+        Acme\OrderBundle\Entity\Order:
+            properties:
+                deliveryDate:
+                    - GreaterThanOrEqual: today UTC
+
+    .. code-block:: php-annotations
+
+        // src/Acme/SocialBundle/Entity/Order.php
+        namespace Acme\OrderBundle\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Order
+        {
+            /**
+             * @Assert\GreaterThanOrEqual("today UTC")
+             */
+            protected $deliveryDate;
+        }
+
+    .. code-block:: xml
+
+        <!-- src/Acme/OrderBundle/Resources/config/validation.xml -->
+        <class name="Acme\OrderBundle\Entity\Order">
+            <property name="deliveryDate">
+                <constraint name="GreaterThanOrEqual">today UTC</constraint>
+            </property>
+        </class>
+
+    .. code-block:: php
+
+        // src/Acme/OrderBundle/Entity/Order.php
+        namespace Acme\OrderBundle\Entity;
+
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Order
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('deliveryDate', new Assert\GreaterThanOrEqual('today UTC'));
+            }
+        }
+
+The ``DateTime`` class also accepts relative dates or times. For example, you
+can check that the above delivery date starts at least five hours after the
+current time:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # src/OrderBundle/Resources/config/validation.yml
+        Acme\OrderBundle\Entity\Order:
+            properties:
+                deliveryDate:
+                    - GreaterThanOrEqual: +5 hours
+
+    .. code-block:: php-annotations
+
+        // src/Acme/SocialBundle/Entity/Order.php
+        namespace Acme\OrderBundle\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Order
+        {
+            /**
+             * @Assert\GreaterThanOrEqual("+5 hours")
+             */
+            protected $deliveryDate;
+        }
+
+    .. code-block:: xml
+
+        <!-- src/Acme/OrderBundle/Resources/config/validation.xml -->
+        <class name="Acme\OrderBundle\Entity\Order">
+            <property name="deliveryDate">
+                <constraint name="GreaterThanOrEqual">+5 hours</constraint>
+            </property>
+        </class>
+
+    .. code-block:: php
+
+        // src/Acme/OrderBundle/Entity/Order.php
+        namespace Acme\OrderBundle\Entity;
+
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Order
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('deliveryDate', new Assert\GreaterThanOrEqual('+5 hours'));
+            }
+        }
+
 Options
 -------
 
@@ -94,3 +258,5 @@ message
 
 This is the message that will be shown if the value is not greater than or equal
 to the comparison value.
+
+.. _`accepted by the DateTime constructor`: http://www.php.net/manual/en/datetime.formats.php
diff --git a/reference/constraints/LessThan.rst b/reference/constraints/LessThan.rst
index 849b157bc0a..09c5f93ef40 100644
--- a/reference/constraints/LessThan.rst
+++ b/reference/constraints/LessThan.rst
@@ -83,6 +83,169 @@ If you want to ensure that the ``age`` of a ``Person`` class is less than
             }
         }
 
+Comparing Dates
+---------------
+
+This constraint can be used to compare ``DateTime`` objects against any date
+string `accepted by the DateTime constructor`_. For example, you could check
+that a date must be in the past like this:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # src/SocialBundle/Resources/config/validation.yml
+        Acme\SocialBundle\Entity\Person:
+            properties:
+                age:
+                    - LessThan: today
+
+    .. code-block:: php-annotations
+
+        // src/Acme/SocialBundle/Entity/Person.php
+        namespace Acme\SocialBundle\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Person
+        {
+            /**
+             * @Assert\LessThan("today")
+             */
+            protected $age;
+        }
+
+    .. code-block:: xml
+
+        <!-- src/Acme/SocialBundle/Resources/config/validation.xml -->
+        <class name="Acme\SocialBundle\Entity\Person">
+            <property name="age">
+                <constraint name="LessThan">today</constraint>
+            </property>
+        </class>
+
+    .. code-block:: php
+
+        // src/Acme/SocialBundle/Entity/Person.php
+        namespace Acme\SocialBundle\Entity;
+
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Person
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('age', new Assert\LessThan('today'));
+            }
+        }
+
+Be aware that PHP will use the server's configured timezone to interpret these
+dates. If you want to fix the timezone, append it to the date string:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # src/SocialBundle/Resources/config/validation.yml
+        Acme\SocialBundle\Entity\Person:
+            properties:
+                age:
+                    - LessThan: today UTC
+
+    .. code-block:: php-annotations
+
+        // src/Acme/SocialBundle/Entity/Person.php
+        namespace Acme\SocialBundle\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Person
+        {
+            /**
+             * @Assert\LessThan("today UTC")
+             */
+            protected $age;
+        }
+
+    .. code-block:: xml
+
+        <!-- src/Acme/SocialBundle/Resources/config/validation.xml -->
+        <class name="Acme\SocialBundle\Entity\Person">
+            <property name="age">
+                <constraint name="GreaterThan">today UTC</constraint>
+            </property>
+        </class>
+
+    .. code-block:: php
+
+        // src/Acme/SocialBundle/Entity/Person.php
+        namespace Acme\SocialBundle\Entity;
+
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Person
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('age', new Assert\LessThan('today UTC'));
+            }
+        }
+
+The ``DateTime`` class also accepts relative dates or times. For example, you
+can check that a person must be at least 18 years old like this:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # src/SocialBundle/Resources/config/validation.yml
+        Acme\SocialBundle\Entity\Person:
+            properties:
+                age:
+                    - LessThan: -18 years
+
+    .. code-block:: php-annotations
+
+        // src/Acme/SocialBundle/Entity/Person.php
+        namespace Acme\SocialBundle\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Person
+        {
+            /**
+             * @Assert\LessThan("-18 years")
+             */
+            protected $age;
+        }
+
+    .. code-block:: xml
+
+        <!-- src/Acme/SocialBundle/Resources/config/validation.xml -->
+        <class name="Acme\SocialBundle\Entity\Person">
+            <property name="age">
+                <constraint name="LessThan">-18 years</constraint>
+            </property>
+        </class>
+
+    .. code-block:: php
+
+        // src/Acme/SocialBundle/Entity/Person.php
+        namespace Acme\SocialBundle\Entity;
+
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Person
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('age', new Assert\LessThan('-18 years'));
+            }
+        }
+
 Options
 -------
 
@@ -95,3 +258,5 @@ message
 
 This is the message that will be shown if the value is not less than the
 comparison value.
+
+.. _`accepted by the DateTime constructor`: http://www.php.net/manual/en/datetime.formats.php
diff --git a/reference/constraints/LessThanOrEqual.rst b/reference/constraints/LessThanOrEqual.rst
index d706ac20693..61261fbe571 100644
--- a/reference/constraints/LessThanOrEqual.rst
+++ b/reference/constraints/LessThanOrEqual.rst
@@ -82,6 +82,169 @@ equal to ``80``, you could do the following:
             }
         }
 
+Comparing Dates
+---------------
+
+This constraint can be used to compare ``DateTime`` objects against any date
+string `accepted by the DateTime constructor`_. For example, you could check
+that a date must be today or in the past like this:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # src/SocialBundle/Resources/config/validation.yml
+        Acme\SocialBundle\Entity\Person:
+            properties:
+                age:
+                    - LessThanOrEqual: today
+
+    .. code-block:: php-annotations
+
+        // src/Acme/SocialBundle/Entity/Person.php
+        namespace Acme\SocialBundle\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Person
+        {
+            /**
+             * @Assert\LessThanOrEqual("today")
+             */
+            protected $age;
+        }
+
+    .. code-block:: xml
+
+        <!-- src/Acme/SocialBundle/Resources/config/validation.xml -->
+        <class name="Acme\SocialBundle\Entity\Person">
+            <property name="age">
+                <constraint name="LessThanOrEqual">today</constraint>
+            </property>
+        </class>
+
+    .. code-block:: php
+
+        // src/Acme/SocialBundle/Entity/Person.php
+        namespace Acme\SocialBundle\Entity;
+
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Person
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('age', new Assert\LessThanOrEqual('today'));
+            }
+        }
+
+Be aware that PHP will use the server's configured timezone to interpret these
+dates. If you want to fix the timezone, append it to the date string:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # src/SocialBundle/Resources/config/validation.yml
+        Acme\SocialBundle\Entity\Person:
+            properties:
+                age:
+                    - LessThanOrEqual: today UTC
+
+    .. code-block:: php-annotations
+
+        // src/Acme/SocialBundle/Entity/Person.php
+        namespace Acme\SocialBundle\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Person
+        {
+            /**
+             * @Assert\LessThanOrEqual("today UTC")
+             */
+            protected $age;
+        }
+
+    .. code-block:: xml
+
+        <!-- src/Acme/SocialBundle/Resources/config/validation.xml -->
+        <class name="Acme\SocialBundle\Entity\Person">
+            <property name="age">
+                <constraint name="GreaterThan">today UTC</constraint>
+            </property>
+        </class>
+
+    .. code-block:: php
+
+        // src/Acme/SocialBundle/Entity/Person.php
+        namespace Acme\SocialBundle\Entity;
+
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Person
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('age', new Assert\LessThanOrEqual('today UTC'));
+            }
+        }
+
+The ``DateTime`` class also accepts relative dates or times. For example, you
+can check that a person must be at least 18 years old like this:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # src/SocialBundle/Resources/config/validation.yml
+        Acme\SocialBundle\Entity\Person:
+            properties:
+                age:
+                    - LessThanOrEqual: -18 years
+
+    .. code-block:: php-annotations
+
+        // src/Acme/SocialBundle/Entity/Person.php
+        namespace Acme\SocialBundle\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Person
+        {
+            /**
+             * @Assert\LessThanOrEqual("-18 years")
+             */
+            protected $age;
+        }
+
+    .. code-block:: xml
+
+        <!-- src/Acme/SocialBundle/Resources/config/validation.xml -->
+        <class name="Acme\SocialBundle\Entity\Person">
+            <property name="age">
+                <constraint name="LessThanOrEqual">-18 years</constraint>
+            </property>
+        </class>
+
+    .. code-block:: php
+
+        // src/Acme/SocialBundle/Entity/Person.php
+        namespace Acme\SocialBundle\Entity;
+
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Person
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('age', new Assert\LessThanOrEqual('-18 years'));
+            }
+        }
+
 Options
 -------
 
@@ -94,3 +257,5 @@ message
 
 This is the message that will be shown if the value is not less than or equal
 to the comparison value.
+
+.. _`accepted by the DateTime constructor`: http://www.php.net/manual/en/datetime.formats.php
diff --git a/reference/constraints/Range.rst b/reference/constraints/Range.rst
index 1c46d7778fa..c78431a42a7 100644
--- a/reference/constraints/Range.rst
+++ b/reference/constraints/Range.rst
@@ -98,6 +98,203 @@ the following:
             }
         }
 
+Date Ranges
+-----------
+
+This constraint can be used to compare ``DateTime`` objects against date ranges.
+The minimum and maximum date of the range should be given as any date string
+`accepted by the DateTime constructor`_. For example, you could check that a
+date must lie within the current year like this:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # src/EventBundle/Resources/config/validation.yml
+        Acme\EventBundle\Entity\Event:
+            properties:
+                startDate:
+                    - Range:
+                        min: first day of January
+                        max: first day of January next year
+
+    .. code-block:: php-annotations
+
+        // src/Acme/SocialBundle/Entity/Event.php
+        namespace Acme\EventBundle\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Event
+        {
+            /**
+             * @Assert\Range(
+             *      min = "first day of January",
+             *      max = "first day of January next year"
+             * )
+             */
+            protected $startDate;
+        }
+
+    .. code-block:: xml
+
+        <!-- src/Acme/EventBundle/Resources/config/validation.xml -->
+        <class name="Acme\EventBundle\Entity\Event">
+            <property name="startDate">
+                <constraint name="Range">
+                    <option name="min">first day of January</option>
+                    <option name="max">first day of January next year</option>
+                </constraint>
+            </property>
+        </class>
+
+    .. code-block:: php
+
+        // src/Acme/EventBundle/Entity/Person.php
+        namespace Acme\EventBundle\Entity;
+
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Event
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('startDate', new Assert\Range(array(
+                    'min' => 'first day of January',
+                    'max' => 'first day of January next year',
+                )));
+            }
+        }
+
+Be aware that PHP will use the server's configured timezone to interpret these
+dates. If you want to fix the timezone, append it to the date string:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # src/EventBundle/Resources/config/validation.yml
+        Acme\EventBundle\Entity\Event:
+            properties:
+                startDate:
+                    - Range:
+                        min: first day of January UTC
+                        max: first day of January next year UTC
+
+    .. code-block:: php-annotations
+
+        // src/Acme/SocialBundle/Entity/Event.php
+        namespace Acme\EventBundle\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Event
+        {
+            /**
+             * @Assert\Range(
+             *      min = "first day of January UTC",
+             *      max = "first day of January next year UTC"
+             * )
+             */
+            protected $startDate;
+        }
+
+    .. code-block:: xml
+
+        <!-- src/Acme/EventBundle/Resources/config/validation.xml -->
+        <class name="Acme\EventBundle\Entity\Event">
+            <property name="startDate">
+                <constraint name="Range">
+                    <option name="min">first day of January UTC</option>
+                    <option name="max">first day of January next year UTC</option>
+                </constraint>
+            </property>
+        </class>
+
+    .. code-block:: php
+
+        // src/Acme/EventBundle/Entity/Person.php
+        namespace Acme\EventBundle\Entity;
+
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Event
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('startDate', new Assert\Range(array(
+                    'min' => 'first day of January UTC',
+                    'max' => 'first day of January next year UTC',
+                )));
+            }
+        }
+
+The ``DateTime`` class also accepts relative dates or times. For example, you
+can check that a delivery date starts within the next five hours like this:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # src/OrderBundle/Resources/config/validation.yml
+        Acme\OrderBundle\Entity\Order:
+            properties:
+                deliveryDate:
+                    - Range:
+                        min: now
+                        max: +5 hours
+
+    .. code-block:: php-annotations
+
+        // src/Acme/SocialBundle/Entity/Order.php
+        namespace Acme\OrderBundle\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Order
+        {
+            /**
+             * @Assert\Range(
+             *      min = "now",
+             *      max = "+5 hours"
+             * )
+             */
+            protected $deliveryDate;
+        }
+
+    .. code-block:: xml
+
+        <!-- src/Acme/OrderBundle/Resources/config/validation.xml -->
+        <class name="Acme\OrderBundle\Entity\Order">
+            <property name="deliveryDate">
+                <constraint name="Range">
+                    <option name="min">now</option>
+                    <option name="max">+5 hours</option>
+                </constraint>
+            </property>
+        </class>
+
+    .. code-block:: php
+
+        // src/Acme/OrderBundle/Entity/Order.php
+        namespace Acme\OrderBundle\Entity;
+
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Order
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('deliveryDate', new Assert\Range(array(
+                    'min' => 'now',
+                    'max' => '+5 hours',
+                )));
+            }
+        }
+
 Options
 -------
 
@@ -142,3 +339,4 @@ The message that will be shown if the underlying value is not a number (per
 the `is_numeric`_ PHP function).
 
 .. _`is_numeric`: http://www.php.net/manual/en/function.is-numeric.php
+.. _`accepted by the DateTime constructor`: http://www.php.net/manual/en/datetime.formats.php