Формы в Symfony: рабочие приёмы и их цена

Symfony Form Component умеет всё сразу: собирает данные из запроса, валидирует их, маппит на объект и рендерит HTML. Проблема начинается, когда одну и ту же форму нужно отдать и в Twig-шаблон, и в JSON-эндпоинт, когда в форме появляется коллекция вложенных сущностей, а рендер 40 полей начинает съедать заметную часть времени ответа. Ниже — приёмы, которые применяют на боевых проектах Symfony 6.4 и 7.x, и цена каждого из них.

Form Type всегда отдельным классом, а не инлайном

В контроллере можно собрать форму через $this->createFormBuilder(). Для одного поля поиска это нормально. Как только форма переиспользуется хотя бы в двух местах или растёт больше трёх полей — выносите в отдельный класс, наследник AbstractType.

// src/Form/ArticleType.php — Symfony 7.x
namespace App\Form;

use App\Entity\Article;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\Extension\Core\Type\TextareaType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;

class ArticleType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            ->add('title', TextType::class)
            ->add('body', TextareaType::class);
    }

    public function configureOptions(OptionsResolver $resolver): void
    {
        // Привязка формы к классу сущности — валидация возьмёт
        // ограничения из атрибутов Article
        $resolver->setDefaults(['data_class' => Article::class]);
    }
}

Выигрыш: форму можно протестировать в изоляции, переиспользовать во вложенных формах и подменить опции через createForm(ArticleType::class, $article, $options). Цена: лишний файл там, где формы одноразовые.

Валидацию держите на сущности, а не в форме

Соблазн — навешать constraints прямо в ->add(). Так делать стоит только для полей, которых нет в сущности (галочка «я согласен», повтор пароля). Все ограничения, относящиеся к данным модели, живут атрибутами на самой сущности.

// src/Entity/Article.php
use Symfony\Component\Validator\Constraints as Assert;

class Article
{
    #[Assert\NotBlank]
    #[Assert\Length(min: 5, max: 200)]
    private string $title = '';
}

Причина одна: одна сущность может редактироваться из нескольких форм, из консольной команды и через API. Если правила размазаны по формам, часть путей записи их обойдёт. На сущности правило действует всегда.

Форма — это транспорт и UI. Правила целостности данных принадлежат модели. Как только валидация переезжает в Form Type, вы получаете сущность, которую нельзя безопасно сохранить в обход формы.

Валидационные группы вместо десяти похожих Form Type

Регистрация требует пароль, редактирование профиля — нет. Плодить RegistrationType и ProfileType с дублирующими полями — путь к рассинхрону. Вместо этого — группы валидации.

#[Assert\NotBlank(groups: ['registration'])]
#[Assert\Length(min: 8, groups: ['registration'])]
private ?string $plainPassword = null;

В опциях формы указываете, какие группы применить:

$resolver->setDefaults([
    'validation_groups' => ['Default', 'registration'],
]);

Группу можно вычислить и динамически через callback, если она зависит от состояния объекта. Цена подхода — валидационные группы неочевидны при чтении сущности: чтобы понять, когда сработает ограничение, нужно найти форму, которая его включает.

Формы и API: не пытайтесь скрестить

Частая ошибка — прогонять JSON-запрос через тот же Form Type, что и HTML-форму. Form Component заточен под application/x-www-form-urlencoded и структуру имён вида article[title]. С JSON он работает, но с оговорками: нужно вручную декодировать тело и передать массив в submit().

// В контроллере API
$data = json_decode($request->getContent(), true);
$form = $this->createForm(ArticleType::class, $article);
// Второй аргумент false — частичное обновление (PATCH):
// поля, которых нет в запросе, не сбрасываются
$form->submit($data, false);

if (!$form->isValid()) {
    // собрать ошибки в структуру для JSON-ответа
}

Для чистого REST-API чаще берут symfony/serializer вместе с валидатором напрямую или API Platform — они изначально работают с JSON и не тащат HTML-рендер. Form Component держите для страниц, которые рендерит сервер.

Коллекции: самая болезненная часть

CollectionType для «списка тегов» или «строк заказа» работает, но два флага решают почти все проблемы. by_reference => false заставляет форму вызывать сеттеры/adder-методы, иначе изменения в коллекции могут не примениться. allow_delete => true удаляет из коллекции элементы, которых нет в отправленных данных.

$builder->add('items', CollectionType::class, [
    'entry_type'   => OrderItemType::class,
    'allow_add'    => true,
    'allow_delete' => true,
    'by_reference' => false, // вызывать addItem()/removeItem()
]);

Динамическое добавление строк на клиенте Symfony сам не делает — отдаёт data-prototype в HTML, а вставку новой строки пишете на JS. Учтите: без orphanRemoval: true в связи Doctrine удалённый из формы элемент отвяжется от родителя, но останется в БД висящей записью.

Когда что выбирать

Что ломается на практике

• CSRF-токен и AJAX. Если отправляете форму через fetch, токен должен уйти в теле запроса. Отключать защиту через 'csrf_protection' => false для удобства — прямая дыра.
• EntityType и N+1. Выпадающий список сущностей грузит все записи в память. На таблице в десятки тысяч строк это убивает страницу — используйте query_builder с фильтром или замените на автокомплит с подгрузкой.
• Медленный рендер большой формы. Каждое поле — отдельный Twig-блок. Сорок полей с кастомными темами дают заметный оверхед. Смотрите профайлер Symfony: вкладка Twig покажет число рендеров блоков.
• handleRequest на GET. Для форм поиска задавайте 'method' => 'GET', иначе handleRequest() проигнорирует данные из query-строки.

Что настроить дальше

Включите профайлер и откройте вкладку Forms на странице с тяжёлой формой — она показывает переданные опции, применённые трансформеры и ошибки по каждому полю. Это быстрее, чем гадать, почему поле не мапится. Если форма переиспользуется в API — вынесите валидацию в группы и прогоните её через ValidatorInterface напрямую, не создавая форму. А тему инвалидации кеша Twig-шаблонов форм здесь не трогаем — это отдельный разговор про прод.