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

Ця опція може бути використана, щоб додати довільні дані, специфічні для домену, до обмеження. Сконфігуроване корисне навантаження не використовується компонентом Validator, але його обробка повністю залежить від вас.

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

`values`

тип: array за замовчуванням: []

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