Наличие и отсутствие полей

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

Если вы хотите разрешить отсутствие ключей в коллекции, или вы хотите позволить "дополнительные" ключи в коллекции, то вы можете соответственно изменить опции allowMissingFields и allowExtraFields. В примере выше, опция allowMissingFields была установлена, как "true", что означает, что если бы в свойстве $personalData отсутствовал элемент personal_email или short_bio, то ошибки валидации бы не произошло.

Обязательные и необязательные ограничения поля

Ограничения полей в коллекции можно обернуть в ограничение Required или Optional, чтобы контролировать, должны ли они быть применены всегда (Required), или только при наличии поля (Optional).

Например, если вы хотите требовать, чтобы поле personal_email массива profileData не было пустым и являлось валидным адресом электронной почты, а поле alternate_email было необязательным, но являлось валидным адресом электронной почты в случае его заполнения, вы можете сделать следующее:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// src/Entity/Author.php
namespace App\Entity;

use Symfony\Component\Validator\Constraints as Assert;

class Author
{
    #[Assert\Collection(
        fields: [
            'personal_email' => new Assert\Required([
                new Assert\NotBlank,
                new Assert\Email,
            ]),
            'alternate_email' => new Assert\Optional(
                new Assert\Email
            ),
        ],
    )]
    protected array $profileData = ['personal_email' => 'email@example.com'];
}

1
2
3
4
5
6
7
8
9
10
11
12
13

# config/validator/validation.yaml
App\Entity\Author:
    properties:
        profile_data:
            - Collection:
                fields:
                    personal_email:
                        - Required:
                            - NotBlank: ~
                            - Email: ~
                    alternate_email:
                        - Optional:
                            - Email: ~

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

<!-- 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\Author">
        <property name="profile_data">
            <constraint name="Collection">
                <option name="fields">
                    <value key="personal_email">
                        <constraint name="Required">
                            <constraint name="NotBlank"/>
                            <constraint name="Email"/>
                        </constraint>
                    </value>
                    <value key="alternate_email">
                        <constraint name="Optional">
                            <constraint name="Email"/>
                        </constraint>
                    </value>
                </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

// src/Entity/Author.php
namespace App\Entity;

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

class Author
{
    // ...

    public static function loadValidatorMetadata(ClassMetadata $metadata): void
    {
        $metadata->addPropertyConstraint('profileData', new Assert\Collection(
            fields: [
                'personal_email'  => new Assert\Required([
                    new Assert\NotBlank(),
                    new Assert\Email(),
                ]),
                'alternate_email' => new Assert\Optional(new Assert\Email()),
            ],
        ));
    }
}

Даже если allowMissingFields не установлен, как "true", вы теперь можете полностью опустить свойство alternate_email из массива profileData, так как оно Optional. Однакое, если поле personal_email не существует в массиве, то ограничение NotBlank всё равно будет применено (так как оно обёрнуто в Required) и вы получите нарушение ограничения.

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

1
2
3
4
5
6
7
8

use Symfony\Component\Validator\Constraints as Assert;

$constraint = new Assert\Collection(
    fields: [
        'name' => new Assert\NotBlank(['groups' => 'basic']),
        'email' => new Assert\NotBlank(['groups' => 'contact']),
    ],
);

Это приведет к следующей конфигурации:

1
2
3
4
5
6
7
8
9
10
11
12
13

$constraint = new Assert\Collection(
    fields: [
        'name' => new Assert\Required(
            constraints: new Assert\NotBlank(groups: ['basic']),
            groups: ['basic', 'strict'],
        ),
        'email' => new Assert\Required(
            constraints: new Assert\NotBlank(groups: ['contact']),
            groups: ['basic', 'strict'],
        ),
    ],
    groups: ['basic', 'strict'],
);

Опция по умолчанию allowMissingFields требует полей во всех группах. Поэтому, когда вы валидируете в группе contact, $name может быть пустым, но ключ все равно будет необходим. Если это не то поведение, которого вы хотите, ясно используйте ограничение Optional вместо Required.

allowExtraFields

тип: boolean по умолчанию: false

Если эта опция установлена, как false, а основоположная коллекция содержит один или более элементов, не включённых в опцию fields, будет возвращена ошибка валидации. Если установлена, как true, дополнительные поля допустимы.

allowMissingFields

тип: boolean по умолчанию: false

Если эта опция установлена, как false, и одно или более полей из опции fields отсутствуют в освноположной коллекции, будет возвращена ошибка валидации. Если установленка, как true, то отсутствие некоторых полей опции fields в основоположной коллекции допускается.

extraFieldsMessage

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

Сообщение, отображаемое, если allowExtraFields - "false", и обнаружено дополнительное поле.

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

fields

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

Эта опция обязательна и является ассоциативным массивом, определяющим все ключи в коллекции, и, для каждого ключа, какой конкретно валидатор(ы) должен быть выполнен для этого элемента коллекции.

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

groups

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

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

missingFieldsMessage

тип: string по умолчанию: Это поле потсутствует.

Сообщение, отображаемое, если allowMissingFields - "false", и одно или более полей отсутствуют в основоположной коллекции.

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

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

payload

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

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

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