Symfony form add error

Дата обновления перевода: 2023-01-20

Компонент Form

Компонент Form позволяет вам с лёгкостью создавать, обрабатывать и использовать
формы повторно.

Копомнент Form — это инструмент, призванный помочь вам решить проблему разрешения
конечным пользователям взаимодействовать и изменять данные в вашем приложении. И
хотя традиционно это делалось через HTML формы, компонент фокусируется на обработке
данных к и от вашего клиента и приложения, будь эти данные из обычной записи формы
или из API.

Установка

Note

Если вы устанавливаете этот компонент вне приложения Symfony, вам нужно
подключить файл vendor/autoload.php в вашем коде для включения механизма
автозагрузки классов, предоставляемых Composer. Детальнее читайте в
этой статье.

Конфигурация

See also

Эта статья объясняет как использовать функции Form как независимого
компонента в любом приложении PHP. Прочитайте статью Формы
для понимания как использовать его в приложениях Symfony.

В Symfony, формы представлены объектыми, а эти объекты строятся с использованием
фабрики форм. Построить фабрику форм просто с помощью метода Forms::createFormFactory:

Эта фабрика может уже быть использована для создания базовых форм, но ей
не хватает поддержки для очень важных функций:

• Обработка запросов: Поддержка обработки запросов и загрузки файлов;
• CSRF-защита: Поддержка защиты от атак межсайтовой подделки запросов
  (CSRF);
• Шаблонизация: Интеграция с уровнем шаблонизации, который позволяет вам
  использовать фрагменты HTML повторно при отображении формы;
• Перевод: Поддержка перевода сообщений об ошибках, ярлыков полей и других
  строк;
• Валидация: Интеграция с библиотекой валидации для генерирования сообщений
  об ошибках для отправленных данных.

Компонент Symfony Form полагается на другие библиотеки в решении этих проблем.
В большинстве случаев вы будете использовать Twig и Symfony
HttpFoundation, компоненты
Translation and Validator,
но вы можете заменить любой из них другой библиотекой на ваш выбор.

Следующие разделы объясняют, как подключать эти библиотеки в фабрику форм.

Обработка запросов

Чтобы обработать даныные формы, вам понадобится вызвать метод
handleRequest():

За кулисами используется объект NativeRequestHandler
для считывания данных с правильных суперглобальных PHP (т.е. $_POST или $_GET),
основанніх на HTTP методе, сконфигурированном в форме (POST по умолчанию).

CSRF-защита

Защита от CSRF-атак встроена в компонент Form, но вам нужно ясно включить
её или заменить пользовательским решением. Если вы хотите использовать встроенную
поддержку, для начала установите компонент CSRF Security:

Следующий отрезок добавляет CSRF-защиту к фабрике форм:

Внутренне, это расширение автоматически добавит скрытое поле к каждой форме
(по умолчанию названное _token), значение которой автоматически генерируется
CSRF-генератором и валидируется при построении формы.

Tip

Если вы не используете компонент HttpFoundation, то вместо него вы можете использовать
NativeSessionTokenStorage,
который полагается на встроенную PHP обработку сессии:

Вы можете отключить CSRF-защиту для формы используя опцию csrf_protection:

Шаблонизация Twig

Если вы используете компонент Form для обработки HTML форм, то вам понадобится
способ с лёгкостью отображать вашу форму в виде полей HTML формы (заполненную
значениями полей, ошибками и ярлыками). Если вы используете Twig в качестве
шаблонизатора, то компонент Form предлагает богатую интеграцию.

Чтобы использовать интеграцию, вам понадобится twig bridge, который предоставляет
интеграцию между Twig и некоторыми компонентами Symfony:

Интеграция TwigBridge предоставляет вам несколько функций Twig ,
которые помогают вам отображать HTML-виджет, ярлык и ошибку для каждого
поля (а также несколько других вещей). Чтобы сконфигурировать интеграцию,
вам понадобится запустить или получить доступ к Twig и добавить
FormExtension:

1.30

Twig_FactoryRuntimeLoader была представлена в Twig 1.30.

Точные детали вашей Конфигурации Twig будут отличаться, но цель — позволить
добавить FormExtension в Twig, что
предоставляет вам доступ к функциям Twig для отображения форм.
Чтобы сделать это, вам для начала нужно создать
TwigRendererEngine, где вы определите
ваш темы формы (т.е. источники /
файлы, которые определяют HTML разметку формы).

Чтобы узнать общие детали об отображении форм, см. Как настроить отображение формы.

Note

Если вы используете интеграцию Twig, прочтите «»
ниже, чтобы узнать детали о необходимых фильтрах перевода.

Перевод

Если вы используете интеграцию Twig с одним из файлов темы по умолчанию
(например, form_div_layout.html.twig), то существует фильтр Twig (trans),
который используется для перевода ярлыков, ошибок, опционального текста и других строк
формы.

Чтобы добавить фильтр Twig trans, вы можете либо использовать встроенный
TranslationExtension, который
интегрируется с компонентом Symfony Translation, либо добавить фильтр Twig
самостоятельно, через ваше собственное расширение Twig.

Чтобы использовать встроенную интеграцию, убедитесь в том, что в вашем
проекте установлены компоненты Symfony Translation и Config:

Далее, добавьте TranslationExtension
к вашему экземпляру TwigEnvironment:

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

Чтобы узнать больше о переводах, см. Переводы.

Валидация

Компонент Form поставляется с тесной (но необязательной) интеграцией с компонентом
Symfony Validator. Если вы используете другое решение для валидации — то это не
проблема! Просто возьмите отправленные данные вашей формы (массив или объект) и
передайте их через вашу собственную систему валидации.

Чтобы использовать интеграцию с компонентом Symfony Validator, для начала
убедитесь, что он установлен в вашем приложении:

Если вы не знакомы с этим компонентом, прочтите больше о нём: Валидация.
Компонент Form поставляется с классом
ValidatorExtension,
который автоматически применяет валидацию к вашим данным. Эти ошибки потом
связываются с соответствующим полем и отображаются.

Ваша интеграция с компонентом Validation будет выглядеть как-то так:

Чтобы узнать больше, перейдите к разделу .

Доступ к фабрике форм

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

Note

В этом документе, фабрика форм всегда является локальной переменной под
названием $formFactory. Суть в том, что вам скорее всего понадобится
создать этот объект в более «глобальном» виде, чтобы вы могли получить к
нему доступ откуда угодно.

То, как именно вы получит доступ к вашей фабрике форм — зависит от вас. Если
вы используете сервис-контейнер (как предоставленный с
компонентом DependencyInjection), то
вам стоит добавить фабрику форм в ваш контейнер и вызывать её, когда вам будет
это нужно. Если ваше приложение использует глобальные или статические перменные
(обычно не очень хорошая идея), то вы можете хранить объект в некотором статичном
классе или сделать что-то подобное.

Создание простой формы

Tip

Если вы используете фреймворк Symfony, то фабрика форм доступна автоматически
в виде сервиса под названием form.factory. Кроме того, базовый класс контроллера
по умолчанию имеет метод createFormBuilder(),
который является шорткатом для получения фабрики форм и вызова в ней createBuilder().

Создание формы осуществляется через объект FormBuilder,
где вы строите и конфигурируете разные поля. Конструктор форм создаётся из
фабрики форм.

• Standalone Use
• Framework Use

Как вы видите, создание формы — это как написание рецепта: вы вызываете add()
для каждого нового поля, которое вы хотите создать. Первый аргумент add() —
это имя вашего поля, а второй — полное имя класса. Компонент Form поставляетс
со множеством встроенных типов.

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

Установка значений по умолчению

Если вам нужно, чтобы ваша форма загружалась с некоторыми значеиями по умолчанию
(или если вы строите форму «редактирования»), просто передайте данные по умолчанию
при создании вашего конструктора форм:

• Standalone Use
• Framework Use

Tip

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

Отображение формы

Теперь, когда форма была создана, следующий шаг — отобразить её. Это делается
путём передачи специального объекта формы «view» в ваш щаблон (отметьте $form->createView()
в контроллере выше) и использования набора функций-хелперов формы:

Вот и всё! Напечатав form_widget(form), вы отобразите каждое поле формы
вместе с ярлыком и сообщением ошибки (если оно есть). И хоть это и легко, но
(пока) не очень гибко. Обычно, вам нужно будет отображать каждое поле формы
отдельно, чтобы вы могли контролировать то, как выглядит форма. Вы узнаете,
как это делать в статье настройка формы.

Изменения метода и действия формы

По умолчанию, форма отправляет по тому же URI, который отобразил форму с запросом
HTTP POST. Это поведение можно изменить используя опции
и (опция method также используется handleRequest(),
чтобы определить, была ли отправлена форма):

• Standalone Use
• Framework Use

Обработка отправок формы

Чтобы обработать отправки формы, используйте метод handleRequest():

• Standalone Use
• Framework Use

Caution

Метод createView() должен вызываться после вызова handleRequest().
Иначе, при использовании событий формы, изменения, сделанные
в событиях *_SUBMIT не будут применяться к просмотру (вроде ошибок валидации).

Это определяет общий «рабочий процесс», который содержит 3 разные возможности:

1. В изначальном запросе GET (т.е. когда пользователь заходит на вашу
   страницу), постройте вашу форму и отобразите её;

Если запрос — POST, рбработайте отправленные данные (через handleRequest()).

Затем:

1. если форма не валина, отобразите форму (которая теперь будет содержать ошибки);
2. если форма валидна, выполните некоторые действия и перенаправьте.

К счастью, вам не надо решать, была ли отправлена форма. Просто передайте текущий
запрос методу handleRequest(). Далее компонент
Form сделает всю работу за вас.

Валидация формы

Простейшим способом добавить валидацию к вашей форме — через опцию
constraints при построении каждого поля:

• Standalone Use
• Framework Use

Когда форма привязана, эти ограничения валидации будут применены автоматически, а
ошибки отобразятся рядом с полями ошибок.

Очистка ошибок формы

Все ошибки могут быть очищены вручную методом
clearErrors().
Это удобно, если вы хотите провалидировать форму без отображения
ошибок валидации пользователю (например, при частичной отправке AJAX или
динамической модификации форм).

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

Узнайте больше

• Как изменить действие и метод формы
• Тема формы Bootstrap 4
• Тема формы Bootstrap 5
• Как выбирать группы валидации, основанные на нажатой кнопке
• Как создать пользовательский тип поля формы
• Как создать расширение типа формы
• Как выбирать группы валидации, основанные на отправленных данных
• Как и когда использовать отображатели данных
• Как использовать преобразователи данных
• Как использовать функцию submit() для обработки отправки форм
• Как отключить валидацию отправленных данных
• Как динамически модифицировать формы, используя события форм
• Как встраивать формы
• События формы
• Как встроить коллекцию форм
• Как настроить отображение формы
• Как получить доступ к сервисам или конфигурации изнутри формы
• Как работать с темами формы
• Как уменьшить дублирование кода с помощью «inherit_data»
• Как отправить форму с несколькими кнопками
• Как контролировать отображение в форме
• Создание пользовательского отгадывателя типа
• Как проводить модульное тестирование ваших форм
• Как сконфигурировать пустые данные для класса формы
• Как динамически конфигурировать группы валидации форм
• Как определить, какие группы валидации использовать
• Как использовать форму без класса данных

Forms

Do you prefer video tutorials? Check out the Symfony Forms screencast series.

Creating and processing HTML forms is hard and repetitive. You need to deal with rendering HTML form fields, validating submitted data, mapping the form data into objects and a lot more. Symfony includes a powerful form feature that provides all these features and many more for truly complex scenarios.

Installation

In applications using Symfony Flex, run this command to install the form feature before using it:

Usage

The recommended workflow when working with Symfony forms is the following:

1. Build the form in a Symfony controller or using a dedicated form class;
2. Render the form in a template so the user can edit and submit it;
3. Process the form to validate the submitted data, transform it into PHP data and do something with it (e.g. persist it in a database).

Each of these steps is explained in detail in the next sections. To make examples easier to follow, all of them assume that you’re building a small Todo list application that displays «tasks».

Users create and edit tasks using Symfony forms. Each task is an instance of the following Task class:

This class is a «plain-old-PHP-object» because, so far, it has nothing to do with Symfony or any other library. It’s a normal PHP object that directly solves a problem inside your application (i.e. the need to represent a task in your application). But you can also edit Doctrine entities in the same way.

Form Types

Before creating your first Symfony form, it’s important to understand the concept of «form type». In other projects, it’s common to differentiate between «forms» and «form fields». In Symfony, all of them are «form types»:

Источник

The Form Component

The Form component allows you to create, process and reuse forms.

The Form component is a tool to help you solve the problem of allowing end-users to interact with the data and modify the data in your application. And though traditionally this has been through HTML forms, the component focuses on processing data to and from your client and application, whether that data be from a normal form post or from an API.

Installation

If you install this component outside of a Symfony application, you must require the vendor/autoload.php file in your code to enable the class autoloading mechanism provided by Composer. Read this article for more details.

Configuration

This article explains how to use the Form features as an independent component in any PHP application. Read the Forms article to learn about how to use it in Symfony applications.

In Symfony, forms are represented by objects and these objects are built by using a form factory. Building a form factory is done with the factory method Forms::createFormFactory :

This factory can already be used to create basic forms, but it is lacking support for very important features:

• Request Handling: Support for request handling and file uploads;
• CSRF Protection: Support for protection against Cross-Site-Request-Forgery (CSRF) attacks;
• Templating: Integration with a templating layer that allows you to reuse HTML fragments when rendering a form;
• Translation: Support for translating error messages, field labels and other strings;
• Validation: Integration with a validation library to generate error messages for submitted data.

The Symfony Form component relies on other libraries to solve these problems. Most of the time you will use Twig and the Symfony HttpFoundation, Translation and Validator components, but you can replace any of these with a different library of your choice.

The following sections explain how to plug these libraries into the form factory.

Request Handling

To process form data, you’ll need to call the handleRequest() method:

Behind the scenes, this uses a NativeRequestHandler object to read data off of the correct PHP superglobals (i.e. $_POST or $_GET ) based on the HTTP method configured on the form (POST is default).

If you need more control over exactly when your form is submitted or which data is passed to it, use the submit() method to handle form submissions.

Integration with the HttpFoundation Component

If you use the HttpFoundation component, then you should add the HttpFoundationExtension to your form factory:

Now, when you process a form, you can pass the Request object to handleRequest():

For more information about the HttpFoundation component or how to install it, see The HttpFoundation Component.

CSRF Protection

Protection against CSRF attacks is built into the Form component, but you need to explicitly enable it or replace it with a custom solution. If you want to use the built-in support, first install the Security CSRF component:

The following snippet adds CSRF protection to the form factory:

Internally, this extension will automatically add a hidden field to every form (called _token by default) whose value is automatically generated by the CSRF generator and validated when binding the form.

If you’re not using the HttpFoundation component, you can use NativeSessionTokenStorage instead, which relies on PHP’s native session handling:

You can disable CSRF protection per form using the csrf_protection option:

Twig Templating

If you’re using the Form component to process HTML forms, you’ll need a way to render your form as HTML form fields (complete with field values, errors, and labels). If you use Twig as your template engine, the Form component offers a rich integration.

To use the integration, you’ll need the twig bridge, which provides integration between Twig and several Symfony components:

The TwigBridge integration provides you with several Twig Functions that help you render the HTML widget, label, help and errors for each field (as well as a few other things). To configure the integration, you’ll need to bootstrap or access Twig and add the FormExtension:

The exact details of your Twig Configuration will vary, but the goal is always to add the FormExtension to Twig, which gives you access to the Twig functions for rendering forms. To do this, you first need to create a TwigRendererEngine, where you define your form themes (i.e. resources/files that define form HTML markup).

For general details on rendering forms, see How to Customize Form Rendering.

If you use the Twig integration, read «The Form Component» below for details on the needed translation filters.

Translation

If you’re using the Twig integration with one of the default form theme files (e.g. form_div_layout.html.twig ), there is a Twig filter ( trans ) that is used for translating form labels, errors, option text and other strings.

To add the trans Twig filter, you can either use the built-in TranslationExtension that integrates with Symfony’s Translation component, or add the Twig filter yourself, via your own Twig extension.

To use the built-in integration, be sure that your project has Symfony’s Translation and Config components installed:

Next, add the TranslationExtension to your TwigEnvironment instance:

Depending on how your translations are being loaded, you can now add string keys, such as field labels, and their translations to your translation files.

For more details on translations, see Translations.

Validation

The Form component comes with tight (but optional) integration with Symfony’s Validator component. If you’re using a different solution for validation, no problem! Take the submitted/bound data of your form (which is an array or object) and pass it through your own validation system.

To use the integration with Symfony’s Validator component, first make sure it’s installed in your application:

If you’re not familiar with Symfony’s Validator component, read more about it: Validation. The Form component comes with a ValidatorExtension class, which automatically applies validation to your data on bind. These errors are then mapped to the correct field and rendered.

Your integration with the Validation component will look something like this:

To learn more, skip down to the The Form Component section.

Accessing the Form Factory

Your application only needs one form factory, and that one factory object should be used to create any and all form objects in your application. This means that you should create it in some central, bootstrap part of your application and then access it whenever you need to build a form.

In this document, the form factory is always a local variable called $formFactory . The point here is that you will probably need to create this object in some more «global» way so you can access it from anywhere.

Exactly how you gain access to your one form factory is up to you. If you’re using a service container (like provided with the DependencyInjection component), then you should add the form factory to your container and grab it out whenever you need to. If your application uses global or static variables (not usually a good idea), then you can store the object on some static class or do something similar.

Creating a simple Form

If you’re using the Symfony Framework, then the form factory is available automatically as a service called form.factory , you can inject it as SymfonyComponentFormFormFactoryInterface . Also, the default base controller class has a createFormBuilder() method, which is a shortcut to fetch the form factory and call createBuilder() on it.

Creating a form is done via a FormBuilder object, where you build and configure different fields. The form builder is created from the form factory.

As you can see, creating a form is like writing a recipe: you call add() for each new field you want to create. The first argument to add() is the name of your field, and the second is the fully qualified class name. The Form component comes with a lot of built-in types.

Now that you’ve built your form, learn how to render it and process the form submission.

Setting default Values

If you need your form to load with some default values (or you’re building an «edit» form), pass in the default data when creating your form builder:

In this example, the default data is an array. Later, when you use the data_class option to bind data directly to objects, your default data will be an instance of that object.

Rendering the Form

Now that the form has been created, the next step is to render it. This is done by passing a special form «view» object to your template (notice the $form->createView() in the controller above) and using a set of form helper functions:

That’s it! By printing form_widget(form) , each field in the form is rendered, along with a label and error message (if there is one). While this is convenient, it’s not very flexible (yet). Usually, you’ll want to render each form field individually so you can control how the form looks. You’ll learn how to do that in the form customization article.

Changing a Form’s Method and Action

By default, a form is submitted to the same URI that rendered the form with an HTTP POST request. This behavior can be changed using the FormType Field and FormType Field options (the method option is also used by handleRequest() to determine whether a form has been submitted):

Источник

How to Customize Form Rendering

Symfony gives you several ways to customize how a form is rendered. In this article you’ll learn how to make single customizations to one or more fields of your forms. If you need to customize all your forms in the same way, create instead a form theme or use any of the built-in themes, such as the Bootstrap theme for Symfony forms.

Form Rendering Functions

A single call to the form() Twig function is enough to render an entire form, including all its fields and error messages:

The next step is to use the form_start(), form_end(), form_errors() and form_row() Twig functions to render the different form parts so you can customize them adding HTML elements and attributes:

The form_row() function outputs the entire field contents, including the label, help message, HTML elements and error messages. All this can be further customized using other Twig functions, as illustrated in the following diagram:

The form_label(), form_widget(), form_help() and form_errors() Twig functions give you total control over how each form field is rendered, so you can fully customize them:

If you’re rendering each field manually, make sure you don’t forget the _token field that is automatically added for CSRF protection.

You can also use << form_rest(form) >> (recommended) to render any fields that aren’t rendered manually. See the form_rest() documentation below for more information.

Later in this article you can find the full reference of these Twig functions with more usage examples.

Form Rendering Variables

Some of the Twig functions mentioned in the previous section allow to pass variables to configure their behavior. For example, the form_label() function lets you define a custom label to override the one defined in the form:

Some form field types have additional rendering options that can be passed to the widget. These options are documented with each type, but one common option is attr , which allows you to modify HTML attributes on the form element. The following would add the task_field CSS class to the rendered input text field:

If you’re rendering an entire form at once (or an entire embedded form), the variables argument will only be applied to the form itself and not its children. In other words, the following will not pass a «foo» class attribute to all of the child fields in the form:

If you need to render form fields «by hand» then you can access individual values for fields (such as the id , name and label ) using its vars property. For example to get the id :

Later in this article you can find the full reference of these Twig variables and their description.

Form Themes

The Twig functions and variables shown in the previous sections can help you customize one or more fields of your forms. However, this customization can’t be applied to the rest of the forms of your app.

If you want to customize all forms in the same way (for example to adapt the generated HTML code to the CSS framework used in your app) you must create a form theme.

Form Functions and Variables Reference

Functions

form(form_view, variables)

Renders the HTML of a complete form.

You will mostly use this helper for prototyping or if you use custom form themes. If you need more flexibility in rendering the form, you should use the other helpers to render individual parts of the form instead:

form_start(form_view, variables)

Renders the start tag of a form. This helper takes care of printing the configured method and target action of the form. It will also include the correct enctype property if the form contains upload fields.

form_end(form_view, variables)

Renders the end tag of a form.

This helper also outputs form_rest() (which is explained later in this article) unless you set render_rest to false:

form_label(form_view, label, variables)

Renders the label for the given field. You can optionally pass the specific label you want to display as the second argument.

See «How to Customize Form Rendering» to learn about the variables argument.

form_help(form_view)

Renders the help text for the given field.

form_errors(form_view)

Renders any errors for the given field.

In the Bootstrap 4 form theme, form_errors() is already included in form_label() . Read more about this in the Bootstrap 4 theme documentation.

form_widget(form_view, variables)

Renders the HTML widget of a given field. If you apply this to an entire form or collection of fields, each underlying form row will be rendered.

The second argument to form_widget() is an array of variables. The most common variable is attr , which is an array of HTML attributes to apply to the HTML widget. In some cases, certain types also have other template-related options that can be passed. These are discussed on a type-by-type basis. The attributes are not applied recursively to child fields if you’re rendering many fields at once (e.g. form_widget(form) ).

See «How to Customize Form Rendering» to learn more about the variables argument.

form_row(form_view, variables)

Renders the «row» of a given field, which is the combination of the field’s label, errors, help and widget.

The second argument to form_row() is an array of variables. The templates provided in Symfony only allow to override the label as shown in the example above.

See «How to Customize Form Rendering» to learn about the variables argument.

form_rest(form_view, variables)

This renders all fields that have not yet been rendered for the given form. It’s a good idea to always have this somewhere inside your form as it’ll render hidden fields for you and make any fields you forgot to render easier to spot (since it’ll render the field for you).

form_parent(form_view)

Returns the parent form view or null if the form view already is the root form. Using this function should be preferred over accessing the parent form using form.parent . The latter way will produce different results when a child form is named parent .

Tests

Tests can be executed by using the is operator in Twig to create a condition. Read the Twig documentation for more information.

selectedchoice(selected_value)

This test will check if the current choice is equal to the selected_value or if the current choice is in the array (when selected_value is an array).

rootform

This test will check if the current form does not have a parent form view.

Form Variables Reference

The following variables are common to every field type. Certain field types may define even more variables and some variables here only really apply to certain types. To know the exact variables available for each type, check out the code of the templates used by your form theme.

Assuming you have a form variable in your template and you want to reference the variables on the name field, accessing the variables is done by using a public vars property on the FormView object:

Variable	Usage
action	The action of the current form.
attr	A key-value array that will be rendered as HTML attributes on the field.
block_prefixes	An array of all the names of the parent types.
cache_key	A unique key which is used for caching.
compound	Whether or not a field is actually a holder for a group of children fields (for example, a choice field, which is actually a group of checkboxes).
data	The normalized data of the type.
disabled	If true , disabled=»disabled» is added to the field.
errors	An array of any errors attached to this specific field (e.g. form.title.errors ). Note that you can’t use form.errors to determine if a form is valid, since this only returns «global» errors: some individual fields may have errors. Instead, use the valid option.
form	The current FormView instance.
full_name	The name HTML attribute to be rendered.
help	The help message that will be rendered.
id	The id HTML attribute to be rendered.
label	The string label that will be rendered.
label_attr	A key-value array that will be rendered as HTML attributes on the label.
method	The method of the current form (POST, GET, etc.).
multipart	If true , form_enctype will render enctype=»multipart/form-data» .
name	The name of the field (e.g. title ) — but not the name HTML attribute, which is full_name .
required	If true , a required attribute is added to the field to activate HTML5 validation. Additionally, a required class is added to the label.
submitted	Returns true or false depending on whether the whole form is submitted
translation_domain	The domain of the translations for this form.
valid	Returns true or false depending on whether the whole form is valid.
value	The value that will be used when rendering (commonly the value HTML attribute). This only applies to the root form element.

Behind the scenes, these variables are made available to the FormView object of your form when the Form component calls buildView() and finishView() on each «node» of your form tree. To see what «view» variables a particular field has, find the source code for the form field (and its parent fields) and look at the above two functions.

Источник

Time to add validation errors and get this test passing. First, add the validation. Open the Programmer class. There’s no validation stuff here yet, so we need the use statement for it. I’ll use the NotBlank class directly, let PhpStorm auto-complete that for me, then remove the last part and add as Assert:

That’s a little shortcut to get that use statement you always need for validation.

Now, above username, add @AssertNotBlank with a message option. Go back and copy the clever message and paste it here:

Handling Validation in the Controller

Ok! That was step 1. Step 2 is to go into the controller and send the validation errors back to the user. We’re using forms, so handling validation is going to look pretty much identical to how it looks in traditional web forms.

Check out that processForm() function we created in episode 1:

All this does is json_decode the request body and call $form->submit(). That does the same thing as $form->handleRequest(), which you’re probably familiar with. So after this function is called, the form processing has happened. After it, add an if statement with the normal if (!$form->isValid()):

If we find ourselves here, it means we have validation errors. Let’s see if this is working. Use the dump() function and the $form->getErrors() function, passing it true and false as arguments. That’ll give us all the errors in a big tree. Cast this to a string — getErrors() returns a FormErrorIterator object, which has a nice __toString() method. Add a die at the end:

Let’s run our test to see what this looks like. Copy the testValidationErrors method name, then run:

php bin/phpunit -c app --filter testValidationErrors

Ok, there’s our printed dump. Woh, that is ugly. That’s the nice HTML formatting that comes from the dump() function. But it’s unreadable here. I’ll show you a trick to clean that up.

It’s dumping HTML because it detects that something is accessing it via the web interface. But we kinda want it to print nicely for the terminal. Above the dump() function, add header('Content-Type: cli'):

That’s a hack — but try the test now:

bin/phpunit -c app --filter testValidationErrors

Ok, that’s a sweet looking dump. We’ve got the validation error for the nickname field and another for a missing CSRF token — we’ll fix that soon. But, validation is working.

Collecting the Validation Errors

So now we just need to collect those errors and put them into a JSON response. To help with that, I’m going to paste a new private function into the bottom of ProgrammerController:

If you’re coding with me, you’ll find this in a code block on this page — copy it from there. Actually, I adapted this from some code in FOSRestBundle.

A Form object is a collection of other Form objects — one for each field. And sometimes, fields have sub-fields, which are yet another level of Form objects. It’s a tree. And when validation runs, it attaches the errors to the Form object of the right field. That’s the treky, I mean techy, explanation of this function: it recursively loops through that tree, fetching the errors off of each field to create an associative array of those errors.

Head back to newAction() and use this: $errors = $this->getErrorsFromForm() and pass it the $form object. Now, create a $data array that will eventually be our JSON response.

Remember, we want type, title and errors keys. Add a type key: this is the machine name of what went wrong. How about validation_error — I’m making that up. For title — we’ll have the human-readable version of what went wrong. Let’s use: «There was a validation error». And for errors pass it the $errors array.

Finish it off! Return a new JsonResponse() with $data and the 400 status code:

Phew! Let’s give it a try:

bin/phpunit -c app --filter testValidationErrors

Oof! That’s not passing! That’s a huge error. The dumped response looks perfect. The error started on ProgrammerControllerTest where we use assertResponsePropertiesExist(). Whoops! And there’s the problem — I had assertResponsePropertyExists() — what you use to check for a single field. Make sure your’s says assertResponsePropertiesExist().

Try it again:

bin/phpunit -c app --filter testValidationErrors

It’s passing! Let’s pretend I made that mistake on purpose — it was nice because we could see that the dumped response looks exactly like we wanted.

This tutorial uses an older version of Symfony. The concepts of REST and errors are still valid, but I recommend using API Platform in new Symfony apps.

What PHP libraries does this tutorial use?

// composer.json
{
    "require": {
        "php": ">=5.3.3",
        "symfony/symfony": "2.6.*", // v2.6.11
        "doctrine/orm": "~2.2,>=2.2.3,<2.5", // v2.4.7
        "doctrine/dbal": "<2.5", // v2.4.4
        "doctrine/doctrine-bundle": "~1.2", // v1.4.0
        "twig/extensions": "~1.0", // v1.2.0
        "symfony/assetic-bundle": "~2.3", // v2.6.1
        "symfony/swiftmailer-bundle": "~2.3", // v2.3.8
        "symfony/monolog-bundle": "~2.4", // v2.7.1
        "sensio/distribution-bundle": "~3.0,>=3.0.12", // v3.0.21
        "sensio/framework-extra-bundle": "~3.0,>=3.0.2", // v3.0.7
        "incenteev/composer-parameter-handler": "~2.0", // v2.1.0
        "hautelook/alice-bundle": "0.2.*", // 0.2
        "jms/serializer-bundle": "0.13.*" // 0.13.0
    },
    "require-dev": {
        "sensio/generator-bundle": "~2.3", // v2.5.3
        "behat/behat": "~3.0", // v3.0.15
        "behat/mink-extension": "~2.0.1", // v2.0.1
        "behat/mink-goutte-driver": "~1.1.0", // v1.1.0
        "behat/mink-selenium2-driver": "~1.2.0", // v1.2.0
        "phpunit/phpunit": "~4.6.0" // 4.6.4
    }
}

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

Компонент Form

Компонент Form дозволяє вам з легкістю створювати, обробляти та використовувати
форми повторно.

Копомнент Form — це інструмент, покликаний допомогти вам вирішити проблему дозволу
кінцевим користувачам взаємодіяти та змінювати дані у вашому додатку. І хоча традиційно
це робилось через HTML-форми, компонент фокусується на обробці даних від та до вашого
клієнту та додатку, незважаючи на те, це дані зі звичайного запису форми, або з API.

Установка

Note

Якщо ви встановлюєте цей компонент поза додатком Symfony, вам потрібно підключити
файл vendor/autoload.phpу вашому коді для включення механізму автозавантаження
класів, наданих Composer. Детальніше можна прочитати у цій статті.

Конфігурація

See also

Ця стаття пояснює, як використовувати функції Форми як незалежного
компоненту в будь-якому додатку PHP. Прочитайте статтю Форми,
щоб отримати розуміння, як використовувати його в додатках Symfony.

В Symfony, форми представлено об’єктами, а ці об’єкти будуються з використанням
фабрики форм. Побудувати фабрику форм просто за допомогою методу Forms::createFormFactory:

Ця фабрика може вже бути використана для створення базових форм, але їй не
вистачає підтримки для дуже важливих функцій:

• Обробка запитів: Підтримка обробки запитів та завантаження файлів;
• CSRF-захист: Підтримка захисту від атак міжсайтової підробки запитів
  (CSRF);
• Шаблонізація: Інтеграція з рівнем шаблонізації, який дозволяє вам використовувати
  фрагменти HTML повторно при відображенні форми;
• Перклад: Підтримка перекладу повідомлень про помилки, ярликів полів та інших
  рядків;
• Валідація: Інтеграція з бібліотекою валідації для генерування повідомлень про
  помилки для відправки даних.

Компонент Symfony Form покладається на інші бібліотеки в рішенні цих проблем.
В більшості випадків ви будете використовувати Twig та Symfony
HttpFoundation, компоненти
Translation та Validator,
але ви можете замінити будь-яки з них іншою бібліотекою на власний вибір.

Наступні розділи пояснюються, як підключати ці бібліотеки в фабрику форм.

Обробка запитів

Шоб обробити дані форми, вам знадобиться викликати метод
handleRequest():

За лаштунками використовується об’єкт NativeRequestHandler
для зчитування даних з правильних суперглобальних PHP (тобто $_POST або $_GET),
заснованих на HTTP-методі, сконфігурованому в формі (POST за замовчуванням).

CSRF-захист

Захист від CSRF-атак вбудобваний в компонент Form, але вам потрібно чітко
включити його або замінити користувацьким рішенням. Якщо ви хочете використовувати
вбудовану підтримку, для початку, встановіть компонент Security CSRF:

Наступний відрізок додає CSRF-захист до фабрики форм:

Внутрішньо, це розширення автоматично додасть приховане поле до кожної форми
(за замочуванням, назване _token), значення якої автоматично генерується
CSRF-генератором та валідується при побудові форми.

Tip

Якщо ви не використовуєте компонент HttpFoundation, то замість нього ви можете використовувати
NativeSessionTokenStorage,
який покладається на вбудобвану PHP-обробку сесії:

Ви можете відключити CSRF-захист для форми, використовуючи опцію csrf_protection:

Шаблонізація Twig

Якщо ви використовуєте компонент Форма для обробки HTML-форм, то вам знадобиться
спосіб легко відображати вашу форму у вигляді полів HTML-форми (заповнену значеннями
полів, помилками та ярликами). Якщо ви використовуєте Twig в якості шаблонізатору,
то компонент Форма пропонує багату інтеграцію.

Щоб використовувати інтеграцію, вам знадобиться twig bridge, який надає інтеграцію
між Twig та деякими компонентами Symfony:

Інтеграція TwigBridge надає вам декілька функцій Twig ,
які допомгають вам відображати HTML-віджет, ярлик та помилку для кожного
поля (а також декілька інших речей). Щоб сконфигурувати інтеграцію, вам
знадобиться запустить або отримати доступ до Twig, та додати
FormExtension:

1.30

Twig_FactoryRuntimeLoader було представлено в Twig 1.30.

Точні деталі вашої Конфігурації Twig будуть відрізнятися, але ціль — дозволити
додати FormExtension в Twig, що
надає вам доступ до функції Twig для відображення форм.
Щоб зробити це, спочатку вам необхідно створити
TwigRendererEngine, де ви визначите ваші
теми формы (тобто джерела/файлі, які визначають HTML
розмітку форми).

Щоб дізнатися загальні деталі про відображення форм, див. Як налаштувати відображення форми.

Note

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

Переклад

Якщо ви використовуєте інтеграцію Twig з одним з файлів теми за замочуванням
(наприклад, form_div_layout.html.twig), то існує фільтр Twig (trans),
який використовується для перекладу ярликів, помилок, опціонального тексту та
інших рядків форми.

Щоб додати фільтр Twig trans, ви можете або використати вбудований
TranslationExtension, який
інтегрується з компонентом Symfony Переклад, або додати фільтр Twig
самостійно, через ваше власне розширення Twig.

Шоб використовувати вбудовану інтеграцію, переконайтесь в тому, що у
вашому проекті встановлені компоненти Symfony Переклад та Конфігурація:

Далі, додайте TranslationExtension
до вашого екземпляру TwigEnvironment:

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

Щоб дізнатися більше про переклади, див. Переклади.

Валідація

Компонент Form постачається з тісною (але необов’язковою) інтеграцією з
комонентом Symfony Validator. Якщо ви використовуєте інше рішення для валідації
— це не проблема! Просто візьміть відправлені дані вашої форми (масив чи об’єкт)
та передайте їх через вашу власну систему валідації.

Щоб використовувати інтеграцію з компонентом Symfony Валідатор, спочатку
переконайтеся, що він встановлений у вашому додатку:

Якщо ви не знайомі з цим компонентом, прочитайте більше про нього: Валідація.
Компонент Форма постачається з класом
ValidatorExtension,
який автоматично застосовує валідацію до ваших даних. Ці помилки потім
зв’язуються з відповідним полем та відображаються.

Ваша інтеграція з компонентом Валідація буд виглядати якось так:

Щоб дізнатися більше, перейдіть до розділу .

Доступ до фабрики форм

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

Note

В цьому документі, фабрика форм завжди є локальною змінною під назвою
$formFactory. Суть в тому, що вам скоріш за все знадобиться створити
цей об’єкт в більш «глобальному» вигляді, щоб ви могли отримати до нього
доступ звідки завгодно.

Те, як саме ви отримаєте доступ до вашої фабрики фори — залежить від вас. Якщо
ви використовуєте сервіс-контейнер (як наданий
компонентом DependencyInjection), то
вам слід додати фабрику форм в ваш контейнер та викликати її, коли вам це буде
потрібно. Якщо ваш застосунок використовує глобальні або статичні змінні (зазвичай
не дуже хороша ідея), то ви можете зберігати об’єкт в деякому статичному класі,
або зробити щось подібне.

Створення простої форми

Tip

Якщо ви використовуєете фреймворк Symfony, то фабрика форм доступна автоматично у
вигляді сервісу під назвою form.factory, ви можете впровадити її як
SymfonyComponentFormFormFactoryInterface. Крім того, базовий клас контролера за
замочуванням має метод createFormBuilder(),
яки є скороченням для отримання фабрики форм та виклика в ній createBuilder().

Створення форми здійснюється через об’єкт FormBuilder,
де ви будуєте та конфігуруєте різні поля. Конструктор форм створюється з фабрики
форм.

• Standalone Use
• Framework Use

Як ви бачите, створення форми — це як написати рецепт: ви викликаєте add()
для кожного нового поля, яке ви хочете створити. Перший аргумент add() — це
ім’я вашого поля, а другий — повне ім’я класу. Компонент Форма постачається з
багатьма вбудованими типами.

Тепер, коли ви побудували вашу форму, дізнайтеся, як
відображати її та
обробляти відправку форми .

Установка значень за замовчуванням

Якщо вам треба, щоб ваша форма завантажувалась з деякими значеннями за замовчуванням
(або якщо ви будуєте форму «редагування), просто передайте дані за замовчуванням при
створенні вашого конструктору форм:

• Standalone Use
• Framework Use

Tip

В цьому прикладі, дані за замовчуванням — масив. Пізніше, коли ви будете
використовувати опцію data_class для прив’язки
даних напряму до об’єктів, ваші дані за замовчуванням будуть екземпляром
цього об’єкту.

Відображення форми

Тепер, коли форма була створена, наступний крок — відобразити її. Це робиться
шляхом передачі спеціального об’єкту форми «view» у ваш шаблон (відмітьте $form->createView()
в контролері вище) та використання набору функцій-хелперів форми:

Ось і все! Надрукувавши form_widget(form), ви відобразите кожне поле форми
разом з ярликом та повідомленням про помилку (якщо воно є). І хоча це і легко,
але (поки) не дуже гнучко. Зазвичай, вам треба буде відображати кожне поле форми
окремо, щоб ви могли контролювати те, як виглядає форма. Ви дізнаєтесь, як це
зробити, в статті налаштування форми.

Зміна методу та дії форми

За замовчуванням, форма відправляє по тому ж URI, який відобразив форму з запитом
HTTP POST. Цю поведінку можна змінити, використовуючи опції Поле FormType
та Поле FormType (опція method також використовується handleRequest(),
щоб визначити, чи була відправлена форма):

• Standalone Use
• Framework Use

Обробка відправок форми

Щоб обробити відправки форми, використовуйте метод handleRequest():

• Standalone Use
• Framework Use

Caution

Метод createView() має викликатися після виклику handleRequest(). Інакше,
при використанні подій форми, зміни, зроблені в подіях
*_SUBMIT не будуть застосовуватися до перегляду (на кшталт помилок валідації).

Це визначає загальний «Робочий процес», який містить 3 різних можливості:

1. В початковому запиті GET (тобто, коли користувач заходить на вашу сторінку),
   побудуйте вашу форму та відобразіть її;

   Якщо запит — POST, обробіть відправлені дані (через handleRequest()).

   А потім:

2. якщо форма не валідна, відобразіть форму (яка тепер міститиме помилки);
3. якщо форма валідна, виконайте деякі дії та перенаправте.

На щастя, вам не потрібно вирішувати, чи була відправлена форма. Просто передайте
поточний запит методу handleRequest(). Далі
компонент Форма зробить всю роботу за вас.

Валідація форм

Найпростіший спосіб додати валідацію до вашої форми — через опцію
constraints при побудові кожного поля:

• Standalone Use
• Framework Use

Коли форма прив’язана, ці обмеження валідації будуть застосовані автоматично, а
помилки відобразяться поруч з полями помилок.

Очистка помилок форми

Всі помилки можуть бути очищені вручну методом
clearErrors().
Це зручно, якщо ви хочете валідувати форму без відображення помилок
валідації користувача (наприклад, при частковій відправці AJAX або
динамічній модифікації форм).

Так як очистка помилок робить форму валідною,
clearErrors() має
викликатися лише після перевірки того, що форма валідна.

Дізнайтеся більше

• Как изменить действие и метод формы
• Тема форми Bootstrap 4
• Тема форми Bootstrap 5
• Як обирати групи валідації, засновані на натиснутій кнопці
• Як створити користувацький тип поля форми
• Як створити розширення типу форми
• Як обирати групи валідації, засновані на відправлених даних
• Як і коли використовувати відображувачі даних
• Як використовувати перетворювачі даних
• Як використовувати функцію submit() для обробки відправки форм
• Як відключити валідацію відправлених даних
• Як динамічно модифікувати форми, використовуючи події форм
• Як вбудовувати форми
• Події форми
• Как вбудувати колекцію форм
• Як налаштувати відображення форми
• Як отримати доступ до сервісів або конфігурації зсередини форми
• Як працювати з темами форми
• Як зменшити дублювання коду за допомогою «inherit_data»
• Як відправити форму з декількома кнопками
• Как контролировать отображение в форме
• Створення користувацького вгадувача типу
• Як проводити модульне тестування ваших форм
• Як сконфігурувати порожні дані для класу форми
• Як динамічно конфігурувати групи валідації форм
• Як визначити, які групи валідації використовувати
• Як викоритовувати форму без класу даних

When writing APIs, a proper error handling is fundamental.

HTTP status codes are a great start, but often when we deal with user inputs is not enough.
If out model has complex validation rules, understanding the reason behind an 400 Bad Request error can be not trivial.

Fortunately when for symfony developers there are many libraries to deal with it.
Symfony Validator,
Symfony Form,
FOS REST Bundle and
JMS Serializer combined allows you to have nice error messages
to be shown to your users.

The entity

This is out model and in this case is petty trivial with only one property called «name».
By using the symfony validator annotations we define that the name can not be blank.

namespace AppBundleEntity;

use SymfonyComponentValidatorConstraints as Assert;

class Author
{
    /**
     * @AssertNotBlank()
     */
    public $name;
}

The form

This is the symfony form type to handle the author createing.

namespace AppBundleForm;

use SymfonyComponentFormAbstractType;
use SymfonyComponentFormFormBuilderInterface;
use SymfonyComponentOptionsResolverOptionsResolver;

class AuthorType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder->add('name');
    }

    public function configureOptions(OptionsResolver $resolver)
    {
        $resolver->setDefault('data_class', Author::class);
    }
}

The controller

This is the controller that acts as a glue of our components.

namespace AppBundleController;

use AppBundleEntityAuthor;
use AppBundleFromAuthorType;
use FOSRestBundleViewView;
use SymfonyComponentHttpFoundationRequest;
use SymfonyComponentHttpFoundationResponse;

class AuthorController
{
    public function create(Request $request)
    {
        $author = new Author(); 
        $form = $this->createForm(AuthorType::class, $author);
        $form->handleRequest($request);

        if ($form->isValid()) {

            // do something here

            return new View($author, Response::HTTP_CREATED);
        } else {
            return new View($form, Response::HTTP_BAD_REQUEST);
        }
    }
}

The result

The result of a PUT call to the create action, if the data are not correct will be:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "code": 400,
  "message": "Validation Failed",
  "errors": {
    "children": {
      "name": {
          "errors": [
            "This value shoul not be blank."
          ],
      }
    }
  }
}

Here the error message can be displayed to users, but if the API has to be consumed by some other software
(as example a mobile app), the error message can be not sufficient anymore.
Having some «error code» that can be hardcoded in some reliable way in the app code, will allow us
to provide a better user experience (offering some nice popup as example).

To do so is pretty easy, we will have to add just a custom error handler into the JMS serializer serialization process.
The custom error handler will use the the symfony validator payload feature to add machine readable error codes.

Custom error codes

The entity

In the original entity we just specify the payload property with our error code.

(The provided error handler accepts a string or an array of strings as error code)

namespace AppBundleEntity;

use SymfonyComponentValidatorConstraints as Assert;

class Author
{
    /**
     * @AssertNotBlank(payload={"error_code"="INVALID_NAME"})
     */
    public $name;
}

The error handler

This is the longest class in this tutorial but its logic is pretty simple and is mainly
a copy/paste from the original error handler.

namespace AppBundleSerializer;

use JMSSerializerContext;
use JMSSerializerGraphNavigator;
use JMSSerializerHandlerSubscribingHandlerInterface;
use JMSSerializerJsonSerializationVisitor;
use JMSSerializerVisitorInterface;
use SymfonyComponentFormForm;
use SymfonyComponentFormFormError;
use SymfonyComponentTranslationTranslatorInterface;
use SymfonyComponentValidatorConstraintViolation;

class FormErrorHandler implements SubscribingHandlerInterface
{
    private $translator;

    public static function getSubscribingMethods()
    {
        $methods = array();
        $methods[] = array(
            'direction' => GraphNavigator::DIRECTION_SERIALIZATION,
            'type' => Form::class,
            'format' => 'json',
        );

        return $methods;
    }

    public function __construct(TranslatorInterface $translator)
    {
        $this->translator = $translator;
    }

    public function serializeFormToJson(JsonSerializationVisitor $visitor, Form $form, array $type, Context $context = null)
    {
        $isRoot = null === $visitor->getRoot();
        $result = $this->adaptFormArray($this->convertFormToArray($visitor, $form), $context);

        if ($isRoot) {
            $visitor->setRoot($result);
        }

        return $result;

    }

    private function getErrorMessage(FormError $error)
    {
        if (null !== $error->getMessagePluralization()) {
            return $this->translator->transChoice($error->getMessageTemplate(), $error->getMessagePluralization(), $error->getMessageParameters(), 'validators');
        }

        return $this->translator->trans($error->getMessageTemplate(), $error->getMessageParameters(), 'validators');
    }

    private function getErrorPayloads(FormError $error)
    {
        /**
         * @var $cause ConstraintViolation
         */
        $cause = $error->getCause();

        if (!($cause instanceof ConstraintViolation) || !$cause->getConstraint() || empty($cause->getConstraint()->payload['error_code'])) {
            return null;
        }

        return $cause->getConstraint()->payload['error_code'];
    }

    private function convertFormToArray(VisitorInterface $visitor, Form $data)
    {
        $isRoot = null === $visitor->getRoot();

        $form = new ArrayObject();
        $errorCodes = array();
        $errors = array();

        foreach ($data->getErrors() as $error) {
            $errors[] = $this->getErrorMessage($error);
        }

        foreach ($data->getErrors() as $error) {
            $errorCode = $this->getErrorPayloads($error);
            if (is_array($errorCode)) {
                $errorCodes = array_merge($errorCodes, array_values($errorCode));
            } elseif ($errorCode !== null) {
                $errorCodes[] = $errorCode;
            }
        }

        if ($errors) {
            $form['errors'] = $errors;
            if ($errorCodes) {
                $form['error_codes'] = array_unique($errorCodes);
            }
        }

        $children = array();
        foreach ($data->all() as $child) {
            if ($child instanceof Form) {
                $children[$child->getName()] = $this->convertFormToArray($visitor, $child);
            }
        }

        if ($children) {
            $form['children'] = $children;
        }

        if ($isRoot) {
            $visitor->setRoot($form);
        }

        return $form;
    }


    private function adaptFormArray(ArrayObject $serializedForm, Context $context = null)
    {
        $statusCode = $this->getStatusCode($context);
        if (null !== $statusCode) {
            return [
                'code' => $statusCode,
                'message' => 'Validation Failed',
                'errors' => $serializedForm,
            ];
        }

        return $serializedForm;
    }

    private function getStatusCode(Context $context = null)
    {
        if (null === $context) {
            return;
        }

        $statusCode = $context->attributes->get('status_code');
        if ($statusCode->isDefined()) {
            return $statusCode->get();
        }
    }
}

Registering the error handler

Add this snippet to your services.xml to register the custom error handler to your application.

<service class="AppBundleSerializerFormErrorHandler" id="AppBundleSerializerFormErrorHandler">
    <argument id="translator" type="service"/>
    <tag name="jms_serializer.subscribing_handler"/>
</service>

The result

That’s all, ehe result of a PUT call to the create action now will contain our custom error codes.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "code": 400,
  "message": "Validation Failed",
  "errors": {
    "children": {
      "name": {
          "errors": [
            "This value should not be blank."
          ],
          "error_codes": [
            "INVALID_NAME"
          ],
      }
    }
  }
}

Conclusion

In this short tutorial we saw how is easy to add custom error codes to your API.

Of course, using the same strategy is possible to add many more information as «error_severity» or whatever you prefer.