Range

Дата обновления перевода 2023-09-25

Range

Валидирует, что заданное число находится между некоторым минимальным и максимальным числом.

??????????? ?	???????? ??? ??????
?????	Range
?????????	RangeValidator

Базовое применение

Чтобы убедиться, что поле класса height находится между 120 и 180, вы можете добавить следующее:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
        // src/Entity/Participant.php
namespace App\Entity;

use Symfony\Component\Validator\Constraints as Assert;

class Participant
{
    #[Assert\Range(
        min: 120,
        max: 180,
        notInRangeMessage: 'You must be between {{ min }}cm and {{ max }}cm tall to enter',
    )]
    protected int $height;
}
    

        1
2
3
4
5
6
7
8
        # 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
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
        <!-- config/validator/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 https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">

    <class name="App\Entity\Participant">
        <property name="height">
            <constraint name="Range">
                <option name="min">120</option>
                <option name="max">180</option>
                <option name="notInRangeMessage">You must be between {{ min }}cm and {{ max }}cm tall to enter</option>
            </constraint>
        </property>
    </class>
</constraint-mapping>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
        // 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): void
    {
        $metadata->addPropertyConstraint('height', new Assert\Range([
            'min' => 120,
            'max' => 180,
            'notInRangeMessage' => 'You must be between {{ min }}cm and {{ max }}cm tall to enter',
        ]));
    }
}
    

Это ограничение может быть использовано для сравнения объектов DateTime с диапазоном дат. Минимальная и максимальная даты диапазона должны быть заданы, как любая строка даты приемлемая конструктором DateTime. Например, вы можете проверить, чтобы дата находилась в текущем году, таким образом:

        1
2
3
4
5
6
7
8
9
10
11
12
13
        // 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 \DateTimeInterface $startDate;
}
    

        1
2
3
4
5
6
7
        # config/validator/validation.yaml
App\Entity\Event:
    properties:
        startDate:
            - Range:
                min: first day of January
                max: first day of January next year
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
        <!-- config/validator/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 https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">

    <class name="App\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>
</constraint-mapping>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        // 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): void
    {
        $metadata->addPropertyConstraint('startDate', new Assert\Range([
            'min' => 'first day of January',
            'max' => 'first day of January next year',
        ]));
    }
}
    

Помните, что PHP будет использовать часовой пояс, сконфигурированный сервером, чтобы интерпретировать эти данные. Если вы хотите изменить часовой пояс, добавьте его в начале строки даты:

        1
2
3
4
5
6
7
8
9
10
11
12
13
        // 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 \DateTimeInterface $startDate;
}
    

        1
2
3
4
5
6
7
        # config/validator/validation.yaml
App\Entity\Event:
    properties:
        startDate:
            - Range:
                min: first day of January UTC
                max: first day of January next year UTC
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
        <!-- config/validator/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 https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">

    <class name="App\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>
</constraint-mapping>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        // 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): void
    {
        $metadata->addPropertyConstraint('startDate', new Assert\Range([
            'min' => 'first day of January UTC',
            'max' => 'first day of January next year UTC',
        ]));
    }
}
    

Класс DateTime также принимает относительные даты и время. Например, вы можете проверить, чтобы дата доставки начиналась в течение следующих пяти часов, таким образом:

        1
2
3
4
5
6
7
8
9
10
11
12
13
        // src/Entity/Order.php
namespace App\Entity;

use Symfony\Component\Validator\Constraints as Assert;

class Order
{
    #[Assert\Range(
        min: 'now',
        max: '+5 hours',
    )]
    protected \DateTimeInterface $deliveryDate;
}
    

        1
2
3
4
5
6
7
        # config/validator/validation.yaml
App\Entity\Order:
    properties:
        deliveryDate:
            - Range:
                min: now
                max: +5 hours
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
        <!-- config/validator/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 https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">

    <class name="App\Entity\Order">
        <property name="deliveryDate">
            <constraint name="Range">
                <option name="min">now</option>
                <option name="max">+5 hours</option>
            </constraint>
        </property>
    </class>
</constraint-mapping>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        // 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): void
    {
        $metadata->addPropertyConstraint('deliveryDate', new Assert\Range([
            'min' => 'now',
            'max' => '+5 hours',
        ]));
    }
}
    

Опции

`groups`

type: array | string default: null

It defines the validation group or groups of this constraint. Read more about validation groups.

`invalidDateTimeMessage`

тип: string по умолчанию: Это значение должно быть валидным числом.

Сообщение, отображённое, когда значения min и max являются датами и временем PHP, а заданное значение - нет.

Вы можете использовать следующие параметры в этом сообщении:

????????	????????
`{{ value }}`	??????? (??????????) ????????

`invalidMessage`

тип: string по умолчанию: Это значение должно быть валидным числом.

Сообщение, отображённок, когда значения min и max числовые (в соответствии с PHP-функцией is_numeric), а заданное значение - нет.

Вы можете использовать следующие параметры в этом сообщении:

????????	????????
`{{ value }}`	??????? (??????????) ????????
`{{ label }}`	??????????????? ????? ???? ?????

`max`

тип: number или string (формат даты)

Эта обязательная опция является максимальным значением. Валидация будет неуспешной, если заданное значение будет больше минимального значения.

`maxMessage`

тип: string по умолчанию: Это значение должно быть {{ limit }} или меньше.

Сообщение, отбражённое, если основоположное значение больше, чем опция max, а опция min не была определена (если определены обе, используйте notInRangeMessage).

Вы можете использовать следующие параметры в этом сообщении:

????????	????????
`{{ limit }}`	??????? ?????
`{{ value }}`	??????? (??????????) ????????

`maxPropertyPath`

тип: string

Определяет свойство объекта, чьё значение используется как опция max.

Например, если вы хотите сравнить свойство $submittedDate некоторого объекта, относительно свойства $deadline того же объекта, используйте maxPropertyPath="deadline" в ограничении диапазона $submittedDate.

Tip

При использовании этой опции, её значение доступно в сообщении об ошибке, как заполнитель {{ max_limit_path }}. Хотя она не предназначается для использования в отображении сообщений об ошибках конечным пользователям, она полезна при использовании API для построения логики отображния на клиентской стороне.

`min`

тип: number или string (формат даты)

Эта обязательная опция является минимальным значением. Валидация будет неуспешной, если заданное значение будет меньше минимального значения.

`minMessage`

тип: string по умолчанию: Это значение должно быть {{ limit }} или больше.

Сообщение, отбражённое, если основоположное значение меньше, чем опция min, а опция max не была определена (если определены обе, используйте notInRangeMessage).

Вы можете использовать следующие параметры в этом сообщении:

????????	????????
`{{ limit }}`	?????? ?????
`{{ value }}`	??????? (??????????) ????????

`minPropertyPath`

тип: string

Определяет свойство объекта, чьё значение используется как опция min.

Например, если вы хотите сравнить свойство $endDate некоторого объекта, относительно свойства $startDate того же объекта, используйте minPropertyPath="startDate" в ограничении диапазона $endDate.

Tip

При использовании этой опции, её значение доступно в сообщении об ошибке, как заполнитель {{ min_limit_path }}. Хотя она не предназначается для использования в отображении сообщений об ошибках конечным пользователям, она полезна при использовании API для построения логики отображния на клиентской стороне.

`notInRangeMessage`

тип: string по умолчанию: Это значение должно быть между {{ min }} и {{ max }}.

Сообщение, которое будет отображено, если основоположное значение меньше, чем опция min или больше, чем опция max.

Вы можете использовать следующие параметры в этом сообщении:

????????	????????
`{{ max }}`	??????? ?????
`{{ min }}`	?????? ?????
`{{ value }}`	??????? (??????????) ????????

Дата обновления перевода 2024-07-25

payload

тип: mixed по умолчанию: null

Эта опция может быть использована, чтобы добавить к ограничению произвольные данные, относящиеся к домену. Сконфигурированная нагрузка не используется компонентом Валидатор, но его обработка полностью зависит от вас.

Например, вы можете захотеть исользовать несколько уровней ошибок, чтобы представить неудачные ограничения в фронт-энде по-разному, в зависимости от степени сложности ошибки.