Skip to content

[WCM] Added information about the new date handling in the comparison constraints and Range #4143

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

[WCM] Added information about the new date handling in the comparison constraints and Range #4143

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion reference/constraints/EqualTo.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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::

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't it useful to explain how to compare Date instances here too?

This constraint compares using ``==``, so ``3`` and ``"3"`` are considered
equal. Use :doc:`/reference/constraints/IdenticalTo` to compare with
``===``.
Expand Down
166 changes: 166 additions & 0 deletions reference/constraints/GreaterThan.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,170 @@ If you want to ensure that the ``age`` of a ``Person`` class is greater than
}
}

Comparing Dates
---------------

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you need to add a .. versionadded:: 2.6 directive

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

missing Acme (also in the YAML code blocks below)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it should use AppBundle now

Acme\OrderBundle\Entity\Order:
properties:
deliveryDate:
- GreaterThan: today

.. code-block:: php-annotations

// src/Acme/SocialBundle/Entity/Order.php
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OrderBundle

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems to be wrong in all annotation code blocks.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

shouldn't we use AcmeDemoBundle like everywhere in the doc ?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We already use different examples in the constraint reference (e.g. AcmeBlogBundle, AcmeEventBundle, and so on). So, I think that's okay here.

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>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I prefer to have fully working XML examples:

<!-- src/Acme/OrderBundle/Resources/config/validation.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">

    <class name="Acme\OrderBundle\Entity\Order">
        <property name="deliveryDate">
            <constraint name="GreaterThan">today</constraint>
        </property>
    </class>
</constraint-mapping>

This also applies to the other XML code blocks below.


.. 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:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have a minor question regarding this phrase:

If you want to fix the timezone ...

Does fix always imply that something is broken? In that case, we could change it for something like this:

If you want to use a custom timezone ...
If you want to set a different timezone ...
If you want to configure the timezone explicitly ...

What I mean is that the server timezone isn't broken, it's just different from what we may need.


.. 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
-------

Expand All @@ -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
166 changes: 166 additions & 0 deletions reference/constraints/GreaterThanOrEqual.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
-------

Expand All @@ -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
Loading