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 [опція за замовчуванням ]

Ця опція обов'язкова і є асоціативним масивом, який визначає всі ключі в колекції і для кожного ключа, який конкретно валідатор(и) має бути виконаний для цього елементу колекції.

missingFieldsMessage

тип: string за замовчуванням: Це поле відсутнє.

Повідомлення, яке відображається, якщо allowMissingFields - "false", і одне або більше полів відсутні в основній колекції.

Ви можете використати наступні параметри в цьому повідомленні:

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

Дата оновлення перекладу 2024-05-29

payload

тип: mixed за замовчуванням: null

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

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