allow_add

тип: boolean за замовчуванням: false

Якщо встановлена як true, то при відправленні у колекцію непізнаних об'єктів, вони будуть додані у якості нових. Остаточний масив міститиме існуючі об'єкти, а також новий об'єкт, який був у відправлених даних. Див. приклад вище, щоб дізнатися більше.

Опція prototype може бути використана, щоб допомогти відобразити об'єкт прототипу, який може бути використаний з JavaScript для динамічного створення нових об'єктів форми на клієнтській стороні. Щоб дізнатися більше, див. приклад вище та .

allow_delete

тип: boolean за замовчуванням: false

Якщо встановлена як true, то якщо існуючий об'єкт не міститься у відправлених даних, він буде правильно відсутнів в підсумковому масиві об'єктів. Це означає, що ви можете реалізувати кнопку "видалити" через JavaScript, який просто видалить елемент форми з DOM. Коли користувач надсилає форму, її відсутність у відправлених даних означатиме, що вона видалена з підсумкового масиву.

Щоб отримати більше інформації, див. .

delete_empty

тип: Boolean або callable за замовчуванням: false

Якщо ви хочете чітко видалити абсолютно пусті записи колекцій з вашої форми, то вам потрібно встановити цю опцію як true. Однак, існуючі записи колекції будуть видалені лише якщо у вас увімкнена опція allow_delete. Інакше пусті значення залишаться.

Значення видаляється з колекції лише якщо нормалізоване значення - null. Однак ви також можете встановити значення опції, як викликане, яке буде виконано для кожного значення у відправленій колекції. Якщо викликане поверне true, то значення видаляється з колекції. Наприклад:

1
2
3
4
5
6
7
8
9

use Symfony\Component\Form\Extension\Core\Type\CollectionType;
// ...

$builder->add('users', CollectionType::class, [
    // ...
    'delete_empty' => function (User $user = null): bool {
        return null === $user || empty($user->getFirstName());
    },
]);

Використання викликаного особилво корисно у випадку зі складними типами форм, які можуть визначати складні умови для їхнього розгляду як пустих.

entry_options

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

Це масив, який передається типу форми, вказаному в опції entry_type. Наприклад, якщо ви використали ChoiceType в якості вашої опції entry_type (наприклад, для колекції випадаючих меню), то вам потрібно хоча б передати опцію choices основному типу:

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

use Symfony\Component\Form\Extension\Core\Type\CollectionType;
use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
// ...

$builder->add('favorite_cities', CollectionType::class, array(
    'entry_type'   => ChoiceType::class,
    'entry_options'  => array(
        'choices'  => array(
            'Nashville' => 'nashville',
            'Paris'     => 'paris',
            'Berlin'    => 'berlin',
            'London'    => 'london',
        ),
    ),
));

prototype_options

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

Це масив, який перредається типу форми, вказаному в опції entry_type при створенні її прототипу. Дозволяє мати різні опції, залежно від того, додаєте ви новий запис чи редагуєте вже існуючий:

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

use Symfony\Component\Form\Extension\Core\Type\CollectionType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
// ...

$builder->add('names', CollectionType::class, [
    'entry_type' => TextType::class,
    'entry_options' => [
        'help' => 'You can edit this name here.',
    ],
    'prototype_options'  => [
        'help' => 'You can enter a new name here.',
    ],
]);

entry_type

тип: string за замовчуванням: Symfony\Component\Form\Extension\Core\Type\TextType

Це тип поля для кожного об'єкту в цій колекції (наприклад, TextType, ChoiceType, і т.д.). Наприклад, якщо у вас є масив адрес електронної пошти, то ви використовуватимете EmailType. Якщо ви хочете вбудувати колекцію в якусь іншу форму, створіть новий екземпляр вашого типу форми та передайте його в якості опції.

keep_as_list

тип: boolean за замовчуванням: false

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

Коли ця опція має значення false, якщо у вас є колекція з 3 елементів і
ви видаляєте другий елемент, то при валідації колекції індекси будуть 0 і 2. Однак, якщо увімкнути опцію keep_as_list і встановити для неї значення true, індекси буде переіндексовано на 0 та 1. Це гарантує, що індекси залишаться послідовними і не матимуть пропусків, забезпечуючи більш чітку та передбачувану структуру для ваших вкладених форм.

prototype

тип: boolean за замовчуванням: true

Ця опція корисна при використанні опції allow_add. Якщо true (і якщо allow_add також true), буде доступний спеціальний атрибут "прототипу", щоб ви могли відобразити приклад "Шаблону" того, як має виглядати новий елемент на вашій сторінці. Атрибут name, наданий цьому елементу - __name__. Це дозволяє вам додавати кнопку "додати ще" через JavaScript, який зчитує прототип, замінює __name__ деяким унікальним ім'ям або числом, та відображає його всередині вашої форми. При відправленні, він буде доданий у ваш основний масив завдяки опції allow_add.

Поле прототипу може бути відображено через змінну prototype у полі колекції:

1

{{ form_row(form.emails.vars.prototype) }}

Відмітьте, що все, що вам насправді потрібно, - це "віджет", але в залежності від того, як ви відображаєте форму, наявність цілого "Рядку форми" може бути легшою для вас.

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

prototype_data

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

Дозволяє вам визначати конкретні дані для прототипу. Кожний новий доданий рядок початково міститиме дані, встановлені цією опцією. За замовчуванням, будуть використані дані, сконфігуровані для всіх записів з опцією entry_options:

1
2
3
4
5
6
7
8
9
10

use Symfony\Component\Form\Extension\Core\Type\CollectionType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
// ...

$builder->add('tags', CollectionType::class, [
    'entry_type' => TextType::class,
    'allow_add' => true,
    'prototype' => true,
    'prototype_data' => 'New Tag Placeholder',
]);

prototype_name

тип: string за замовчуванням: __name__

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

invalid_message

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

Це повідомлення помилки валідації, яке використовується, якщо дані, введені у це поле, не мають сенсу (тобто валідація проходить невдало).

Це може трапитися, наприклад, якщо користувач вводить у поле TimeType асбурдний рядок, який не може бути конвертований в даний час, або якщо користувач вводить рядок (наприклад, apple) у числове поле.

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

attr

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

Якщо ви хочете додати додаткові атрибути до HTML представлення поля, то ви можете використовувати опцію attr. Це асоціативний масив із HTML-атрибутами в якості ключів. Це може бути корисно, коли вам потрібно встановити для деякого віджета користувацький клас:

1
2
3

$builder->add('body', TextareaType::class, [
    'attr' => ['class' => 'tinymce'],
]);

Дата оновлення перекладу 2025-02-22

by_reference

тип: boolean за замовчуванням: true

У більшості випадків, якщо у вас є поле author, то ви очікуєте, що у вихідному об'єкті буде викликано setAuthor(). Однак, у деяких випадках, setAuthor() може бути не викликаний. Встановивши by_reference, як false, ви гарантуєте, що сеттер буде викликаний у будь-якому випадку.

Щоб пояснити це детальніше, ось простий приклад:

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

use Symfony\Component\Form\Extension\Core\Type\EmailType;
use Symfony\Component\Form\Extension\Core\Type\FormType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
// ...

$builder = $this->createFormBuilder($article);
$builder
    ->add('title', TextType::class)
    ->add(
        $builder->create('author', FormType::class, ['by_reference' => ?])
            ->add('name', TextType::class)
            ->add('email', EmailType::class)
    )

Якщо by_reference - "true", то наступне відбувається за лаштунками, коли ви викликаєте submit() (або handleRequest()) у формі:

1
2
3

$article->setTitle('...');
$article->getAuthor()->setName('...');
$article->getAuthor()->setEmail('...');

Зауважте, що setAuthor() не викликається. Автор змінюється посиланням.

Якщо ви встановили by_reference як "false", відправка виглядає так:

1
2
3
4
5

$article->setTitle('...');
$author = clone $article->getAuthor();
$author->setName('...');
$author->setEmail('...');
$article->setAuthor($author);

Тому, все, що насправді робить by_reference=false - це змушує фреймворк визати сеттер у батьківському об'єкті.

Схожим чином, якщо ви використовуєте поле CollectionType, де ваша вихідна колекція даних є об'єктом (як з ArrayCollection у Doctrine), то by_reference має бути встановлена як false, якщо вам потрібно, щоб був викликаний додавач або знищувач (наприклад, addAuthor() і removeAuthor()).

Дата оновлення перекладу 2025-01-15

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

Це означає, що вона допомагає вам обробляти відправлення форм з порожніми полями. Наприклад, якщо ви хочете, щоб для поля name було явно встановлено значення
John Doe, коли не вибрано жодного значення, ви можете зробити це так:

1
2
3
4

$builder->add('name', null, [
    'required'   => false,
    'empty_data' => 'John Doe',
]);

Це все одно відобразить порожнє текстове поле, але після надсилання буде встановлено значення John Doe. Використовуйте опції data або placeholder, щоб показати це початкове значення у формі, що відображається.

Значення за замовчуванням - [] (пустий масив).

Дата оновлення перекладу 2025-01-15

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

Це означає, що вона допомагає вам обробляти відправлення форм з порожніми полями. Наприклад, якщо ви хочете, щоб для поля name було явно встановлено значення
John Doe, коли не вибрано жодного значення, ви можете зробити це так:

1
2
3
4

$builder->add('name', null, [
    'required'   => false,
    'empty_data' => 'John Doe',
]);

Це все одно відобразить порожнє текстове поле, але після надсилання буде встановлено значення John Doe. Використовуйте опції data або placeholder, щоб показати це початкове значення у формі, що відображається.

error_bubbling

тип: boolean за замовчуванням: true

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

Якщо true, будь-які помилки цього поля будуть передані батьківському полю або формі. Наприклад, якщо встановлено true у нормальному полі, будь-які помилки цього поля будуть прикріплені до головної форми, а не до конкретного поля.

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

error_mapping

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

Ця опція дозволяє вам змінювати ціль помилки валідації.

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

За допомогою кастомізованого мапування помилок ви можете зробити краще: співставити помилку з полем міста так, щоб воно відображалося над ним:

1
2
3
4
5
6
7
8

public function configureOptions(OptionsResolver $resolver): void
{
    $resolver->setDefaults([
        'error_mapping' => [
            'matchingCityAndZipCode' => 'city',
        ],
    ]);
}

Ось правила для лівої та правої частини мапування:

• Ліва частина містить шляхи властивостей;
• Якщо порушення генерується у властивості або методі класу, то його шлях - це propertyName;
• Якщо порушення згенеровано в елементі об'єкту array або ArrayAccess, то шлях до нього - [indexName];
• Ви можете створювати вкладені шляхи властивостей шляхом їх конкатенації, розділяючи властивості крапками. Наприклад: addresses[work].matchingCityAndZipCode;
• Права частина містить назви полів форми.

За замовчуванням, помилки для будь-якої властивості, яка не мапована, будуть спливати в батьківську форму. Ви можете використовувати крапку (.) зліва, щоб співставити помилки всіх неспівставлених властивостей до певного поля. Наприклад, щоб мапувати всі ці помилки до поля city, використовуйте:

1
2
3
4
5

$resolver->setDefaults([
    'error_mapping' => [
        '.' => 'city',
    ],
]);

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

help

тип: string або TranslatableInterface за замовчуванням: null

Дозволяє вам визначити повідомлення допомоги для поля форми, яке за замовчуванням відображається під полем:

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

use Symfony\Component\Translation\TranslatableMessage;

$builder
    ->add('zipCode', null, [
        'help' => 'The ZIP/Postal code for your credit card\'s billing address.',
    ])

    // ...

    ->add('status', null, [
        'help' => new TranslatableMessage('order.status', ['%order_id%' => $order->getId()], 'store'),
    ])
;

Дата оновлення перекладу 2025-02-24

help_attr

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

Встановлює HTML-атрибути для елемента, що використовується для відображення повідомлення допомоги
у полі форми. Його значенням є асоціативним масивом з іменами HTML-атрибутів в якості ключів. Ці атрибути також можуть бути встановлені в шаблоні:

1
2
3

{{ form_help(form.name, 'Your name', {
    'help_attr': {'class': 'CUSTOM_LABEL_CLASS'}
}) }}

Дата оновлення перекладу 2025-02-24

help_html

тип: boolean за замовчуванням: false

За замовчуванням, зміст опції help екранується перед відображенням у шаблоні. Встановіть для цієї опції значення true, щоб не екранувати його, що може бути корисно, якщо довідка містить HTML-елементи.

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

label

тип: string або TranslatableMessage за замовчуванням: Ярлик "вгадується" з імені поля

Встановлює ярлик, який буде використано при відображенні поля. Установка false прридушить ярлик:

1
2
3
4
5
6
7
8

use Symfony\Component\Translation\TranslatableMessage;

$builder
    ->add('zipCode', null, [
        'label' => 'The ZIP/Postal code',
        // опціонально, ви можете використати обʼєкти TranslatableMessage в якості змісту ярлика
        'label' => new TranslatableMessage('address.zipCode', ['%country%' => $country], 'address'),
    ])

Ярлик також може бути встановлений у шаблоні:

1

{{ form_label(form.name, 'Your name') }}

1
2
3
4

echo $view['form']->label(
    $form['name'],
    'Your name'
);

Дата оновлення перекладу 2025-02-24

label_attr

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

Встановлює HTML-атрибути для елемента <label>, який буде використаний при відображенні ярлика для поля. Це асоціативний масив із HTML-атрибутом в якості ключа. Цей атрибут може також бути встановлений прямо всередині шаблону:

1
2
3

{{ form_label(form.name, 'Your name', {
    'label_attr': {'class': 'CUSTOM_LABEL_CLASS'}
}) }}

1
2
3
4
5

echo $view['form']->label(
    $form['name'],
    'Your name',
    ['label_attr' => ['class' => 'CUSTOM_LABEL_CLASS']]
);

Дата оновлення перекладу 2025-02-24

label_html

тип: boolean за замовчуванням: false

За замовчуванням, зміст опції label екранується перед відображенням у шаблоні. Встановіть для цієї опції значення true, щоб не екранувати її, що може бути корисно, коли ярлик містить HTML-елементи.

Дата оновлення перекладу 2025-02-24

label_format

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

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

Якщо ви використовуєте повідомлення перекладів ключових слів як ярлики, то у вас часто буде кілька повідомлень із ключовим словом для одного й того самого ярлика (наприклад, profile_address_street, invoice_address_street). Це тому, що ярлик будується для кожного "шляху" до поля. Щоб уникнути повтору повідомлень ключових слів, ви можете конфігурувати формат ярлика як статичне значення, наприклад:

1
2
3
4
5
6
7
8

// ...
$profileFormBuilder->add('address', AddressType::class, [
    'label_format' => 'form.address.%name%',
]);

$invoiceFormBuilder->add('invoice', AddressType::class, [
    'label_format' => 'form.address.%name%',
]);

Ця опція успадковується дочірніми типами. З використанням вищенаписаного коду, ярлик поля street обох форм буде використовувати повідомлення з ключовим словом form.address.street.

У форматі ярлика доступні дві змінні:

%id%

Унікальний ідентифікатор для поля, що складається з повного шляху до поля та імені поля (наприклад, profile_address_street);

%name%

Ім'я поля (наприклад, street).

Значення за замовчуванням (null) призводить до `«людської» версії імені поля.

Дата оновлення перекладу 2025-02-24

mapped

тип: boolean за замовчуванням: true

Якщо ви хочете, щоб поле було проігноровано при читанні або записі в нього обʼєкта, ви можете встановити опцію mapped як false.

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

required

тип: boolean за замовчуванням: true

Якщо значення true, буде відображено обов'язковий атрибут HTML5. Відповідний label також буде відображено з класом required.

Це поверхнево і не залежить від валідації. У кращому випадку, якщо ви дозволите Symfony вгадати тип вашого поля, то значення цієї опції буде вгадано з вашої інформації валідації.

Дата оновлення перекладу 2025-02-24

row_attr

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

Асоціативний масив атрибутів HTML, що додаються до елементу, який використовується для відображення рядка типу форми :

1
2
3

$builder->add('body', TextareaType::class, [
    'row_attr' => ['class' => 'text-editor', 'id' => '...'],
]);