Прежде чем приступить к прочтению, хочется обозначить предметно-ориентированное понятие формы. Это важно, поскольку при разработке программного обеспечения мы придерживаемся принципов предметно-ориентированного проектирования.
Содержание
- Предметно-ориентированное представление формы
- Проще понять на примерах:
- Представление формы в исходном коде
- Итоги
Предметно-ориентированное представление формы
Для простоты понимания представим, что форма, это объект пользовательского интерфейса программы, который требует ввода данных от пользователя. Есть разные виды форм, в том числе те, которые не требуют заполнения полей, но требуют подтверждения действий.
Проще понять на примерах:
- Поле поисковой строки с кнопкой «Найти» в поисковых системах — это форма
- Поле логин и пароль с кнопкой «Войти» в мобильном приложении — это форма
- Поле с требованием ввести «E-mail адрес» на сайте с кнопкой «Подписаться» — это тоже форма
- Вопрос с выбором ответа в «системе управления обучением» — это тоже форма
- Уведомление о разрешении какого либо действия с двумя кнопками «Разрешить» или «Запретить» — это форма , которую называют диалоговым окном
В реальном мире формой можно назвать любое письменное заявление, которое мы заполняем и передаём куда либо. Например «согласие на обработку персональных данных» или «письмо деду морозу» =)
Представление формы в исходном коде
Компонент форм в Symfony считается одним из самых сложных. На самом деле это не так. Он предоставляет инструменты для описания полей, преобразования данных, проверки введённых значений и отображения ошибок. Разберём эти возможности на практическом примере.
Формы в Symfony можно создавать двумя основными способами: через отдельный класс типа формы — Form Type — или непосредственно в контроллере с помощью FormBuilder.
Первый вариант удобен, когда форма используется на нескольких страницах или требует отдельной настройки. Второй подходит для простых случаев и быстрого прототипирования.
Подробнее в документации Symfony:
Для удобства пояснения, представим что мы выполняем реальное задание от заказчка.
Заказчик запросил создание «формы обратной связи».
Наш менеджер по проектам уточнил у заказчика детали и сформулировал требования для отдела разработки. Требования: в форме обратной связи должны быть 3 поля: Имя, E-mail, Текст сообщения и после отправки этой формы заказчику на его электронный адрес должно уходить письмо с данными из этой формы.
Далее менджер проекта попросил верстальщика сделать html форму и передал эту форму программисту. Программист начал делать код и в первые минуты его код выглядит так.

Теперь надо интегрировать эту форму в symfony. Делаем напрямую через FormBuilder.

Код на скриншоте позволяет вывести форму средствами Symfony, но приём и обработка данных ещё не реализованы. К этому вернёмся позже.
Сейчас обратим внимание на Twig-шаблон form.html.twig. Функция form_widget() выводит виджет поля, но сама по себе не выводит его подпись и ошибки валидации. Функция form_row() формирует строку поля, включая подпись, виджет, ошибки и другую предусмотренную темой оформления разметку.
Для вывода целой формы можно использовать form(), а для более точного управления разметкой — form_start(), form_row(), form_errors(), form_widget() и form_end().
Подробнее: настройка отображения форм в Twig.
Вдруг менеджер проекта сообщил что заказчик требует форму обратной связи ещё на одной странице, но дизайн формы должен быть одинаковым на всех страницах!
Программист добавляет ещё одну страницу и ещё один шаблон и реализует обработку данных из формы. И получает такой код.

Менеджер сообщил, что заказчик ещё не знает как точно будут называться поля формы, например вместо поля «Имя» заказчик планирует переименовать это поле «ФИО», но не сейчас. А ещё заказчик планирует разместить такие формы на всех 25 страницах его сайта!
Программист меняет код и теперь использует единый тип формы App\Form\FeedbackForm.

Теперь даже если форма будет размещена на 25 страницах, её поля и базовые настройки можно будет изменять в одном классе. Внешнее оформление при этом определяется Twig-шаблонами и темами форм.
Отдельные типы форм также позволяют расширять их поведение через Form Type Extensions и создавать вложенные формы.
Это особенно полезно в больших проектах, где одни и те же поля и правила обработки используются в разных разделах сайта.
Теперь займёмся обработкой данных. Если при создании формы не передать объект данных и не задать data_class, составная форма обычно возвращает ассоциативный массив.
При использовании createFormBuilder() исходные данные передаются первым аргументом, при использовании createForm() — вторым. Если форма связана с объектом через data_class, результатом getData() будет объект соответствующего класса.
Пример, в данном случае данные из формы придут в массиве.

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

Как поступить? Очень просто. Подготовим массив $formData и укажем значение для поля message до создания формы. Symfony использует переданные данные при первоначальном заполнении полей.

Теперь при открытии формы в поле сообщения будет находиться подготовленный текст. Но если форма используется на 25 страницах, передавать одинаковые данные из каждого контроллера неудобно.
Поэтому оптимизируем код. В классе App\Form\FeedbackForm можно задать значение по умолчанию для отдельного поля или вынести шаблон сообщения в собственную опцию формы через configureOptions().
Важно учитывать различие: опция data отдельного поля задаёт его начальное значение и может переопределить значение из связанного объекта. Поэтому для формы, редактирующей уже существующие данные, безопаснее заполнять объект до вызова createForm().
Вот что вышло:

Внезапно, заказчик сообщил что отправлять результаты форм ему на почту нужно через его собственную библиотеку! А код отправки данных этой библиотеки принимает на вход только объект с методом getEmailMessage().
Не проблема. Создадим класс данных App\Form\FeedbackFormData со свойствами name, email и message, а также методом getEmailMessage(), который требуется библиотеке заказчика.
В классе App\Form\FeedbackForm укажем опцию data_class => FeedbackFormData::class. Symfony будет связывать поля формы со свойствами объекта.
Для шаблона сообщения предусмотрим значение по умолчанию в объекте данных. Это позволит избежать случайного перезаписывания уже введённого сообщения.

В современных версиях Symfony для валидации объектов используются PHP-атрибуты. Например, класс данных формы можно описать следующим образом:
<?php
namespace App\Form;
use Symfony\Component\Validator\Constraints as Assert;
final class FeedbackFormData
{
#[Assert\NotBlank(message: 'Укажите имя.')]
public ?string $name = null;
#[Assert\NotBlank(message: 'Укажите E-mail.')]
#[Assert\Email(message: 'Укажите корректный E-mail.')]
public ?string $email = null;
#[Assert\NotBlank(message: 'Введите сообщение.')]
public ?string $message = null;
public function getEmailMessage(): string
{
return sprintf(
"Имя: %s\nE-mail: %s\nСообщение: %s",
$this->name ?? '',
$this->email ?? '',
$this->message ?? ''
);
}
}
А сам тип формы:
<?php
namespace App\Form;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\EmailType;
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;
final class FeedbackForm extends AbstractType
{
public function buildForm(
FormBuilderInterface $builder,
array $options
): void {
$builder
->add('name', TextType::class, [
'label' => 'Имя',
])
->add('email', EmailType::class, [
'label' => 'E-mail',
])
->add('message', TextareaType::class, [
'label' => 'Сообщение',
]);
}
public function configureOptions(OptionsResolver $resolver): void
{
$resolver->setDefaults([
'data_class' => FeedbackFormData::class,
]);
}
}
Пример рассчитан на PHP 8 с поддержкой атрибутов и актуальный компонент Symfony Form. Для проверки ограничений необходим пакет symfony/validator.
Метод configureOptions() позволяет объявлять и настраивать опции типа формы. Через него можно задать data_class, значения по умолчанию, допустимые типы пользовательских опций и другие параметры.
Эти настройки доступны в buildForm() через массив $options.
При этом важно различать значения по умолчанию и параметры конкретного экземпляра: настройки из configureOptions() могут быть переопределены при вызове createForm(), если соответствующая опция допускает изменение.
Например, можно задать собственную опцию message_template со значением по умолчанию, а на отдельной странице передать для неё другой текст.

Подробнее о настройке типов форм и собственных опций читайте в документации Symfony.
Теперь после корректной отправки формы метод $form->getData() возвращает объект FeedbackFormData со значениями, введёнными пользователем. Его можно передать в библиотеку заказчика, предварительно убедившись, что форма отправлена и прошла валидацию.
Вдруг заказчик сообщил что на одной из страниц шаблон будет другим!
Сразу подчеркнём, что способов реализации такой задачи несколько. Один из наиболее простых — передавать в форму собственную опцию message_template, значение которой зависит от страницы.
При этом шаблон сообщения лучше задавать при создании нового объекта данных, чтобы не перезаписывать сообщение, уже введённое пользователем.

Другой способ решить задачу без изменения логики контроллера — использовать внедрение зависимостей. Например, можно передать в тип формы сервис, определяющий шаблон сообщения по текущему маршруту или другим параметрам приложения.
Но здесь есть важный нюанс: типы форм в Symfony обычно являются сервисами. Поэтому не следует сохранять данные текущего запроса в изменяемых свойствах типа формы. Лучше получать необходимые значения при построении формы и передавать их через опции.

Для надёжности лучше проверять не сам URL, а имя маршрута. Тогда изменение адреса страницы не нарушит выбор шаблона сообщения.
В современных версиях Symfony маршруты в PHP-контроллерах объявляются с помощью атрибутов #[Route] из пространства имён Symfony\Component\Routing\Attribute.
Например:
<?php
namespace App\Controller;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
final class FeedbackPageController extends AbstractController
{
#[Route('/feedback', name: 'app_feedback', methods: ['GET'])]
public function index(): Response
{
return $this->render('feedback/index.html.twig');
}
}
В Symfony 6.3 поддержка Doctrine-аннотаций для маршрутизации была объявлена устаревшей, а в Symfony 7.0 удалена. Для нового кода следует использовать атрибуты PHP.
Источник: документация маршрутизации Symfony.
Есть ещё один способ, который заслуживает внимания: расширение типа формы. Для этого можно создать новый класс формы и определить метод getParent(), возвращающий родительский тип.
Это механизм наследования типов форм Symfony. Он отличается от обычного PHP-наследования классов и позволяет использовать настройки и поля родительского типа.
Вот реализация способом наследования формы.

В контроллере заменили тип формы на FeedbackForm2. Новый тип расширяет FeedbackForm через метод getParent() и изменяет настройки поля message, подставляя специальный шаблон по требованию заказчика.
Но у такого подхода есть недостаток. Если повторно добавить поле с тем же именем и явно указать его тип, можно случайно зафиксировать этот тип в дочерней форме. Тогда изменения родительской формы не будут автоматически учитываться.
Если требуется менять только начальные данные, лучше сохранить определение поля в родительском типе и использовать опции или объект данных.
Поэтому предпочтительнее изменять начальные данные без повторного объявления типа поля. Например, использовать отдельный объект FeedbackFormData с нужным шаблоном сообщения или передать собственную опцию при создании формы.

При таком подходе, если в FeedbackForm изменится тип поля — например, с TextareaType на TextType, — эти изменения сохранятся и для формы с другим шаблоном сообщения. Нам не придётся дублировать настройки поля.
Теперь переходим к валидации данных. По умолчанию у многих стандартных полей Symfony опция required включена. Она влияет на HTML-разметку и поведение браузера, но сама по себе не гарантирует проверку данных на сервере.
Отключим required и проверим отправку формы. Для настоящей серверной проверки понадобятся ограничения валидации.

Форма может быть отправлена без заполнения обязательных по требованиям заказчика полей. В таком случае в данные попадут пустые значения или null — в зависимости от типа поля и его настроек.
Нужно гарантировать, что имя и E-mail проверяются на сервере независимо от поведения браузера.
Добавляем валидацию. В Symfony её можно настроить разными способами: непосредственно через опцию constraints у поля формы или через ограничения, объявленные в классе данных.
Для проверки обязательности используется Assert\NotBlank, а для проверки формата электронного адреса — Assert\Email.
Одна только проверка Email не заменяет NotBlank: пустое значение необходимо запрещать отдельно, если поле действительно обязательное.
Способ № 1 — добавляем ограничения через опцию constraints непосредственно при определении полей формы.

Изменения внесены в класс формы и Twig-шаблон. При использовании только form_widget() сообщения об ошибках автоматически рядом с полем не появятся.
Для вывода ошибок можно использовать form_row(), отдельный вызов form_errors() или стандартную функцию form(), которая отображает форму целиком с учётом выбранной темы оформления.
Например:
{{ form_start(form) }}
{{ form_row(form.name) }}
{{ form_row(form.email) }}
{{ form_row(form.message) }}
<button type="submit">Отправить</button>
{{ form_end(form) }}
Symfony также автоматически включает защиту CSRF для обычных форм при соответствующей настройке компонента. Для JSON API механизм защиты и аутентификации следует проектировать отдельно.
Вдруг заказчик сообщает что у него есть мобильное приложение и оттуда тоже отправляется такая форма, но данные от пользователя приходят в json формате и на другой специальный URL. При этом логика обработки этих данных должна быть одинаковая как для формы, так и для мобильного приложения.
И с этим тоже нет сложностей: у нас уже есть класс данных FeedbackFormData. Вынесем ограничения валидации в него, чтобы они не зависели от способа получения данных.
Для мобильного приложения можно использовать компонент Serializer для десериализации JSON в объект FeedbackFormData, а затем проверить объект через Validator.
Так мы получим общие правила валидации, хотя сами способы обработки HTTP-запросов останутся разными.
Добавим отдельный обработчик JSON-запроса и разместим ограничения в классе данных формы. Это позволит использовать один набор правил валидации для веб-интерфейса и мобильного приложения.
Важно: одинаковые ограничения не означают полностью одинаковый жизненный цикл обработки. Веб-форма дополнительно использует механизм отправки формы, преобразования данных и проверки CSRF, а JSON API должен самостоятельно обрабатывать ошибки формата, аутентификацию и ответы клиенту.

Теперь данные, полученные из мобильного приложения в JSON, и данные обычной веб-формы могут проверяться одними и теми же ограничениями объекта FeedbackFormData.
Для JSON API необходимо отдельно учитывать отсутствие обязательных свойств, неверные типы значений и ошибки десериализации. После успешной проверки оба обработчика могут вызывать один сервис, отвечающий за отправку сообщения.
Вдруг заказчик сообщил, что хочет скрывать поле «Сообщение» до тех пор, пока пользователь не заполнит поля «Имя» и «E-mail». После их заполнения поле должно появиться и стать обязательным.
Эту задачу удобно разделить на две части. На клиенте JavaScript управляет видимостью поля «Сообщение» при вводе имени и E-mail. На сервере Symfony проверяет, какие поля должны присутствовать и какие значения допустимы.
Для динамического изменения состава формы можно использовать события Form Component — например, PRE_SET_DATA и PRE_SUBMIT. Но события Symfony сами по себе не обеспечивают мгновенного появления поля в браузере: для этого необходим клиентский код или дополнительный запрос к серверу.
Если сервер добавляет поле только при выполнении условия, Twig-шаблон должен проверять его существование перед выводом.

Подробнее об изменении структуры формы и событиях Form Component читайте в документации Symfony:
С нами снова связался заказчик и попросил подключить вендорный код (библиотеку) для аналитики электронных адресов. При этом код его библиотеки требует на вход объект с методами getDomain(), getEmail().
Воспользуемся механизмом преобразования данных. Создадим объект CustomerEmail с методами getDomain() и getEmail(), которые ожидает библиотека заказчика.
Затем добавим к полю email преобразователь через addModelTransformer(). Он позволит представить адрес электронной почты в модели как объект CustomerEmail, а пользователю показывать обычную строку.
При этом необходимо согласовать тип свойства email в FeedbackFormData, правила его валидации и преобразование данных. Если свойство раньше имело тип ?string, после введения объектной модели его тип потребуется изменить.
Код будет выглядить так:

Моменты на которые нужно обратить внимание:
addModelTransformer()добавляет преобразователь между модельным представлением данных и нормализованным представлением поля. Для преобразования строки E-mail в объектCustomerEmailи обратно можно реализоватьDataTransformerInterfaceс методамиtransform()иreverseTransform().- В классе данных
FeedbackFormDataвалидируется свойствоemail, а не адресinfo@njsoft.dev. Последний является адресом электронной почты компании и не должен использоваться вместо имени свойства. - Если свойство
emailсодержит объектCustomerEmail, стандартный валидаторAssert\Emailможно применять только с учётом преобразования объекта в строку. Метод__toString()позволяет получить строковое представление адреса, но для более явной модели можно создать собственное ограничение валидации или проверять строку до преобразования. - При использовании объектной модели следует убедиться, что остальные методы класса данных, включая
getEmailMessage(), корректно работают сCustomerEmail. - Если используется Transformer, ошибки преобразования необходимо обрабатывать как ошибки данных формы, а не как необработанные исключения.
Подробнее о преобразовании данных в формах читайте в документации Symfony: How to Use Data Transformers.
Заказчик сказал нам большое спасибо и сказал что заплатит много-много денег, если мы доделаем ещё одну маленьку фичу: нужно возле поля E-mail выводить картинку котика, которая находится по ссылке /customerwebsite/kotik.png
И это легко реализовать, потому что Symfony позволяет создавать собственные типы полей и Twig-шаблоны для их отображения.
Создадим тип поля, расширяющий EmailType. Для этого используем методы getParent(), getBlockPrefix(), buildView() и configureOptions().
С помощью configureOptions() добавим собственную опцию image_url, через buildView() передадим её в Twig, а через getBlockPrefix() определим имя блока шаблона.
Затем зарегистрируем шаблон темы формы в config/packages/twig.yaml.
Подробнее: создание собственного типа поля в Symfony.
При выводе адреса изображения в Twig следует использовать обычное экранирование атрибутов. Если адрес формируется из пользовательских данных, необходимо отдельно контролировать допустимые значения URL.
Теперь форма выводит картинку рядом с полем E-mail:

На что нужно обратить внимание:
app_form_types.html.twigзарегистрирован как тема форм через настройкуform_themesвconfig/packages/twig.yaml.- Имя Twig-блока
app_email_with_image_widgetформируется из значенияgetBlockPrefix()и суффикса_widget. configureOptions()позволяет объявить собственную опциюimage_url. Её тип можно ограничить черезsetAllowedTypes(), чтобы Symfony отклонял некорректную конфигурацию поля.buildView()передаёт значениеimage_urlв переменные представления, доступные Twig-шаблону.getParent()возвращаетEmailType::class, поскольку мы расширяем стандартное поле электронного адреса, добавляя к нему изображение.- Если необходимо сохранить стандартное поведение и оформление родительского поля, в собственном Twig-блоке можно использовать механизм наследования блоков темы формы.
Итоги
Компонент форм Symfony — полезный инструмент, который помогает создавать и поддерживать код для ввода, проверки и обработки данных. С его помощью можно строить как простые формы обратной связи, так и сложные интерфейсы с вложенными полями, динамической структурой и собственными типами данных.
Главное преимущество — возможность отделить описание формы и правила валидации от конкретной страницы, на которой она используется.
Компонент интегрирован с инструментами отладки Symfony. При установленном и включённом Web Profiler в среде разработки можно просматривать структуру форм, переданные данные, ошибки валидации и другую диагностическую информацию.
Для рабочих серверов такие инструменты отладки не должны быть доступны публично.

Рекомендуем всем программистам освоить этот замечательный инструмент!





