Collection

Дата оновлення перекладу 2022-12-16

Collection

Це обмеження використовується, коли дані, що лежать в основі, є колекцією (тобто масивом або об'єктом, що реалізує Traversable та ArrayAccess), але ви хочете валідувати різні ключі цієї колекції різними способами. Наприклад, ви можете валідувати ключ email, використовуючи обмеження Email, а ключ колекції inventory - з обмеженням Range.

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

Базове застосування

Обмеження 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 $profileData = array(
        'personal_email' => '...',
        'short_bio' => '...',
    );

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

Щоб валідувати те, що елемент personal_email властивості масиву profileData є валідною адресою електронної пошти, і що елемент short_bio не пустий, але при цьому не перевищує 100 символів у довжину, вам необхідно зробити наступне:

Attributes
YAML
XML
PHP

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

use Symfony\Component\Validator\Constraints as Assert;

// ВАЖЛИВО: вкладені атрибути вимагають PHP 8.1 або вище
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 $profileData = [
        'personal_email' => '...',
        'short_bio' => '...',
    ];
}
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
        # config/validator/validation.yaml
App\Entity\Author:
    properties:
        profileData:
            - Collection:
                fields:
                    personal_email:
                        - Email: ~
                    short_bio:
                        - NotBlank: ~
                        - Length:
                            max:   100
                            maxMessage: Your short bio is too long!
                allowMissingFields: true
    

        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="profileData">
            <constraint name="Collection">
                <option name="fields">
                    <value key="personal_email">
                        <constraint name="Email"/>
                    </value>
                    <value key="short_bio">
                        <constraint name="NotBlank"/>
                        <constraint name="Length">
                            <option name="max">100</option>
                            <option name="maxMessage">Your short bio is too long!</option>
                        </constraint>
                    </value>
                </option>
                <option name="allowMissingFields">true</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/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)
    {
        $metadata->addPropertyConstraint('profileData', new 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,
        ]));
    }
}
    

Наявність та відсутність полів

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

Якщо ви хочете дозволити відсутність ключів у колекції, або ви хочете дозволити "додаткові" ключі в колекції, то ви можете відповідно змінити опції allowMissingFields і allowExtraFields. У прикладі вище, опція allowMissingFields була встановлена як "true", що означає, що якщо б у властивості $personalData був відсутній елемент personal_email або short_bio, то помилки валідації не вібулося б.

Обов'язкові та необов'язкові обмеження поля

Обмеежння полів у колекції можна огорнути в обмеження Required або Optional, щоб контролювати, чи мають вони бути застосовані завжди (Required), або лише за наявності поля (Optional).

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

Attributes
YAML
XML
PHP

        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 $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
{
    protected $profileData = ['personal_email'];

    public static function loadValidatorMetadata(ClassMetadata $metadata)
    {
        $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" і виявлено додаткове поле.

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

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

`fields`

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

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

`missingFieldsMessage`

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

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

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

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

Дата оновлення перекладу 2022-12-20

`payload`

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

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

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

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