Range ===== Validates that a given number or ``DateTime`` object is *between* some minimum and maximum. ========== =================================================================== Applies to :ref:`property or method ` Options - `groups`_ - `invalidMessage`_ - `max`_ - `maxMessage`_ - `maxPropertyPath`_ - `min`_ - `minMessage`_ - `minPropertyPath`_ - `notInRangeMessage`_ - `payload`_ Class :class:`Symfony\\Component\\Validator\\Constraints\\Range` Validator :class:`Symfony\\Component\\Validator\\Constraints\\RangeValidator` ========== =================================================================== Basic Usage ----------- To verify that the "height" field of a class is between "120" and "180", you might add the following: .. configuration-block:: .. code-block:: php-annotations // src/Entity/Participant.php namespace App\Entity; use Symfony\Component\Validator\Constraints as Assert; class Participant { /** * @Assert\Range( * min = 120, * max = 180, * minMessage = "You must be at least {{ limit }}cm tall to enter", * maxMessage = "You cannot be taller than {{ limit }}cm to enter" * ) */ protected $height; } .. code-block:: yaml # config/validator/validation.yaml App\Entity\Participant: properties: height: - Range: min: 120 max: 180 notInRangeMessage: You must be between {{ min }}cm and {{ max }}cm tall to enter .. code-block:: xml .. code-block:: php // src/Entity/Participant.php namespace App\Entity; use Symfony\Component\Validator\Constraints as Assert; use Symfony\Component\Validator\Mapping\ClassMetadata; class Participant { public static function loadValidatorMetadata(ClassMetadata $metadata) { $metadata->addPropertyConstraint('height', new Assert\Range([ 'min' => 120, 'max' => 180, 'notInRangeMessage' => 'You must be between {{ min }}cm and {{ max }}cm tall to enter', ])); } } 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:: php-annotations // src/Entity/Event.php namespace App\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:: yaml # config/validator/validation.yaml App\Entity\Event: properties: startDate: - Range: min: first day of January max: first day of January next year .. code-block:: xml .. code-block:: php // src/Entity/Event.php namespace App\Entity; use Symfony\Component\Validator\Constraints as Assert; use Symfony\Component\Validator\Mapping\ClassMetadata; class Event { public static function loadValidatorMetadata(ClassMetadata $metadata) { $metadata->addPropertyConstraint('startDate', new Assert\Range([ '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:: php-annotations // src/Entity/Event.php namespace App\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:: yaml # config/validator/validation.yaml App\Entity\Event: properties: startDate: - Range: min: first day of January UTC max: first day of January next year UTC .. code-block:: xml .. code-block:: php // src/Entity/Person.php namespace App\Entity; use Symfony\Component\Validator\Constraints as Assert; use Symfony\Component\Validator\Mapping\ClassMetadata; class Event { public static function loadValidatorMetadata(ClassMetadata $metadata) { $metadata->addPropertyConstraint('startDate', new Assert\Range([ '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:: php-annotations // src/Entity/Order.php namespace App\Entity; use Symfony\Component\Validator\Constraints as Assert; class Order { /** * @Assert\Range( * min = "now", * max = "+5 hours" * ) */ protected $deliveryDate; } .. code-block:: yaml # config/validator/validation.yaml App\Entity\Order: properties: deliveryDate: - Range: min: now max: +5 hours .. code-block:: xml .. code-block:: php // src/Entity/Order.php namespace App\Entity; use Symfony\Component\Validator\Constraints as Assert; use Symfony\Component\Validator\Mapping\ClassMetadata; class Order { public static function loadValidatorMetadata(ClassMetadata $metadata) { $metadata->addPropertyConstraint('deliveryDate', new Assert\Range([ 'min' => 'now', 'max' => '+5 hours', ])); } } Options ------- .. include:: /reference/constraints/_groups-option.rst.inc invalidMessage ~~~~~~~~~~~~~~ **type**: ``string`` **default**: ``This value should be a valid number.`` The message that will be shown if the underlying value is not a number (per the :phpfunction:`is_numeric` PHP function). You can use the following parameters in this message: =============== ============================================================== Parameter Description =============== ============================================================== ``{{ value }}`` The current (invalid) value =============== ============================================================== max ~~~ **type**: ``number`` or ``string`` (date format) This required option is the "max" value. Validation will fail if the given value is **greater** than this max value. maxMessage ~~~~~~~~~~ **type**: ``string`` **default**: ``This value should be {{ limit }} or less.`` The message that will be shown if the underlying value is more than the `max`_ option, and no `min`_ option has been defined (if both are defined, use `notInRangeMessage`_). You can use the following parameters in this message: =============== ============================================================== Parameter Description =============== ============================================================== ``{{ limit }}`` The upper limit ``{{ value }}`` The current (invalid) value =============== ============================================================== maxPropertyPath ~~~~~~~~~~~~~~~ **type**: ``string`` It defines the object property whose value is used as ``max`` option. For example, if you want to compare the ``$submittedDate`` property of some object with regard to the ``$deadline`` property of the same object, use ``maxPropertyPath="deadline"`` in the range constraint of ``$submittedDate``. .. tip:: When using this option, its value is available in error messages as the ``{{ max_limit_path }}`` placeholder. Although it's not intended to include it in the error messages displayed to end users, it's useful when using APIs for doing any mapping logic on client-side. min ~~~ **type**: ``number`` or ``string`` (date format) This required option is the "min" value. Validation will fail if the given value is **less** than this min value. minMessage ~~~~~~~~~~ **type**: ``string`` **default**: ``This value should be {{ limit }} or more.`` The message that will be shown if the underlying value is less than the `min`_ option, and no `max`_ option has been defined (if both are defined, use `notInRangeMessage`_). You can use the following parameters in this message: =============== ============================================================== Parameter Description =============== ============================================================== ``{{ limit }}`` The lower limit ``{{ value }}`` The current (invalid) value =============== ============================================================== minPropertyPath ~~~~~~~~~~~~~~~ **type**: ``string`` It defines the object property whose value is used as ``min`` option. For example, if you want to compare the ``$endDate`` property of some object with regard to the ``$startDate`` property of the same object, use ``minPropertyPath="startDate"`` in the range constraint of ``$endDate``. .. tip:: When using this option, its value is available in error messages as the ``{{ min_limit_path }}`` placeholder. Although it's not intended to include it in the error messages displayed to end users, it's useful when using APIs for doing any mapping logic on client-side. notInRangeMessage ~~~~~~~~~~~~~~~~~ **type**: ``string`` **default**: ``This value should be between {{ min }} and {{ max }}.`` The message that will be shown if the underlying value is less than the `min`_ option or greater than the `max`_ option. You can use the following parameters in this message: =============== ============================================================== Parameter Description =============== ============================================================== ``{{ max }}`` The upper limit ``{{ min }}`` The lower limit ``{{ value }}`` The current (invalid) value =============== ============================================================== .. include:: /reference/constraints/_payload-option.rst.inc .. _`accepted by the DateTime constructor`: https://www.php.net/manual/en/datetime.formats.php