Collection

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

Collection

Это ограничение используется, когда основоположные данные являются коллекцией (т.е. массивом или объектом, реализующим Traversable и ArrayAccess), но вы хотите валидировать разные ключи этой коллекции разными способами. Например, вы можете валидировать ключ email, используя ограничение Email, а ключ коллекции inventory с огранчением Range.

Это ограничение также может убедиться в том, что определённые ключи коллекции присутствуют, и что отсутствуют лишние ключи.

See also

Если вы хотите валидировать, что все элементы коллекции уникальны, используйте ограничение Unique.

??????????? ? ???????? ??? ??????
????? Collection
????????? CollectionValidator

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

Ограничение Collection позволяет вам валидировать разные ключи коллекции по-отдельности. Рассмотрите следующий пример:

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

class Author
{
    protected array $profileData = [
        'personal_email' => '...',
        'short_bio' => '...',
    ];

    public function setProfileData($key, $value): void
    {
        $this->profileData[$key] = $value;
    }
}

Чтобы валидировать то, что элемент personal_email свойства массива profileData является валидным адресом электронной почты, и что элемент short_bio не пустой, но при этом не превышает 100 символов в длину, вам нужно сделать следующее:

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/Entity/Author.php
namespace App\Entity;

use Symfony\Component\Validator\Constraints as Assert;

class Author
{
    #[Assert\Collection(
        fields: [
            'personal_email' => new Assert\Email,
            'short_bio' => [
                new Assert\NotBlank,
                new Assert\Length(
                    max: 100,
                    maxMessage: 'Your short bio is too long!'
                )
            ]
        ],
        allowMissingFields: true,
    )]
    protected array $profileData = [
        'personal_email' => '...',
        'short_bio' => '...',
    ];
}

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

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

Если вы хотите разрешить отсутствие ключей в коллекции, или вы хотите позволить "дополнительные" ключи в коллекции, то вы можете соответственно изменить опции 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'];
}

Даже если 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", и обнаружено дополнительное поле.

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

???????? ????????
{{ field }} ???? ????????????? ??????????????? ????

fields

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

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

groups

type: array | string default: null

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

missingFieldsMessage

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

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

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

???????? ????????
{{ field }} ???? ?????????????? ????, ????????????? ? fields

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

payload

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

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

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