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, але його обробка повністю залежить від вас.
Наприклад, ви можете захотіти використати декілька рівнів помилок, щоб представити неуспішні обмеження по-різному у фронтенді, залежно від серйозності помилки.