Работа с формами в symfony

Веб-разработка
23 сентября 2022
16 мин чтения
Работа с формами в symfony

Прежде чем приступить к прочтению, хочется обозначить предметно-ориентированное понятие формы. Это важно, поскольку при разработке программного обеспечения мы придерживаемся принципов предметно-ориентированного проектирования.

Содержание

Предметно-ориентированное представление формы

Для простоты понимания представим, что форма, это объект пользовательского интерфейса программы, который требует ввода данных от пользователя. Есть разные виды форм, в том числе те, которые не требуют заполнения полей, но требуют подтверждения действий.

Проще понять на примерах:

  1. Поле поисковой строки с кнопкой «Найти» в поисковых системах — это форма
  2. Поле логин и пароль с кнопкой «Войти» в мобильном приложении — это форма
  3. Поле с требованием ввести «E-mail адрес» на сайте с кнопкой «Подписаться» — это тоже форма
  4. Вопрос с выбором ответа в «системе управления обучением» — это тоже форма
  5. Уведомление о разрешении какого либо действия с двумя кнопками «Разрешить» или «Запретить» — это форма , которую называют диалоговым окном

В реальном мире формой можно назвать любое письменное заявление, которое мы заполняем и передаём куда либо. Например «согласие на обработку персональных данных» или «письмо деду морозу» =)

Представление формы в исходном коде

Компонент форм в Symfony считается одним из самых сложных. На самом деле это не так. Он предоставляет инструменты для описания полей, преобразования данных, проверки введённых значений и отображения ошибок. Разберём эти возможности на практическом примере.

Формы в Symfony можно создавать двумя основными способами: через отдельный класс типа формы — Form Type — или непосредственно в контроллере с помощью FormBuilder.

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

Подробнее в документации Symfony:

Для удобства пояснения, представим что мы выполняем реальное задание от заказчка.

Заказчик запросил создание «формы обратной связи».

Наш менеджер по проектам уточнил у заказчика детали и сформулировал требования для отдела разработки. Требования: в форме обратной связи должны быть 3 поля: Имя, E-mail, Текст сообщения и после отправки этой формы заказчику на его электронный адрес должно уходить письмо с данными из этой формы.

Далее менджер проекта попросил верстальщика сделать html форму и передал эту форму программисту. Программист начал делать код и в первые минуты его код выглядит так.

Работа с формами в symfony - изображение 1

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

Работа с формами в symfony - изображение 2

Код на скриншоте позволяет вывести форму средствами Symfony, но приём и обработка данных ещё не реализованы. К этому вернёмся позже.

Сейчас обратим внимание на Twig-шаблон form.html.twig. Функция form_widget() выводит виджет поля, но сама по себе не выводит его подпись и ошибки валидации. Функция form_row() формирует строку поля, включая подпись, виджет, ошибки и другую предусмотренную темой оформления разметку.

Для вывода целой формы можно использовать form(), а для более точного управления разметкой — form_start(), form_row(), form_errors(), form_widget() и form_end().

Подробнее: настройка отображения форм в Twig.

Вдруг менеджер проекта сообщил что заказчик требует форму обратной связи ещё на одной странице, но дизайн формы должен быть одинаковым на всех страницах!

Программист добавляет ещё одну страницу и ещё один шаблон и реализует обработку данных из формы. И получает такой код.

Работа с формами в symfony - изображение 3

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

Программист меняет код и теперь использует единый тип формы App\Form\FeedbackForm.

Работа с формами в symfony - изображение 4

Теперь даже если форма будет размещена на 25 страницах, её поля и базовые настройки можно будет изменять в одном классе. Внешнее оформление при этом определяется Twig-шаблонами и темами форм.

Отдельные типы форм также позволяют расширять их поведение через Form Type Extensions и создавать вложенные формы.

Это особенно полезно в больших проектах, где одни и те же поля и правила обработки используются в разных разделах сайта.

Теперь займёмся обработкой данных. Если при создании формы не передать объект данных и не задать data_class, составная форма обычно возвращает ассоциативный массив.

При использовании createFormBuilder() исходные данные передаются первым аргументом, при использовании createForm() — вторым. Если форма связана с объектом через data_class, результатом getData() будет объект соответствующего класса.

Пример, в данном случае данные из формы придут в массиве.

Работа с формами в symfony - изображение 5

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

Работа с формами в symfony - изображение 6

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

Работа с формами в symfony - изображение 7

Теперь при открытии формы в поле сообщения будет находиться подготовленный текст. Но если форма используется на 25 страницах, передавать одинаковые данные из каждого контроллера неудобно.

Поэтому оптимизируем код. В классе App\Form\FeedbackForm можно задать значение по умолчанию для отдельного поля или вынести шаблон сообщения в собственную опцию формы через configureOptions().

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

Вот что вышло:

Работа с формами в symfony - изображение 8

Внезапно, заказчик сообщил что отправлять результаты форм ему на почту нужно через его собственную библиотеку! А код отправки данных этой библиотеки принимает на вход только объект с методом getEmailMessage().

Не проблема. Создадим класс данных App\Form\FeedbackFormData со свойствами name, email и message, а также методом getEmailMessage(), который требуется библиотеке заказчика.

В классе App\Form\FeedbackForm укажем опцию data_class => FeedbackFormData::class. Symfony будет связывать поля формы со свойствами объекта.

Для шаблона сообщения предусмотрим значение по умолчанию в объекте данных. Это позволит избежать случайного перезаписывания уже введённого сообщения.

Работа с формами в symfony - изображение 9

В современных версиях 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 - изображение 10

Подробнее о настройке типов форм и собственных опций читайте в документации Symfony.

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

Вдруг заказчик сообщил что на одной из страниц шаблон будет другим!

Сразу подчеркнём, что способов реализации такой задачи несколько. Один из наиболее простых — передавать в форму собственную опцию message_template, значение которой зависит от страницы.

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

Работа с формами в symfony - изображение 11

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

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

Работа с формами в symfony - изображение 12

Для надёжности лучше проверять не сам 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-наследования классов и позволяет использовать настройки и поля родительского типа.

Вот реализация способом наследования формы.

Работа с формами в symfony - изображение 13

В контроллере заменили тип формы на FeedbackForm2. Новый тип расширяет FeedbackForm через метод getParent() и изменяет настройки поля message, подставляя специальный шаблон по требованию заказчика.

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

Если требуется менять только начальные данные, лучше сохранить определение поля в родительском типе и использовать опции или объект данных.

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

Работа с формами в symfony - изображение 14

При таком подходе, если в FeedbackForm изменится тип поля — например, с TextareaType на TextType, — эти изменения сохранятся и для формы с другим шаблоном сообщения. Нам не придётся дублировать настройки поля.

Теперь переходим к валидации данных. По умолчанию у многих стандартных полей Symfony опция required включена. Она влияет на HTML-разметку и поведение браузера, но сама по себе не гарантирует проверку данных на сервере.

Отключим required и проверим отправку формы. Для настоящей серверной проверки понадобятся ограничения валидации.

Работа с формами в symfony - изображение 15

Форма может быть отправлена без заполнения обязательных по требованиям заказчика полей. В таком случае в данные попадут пустые значения или null — в зависимости от типа поля и его настроек.

Нужно гарантировать, что имя и E-mail проверяются на сервере независимо от поведения браузера.

Добавляем валидацию. В Symfony её можно настроить разными способами: непосредственно через опцию constraints у поля формы или через ограничения, объявленные в классе данных.

Для проверки обязательности используется Assert\NotBlank, а для проверки формата электронного адреса — Assert\Email.

Одна только проверка Email не заменяет NotBlank: пустое значение необходимо запрещать отдельно, если поле действительно обязательное.

Способ № 1 — добавляем ограничения через опцию constraints непосредственно при определении полей формы.

Работа с формами в symfony - изображение 16

Изменения внесены в класс формы и 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 должен самостоятельно обрабатывать ошибки формата, аутентификацию и ответы клиенту.

Работа с формами в symfony - изображение 17

Теперь данные, полученные из мобильного приложения в JSON, и данные обычной веб-формы могут проверяться одними и теми же ограничениями объекта FeedbackFormData.

Для JSON API необходимо отдельно учитывать отсутствие обязательных свойств, неверные типы значений и ошибки десериализации. После успешной проверки оба обработчика могут вызывать один сервис, отвечающий за отправку сообщения.

Вдруг заказчик сообщил, что хочет скрывать поле «Сообщение» до тех пор, пока пользователь не заполнит поля «Имя» и «E-mail». После их заполнения поле должно появиться и стать обязательным.

Эту задачу удобно разделить на две части. На клиенте JavaScript управляет видимостью поля «Сообщение» при вводе имени и E-mail. На сервере Symfony проверяет, какие поля должны присутствовать и какие значения допустимы.

Для динамического изменения состава формы можно использовать события Form Component — например, PRE_SET_DATA и PRE_SUBMIT. Но события Symfony сами по себе не обеспечивают мгновенного появления поля в браузере: для этого необходим клиентский код или дополнительный запрос к серверу.

Если сервер добавляет поле только при выполнении условия, Twig-шаблон должен проверять его существование перед выводом.

Работа с формами в symfony - изображение 18

Подробнее об изменении структуры формы и событиях Form Component читайте в документации Symfony:

С нами снова связался заказчик и попросил подключить вендорный код (библиотеку) для аналитики электронных адресов. При этом код его библиотеки требует на вход объект с методами getDomain(), getEmail().

Воспользуемся механизмом преобразования данных. Создадим объект CustomerEmail с методами getDomain() и getEmail(), которые ожидает библиотека заказчика.

Затем добавим к полю email преобразователь через addModelTransformer(). Он позволит представить адрес электронной почты в модели как объект CustomerEmail, а пользователю показывать обычную строку.

При этом необходимо согласовать тип свойства email в FeedbackFormData, правила его валидации и преобразование данных. Если свойство раньше имело тип ?string, после введения объектной модели его тип потребуется изменить.

Код будет выглядить так:

Работа с формами в symfony - изображение 19

Моменты на которые нужно обратить внимание:

  • 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:

Работа с формами в symfony - изображение 20

На что нужно обратить внимание:

  • 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 в среде разработки можно просматривать структуру форм, переданные данные, ошибки валидации и другую диагностическую информацию.

Для рабочих серверов такие инструменты отладки не должны быть доступны публично.

Работа с формами в symfony - изображение 21

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

Редакция NJ Soft
Редакция NJ Soft
Редактор блога

Поделиться:

Нужна разработка или поддержка проекта?

Разрабатываем веб-сервисы и мобильные приложения, дорабатываем и поддерживаем существующие проекты. Расскажите о задаче — предложим решение.