When

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

When

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

???????????	? ?????? ??? ????????/??????
?????	expression constraints
?????	When
?????????	WhenValidator

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

Представьте, что у вас есть класс Discount со свойствами type и value:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
        // src/Model/Discount.php
namespace App\Model;

class Discount
{
    private ?string $type;

    private ?int $value;

    // ...

    public function getType(): ?string
    {
        return $this->type;
    }

    public function getValue(): ?int
    {
        return $this->value;
    }
}
    

Щоб валідувати обʼєкт, у вас є деякі вимоги:

A) Якщо type - percent, тоді value має бути меншим ніж або дорівнювати 100; B) Якщо type - absolute, тоді value може бути чим завгодно; C) Не зважаючи на значення type, value має бути більшим за 0.

Одним способом досягти цього - це з обмеженням When:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
        // src/Model/Discount.php
namespace App\Model;

use Symfony\Component\Validator\Constraints as Assert;

class Discount
{
    #[Assert\GreaterThan(0)]
    #[Assert\When(
        expression: 'this.getType() == "percent"',
        constraints: [
            new Assert\LessThanOrEqual(100, message: 'The value should be between 1 and 100!')
        ],
        otherwise: [
            new Assert\LessThan(9999, message: 'The value should be less than 9999!')
        ],
    )]
    private ?int $value;

    // ...
}
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
        # config/validator/validation.yaml
App\Model\Discount:
    properties:
        value:
            - GreaterThan: 0
            - When:
                expression: "this.getType() == 'percent'"
                constraints:
                    - LessThanOrEqual:
                        value: 100
                        message: "The value should be between 1 and 100!"
                otherwise:
                    - LessThan:
                        value: 9999
                        message: "The value should be less than 9999!"
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
        <!-- 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\Model\Discount">
        <property name="value">
            <constraint name="GreaterThan">0</constraint>
            <constraint name="When">
                <option name="expression">
                    this.getType() == 'percent'
                </option>
                <option name="constraints">
                    <constraint name="LessThanOrEqual">
                        <option name="value">100</option>
                        <option name="message">The value should be between 1 and 100!</option>
                    </constraint>
                </option>
                <option name="otherwise">
                    <constraint name="LessThan">
                        <option name="value">9999</option>
                        <option name="message">The value should be less than 9999!</option>
                    </constraint>
                </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
20
21
22
23
24
25
26
27
28
29
30
        // src/Model/Discount.php
namespace App\Model;

use Symfony\Component\Validator\Constraints as Assert;
use Symfony\Component\Validator\Mapping\ClassMetadata;

class Discount
{
    public static function loadValidatorMetadata(ClassMetadata $metadata): void
    {
        $metadata->addPropertyConstraint('value', new Assert\GreaterThan(0));
        $metadata->addPropertyConstraint('value', new Assert\When(
            expression: 'this.getType() == "percent"',
            constraints: [
                new Assert\LessThanOrEqual(
                    value: 100,
                    message: 'The value should be between 1 and 100!',
                ),
            ],
            otherwise: [
                new Assert\LessThan(
                    value: 9999,
                    message: 'The value should be less than 9999!',
                ),
            ],
        ));
    }

    // ...
}
    

Опция expression - это выражение, которое должно вернуть true, чтобы запустить валидацию присоединённых ограничений. Чтобы узнать больше о синтаксисе языка выражений, см. .

Чтобы получить больше информации о выражении и о том, какие переменные вам доступны, см. детали опции expression ниже.

Опции

`expression`

тип: string|Closure

Условие, которое оценивается для определения, применяется ли ограничение. Оно может быть определено как замыкание или строка с помощью синтаксиса языка выражений. Если результат является неверным значением (false, null, 0, пустая строка или пустой массив), ограничения, определенные в опции constraints, не будут применяться, но ограничения, определенные в опции otherwise (если она указана), будут применяться.

При использовании выражения вы можете получить доступ к следующим переменным:

this: Объект, который валидируется (например, экземпляр Discount).
value: Значения свойства, которое валидируется (доступно только если ограничение применяется к свойству).
context: Объект ExecutionContextInterface, который предоставляет такую информацию как класс, который валидируется, имя свойства, которое валидируется, список нарушений и т.д.

7.2

Переменная context в выражениях была представлена в Symfony 7.2.

При использовании замыкания первый аргумент является объектом, который валидируется.

7.3

Поддержка замыканий в опции expression была представлена в Symfony 7.3 и требует PHP 8.5.

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
        // src/Model/Discount.php
namespace App\Model;

use Symfony\Component\Validator\Constraints as Assert;
use Symfony\Component\Validator\Context\ExecutionContextInterface;

class Discount
{
    // either using an expression...
    #[Assert\When(
        expression: 'value == "percent"',
        constraints: [new Assert\Callback('doComplexValidation')],
    )]

    // ... or using a closure
    #[Assert\When(
        expression: static function (Discount $discount) {
            return $discount->getType() === 'percent';
        },
        constraints: [new Assert\Callback('doComplexValidation')],
    )]
    private ?string $type;

    // ...

    public function doComplexValidation(ExecutionContextInterface $context, $payload): void
    {
        // ...
    }
}
    

        1
2
3
4
5
6
7
8
        # config/validator/validation.yaml
App\Model\Discount:
    properties:
        type:
            - When:
                expression: "value == 'percent'"
                constraints:
                    - Callback: doComplexValidation
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
        <!-- 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\Model\Discount">
        <property name="type">
            <constraint name="When">
                <option name="expression">
                    value == 'percent'
                </option>
                <option name="constraints">
                    <constraint name="Callback">
                        <option name="callback">doComplexValidation</option>
                    </constraint>
                </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
20
21
22
23
24
25
        // src/Model/Discount.php
namespace App\Model;

use Symfony\Component\Validator\Constraints as Assert;
use Symfony\Component\Validator\Mapping\ClassMetadata;

class Discount
{
    // ...

    public static function loadValidatorMetadata(ClassMetadata $metadata): void
    {
        $metadata->addPropertyConstraint('type', new Assert\When(
            expression: 'value == "percent"',
            constraints: [
                new Assert\Callback('doComplexValidation'),
            ],
        ));
    }

    public function doComplexValidation(ExecutionContextInterface $context, $payload): void
    {
        // ...
    }
}
    

Вы можете также передать пользовательские переменные, используя опцию values.

`constraints`

тип: array|Constraint

Одно или несколько ограничений, которые применяются, если выражение возвращает true.

`otherwise`

тип: array|Constraint

Одно или несколько ограничений, которые используются в случае, если выражение возвращает false.

7.3

Опция otherwise была представлена в Symfony 7.3.

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

`groups`

тип: array | string по умолчанию: null

Определяет группу или группы валидации ограничений. Прочитайте больше о группах валидации.

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

payload

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

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

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

`values`

тип: array по умолчанию: []

Значения пользовательских переменных, ипользуемых в выражении. Значения могут быть любым типом (числовым, булевым, строками, null, и т.д.)