Компонент Form¶

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

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

1

$form->handleRequest();

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

1
2
3
4
5
6

use Symfony\Component\Form\Forms;
use Symfony\Component\Form\Extension\HttpFoundation\HttpFoundationExtension;

$formFactory = Forms::createFormFactoryBuilder()
    ->addExtension(new HttpFoundationExtension())
    ->getFormFactory();

1

$form->handleRequest($request);

CSRF-защита¶

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

1

$ composer require symfony/security-csrf

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

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

use Symfony\Component\Form\Forms;
use Symfony\Component\HttpFoundation\Session\Session;
use Symfony\Component\Form\Extension\Csrf\CsrfExtension;
use Symfony\Component\Security\Csrf\TokenStorage\SessionTokenStorage;
use Symfony\Component\Security\Csrf\TokenGenerator\UriSafeTokenGenerator;
use Symfony\Component\Security\Csrf\CsrfTokenManager;

// создаёт объект сесси из компонента HttpFoundation
$session = new Session();

$csrfGenerator = new UriSafeTokenGenerator();
$csrfStorage = new SessionTokenStorage($session);
$csrfManager = new CsrfTokenManager($csrfGenerator, $csrfStorage);

$formFactory = Forms::createFormFactoryBuilder()
    // ...
    ->addExtension(new CsrfExtension($csrfManager))
    ->getFormFactory();

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

1
2
3
4

use Symfony\Component\Security\Csrf\TokenStorage\NativeSessionTokenStorage;

$csrfStorage = new NativeSessionTokenStorage();
// ...

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

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

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

1

$ composer require symfony/twig-bridge

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

use Symfony\Component\Form\Forms;
use Symfony\Bridge\Twig\Extension\FormExtension;
use Symfony\Component\Form\FormRenderer;
use Symfony\Bridge\Twig\Form\TwigRendererEngine;

// файл Twig, содержащий всю разметку по умолчанию для отображения форм
// этот файл поставляется с TwigBridge
$defaultFormTheme = 'form_div_layout.html.twig';

$vendorDirectory = realpath(__DIR__.'/../vendor');
// путь к библиотеке TwigBridge, чтобы Twig мог найти
// файл form_div_layout.html.twig
$appVariableReflection = new \ReflectionClass('\Symfony\Bridge\Twig\AppVariable');
$vendorTwigBridgeDirectory = dirname($appVariableReflection->getFileName());
// путь к вашим другим щаблонам
$viewsDirectory = realpath(__DIR__.'/../views');

$twig = new Twig_Environment(new Twig_Loader_Filesystem(array(
    $viewsDirectory,
    $vendorTwigBridgeDirectory.'/Resources/views/Form',
)));
$formEngine = new TwigRendererEngine(array($defaultFormTheme), $twig);
$twig->addRuntimeLoader(new \Twig_FactoryRuntimeLoader(array(
    FormRenderer::class => function () use ($formEngine, $csrfManager) {
        return new FormRenderer($formEngine, $csrfManager);
    },
)));

// ... (см. предыдущий раздел CSRF-защита, чтобы узнать больше)

// добавляет FormExtension в Twig
$twig->addExtension(new FormExtension());

// создаёт фабрику форм
$formFactory = Forms::createFormFactoryBuilder()
    // ...
    ->getFormFactory();

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

Чтобы узнать общие детали об отображении форм, см. How to Customize Form Rendering.

Перевод¶

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

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

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

1

$ composer require symfony/translation symfony/config

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

use Symfony\Component\Form\Forms;
use Symfony\Component\Translation\Translator;
use Symfony\Component\Translation\Loader\XliffFileLoader;
use Symfony\Bridge\Twig\Extension\TranslationExtension;

// создаёт Переводчик
$translator = new Translator('en');
// как-то загружает некоторые переводы в него
$translator->addLoader('xlf', new XliffFileLoader());
$translator->addResource(
    'xlf',
    __DIR__.'/path/to/translations/messages.en.xlf',
    'en'
);

// добавляет TranslationExtension (даёт нам фильтры trans и transChoice)
$twig->addExtension(new TranslationExtension($translator));

$formFactory = Forms::createFormFactoryBuilder()
    // ...
    ->getFormFactory();

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

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

Валидация¶

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

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

1

$ composer require symfony/validator

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

use Symfony\Component\Form\Forms;
use Symfony\Component\Form\Extension\Validator\ValidatorExtension;
use Symfony\Component\Validator\Validation;

$vendorDirectory = realpath(__DIR__.'/../vendor');
$vendorFormDirectory = $vendorDirectory.'/symfony/form';
$vendorValidatorDirectory = $vendorDirectory.'/symfony/validator';

// создаёт валидатор - детали будут отличаться
$validator = Validation::createValidator();

// существуют встроенные переходы для базовых сообщений ошибок
$translator->addResource(
    'xlf',
    $vendorFormDirectory.'/Resources/translations/validators.en.xlf',
    'en',
    'validators'
);
$translator->addResource(
    'xlf',
    $vendorValidatorDirectory.'/Resources/translations/validators.en.xlf',
    'en',
    'validators'
);

$formFactory = Forms::createFormFactoryBuilder()
    // ...
    ->addExtension(new ValidatorExtension($validator))
    ->getFormFactory();

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

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

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

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

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

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

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

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

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

1
2
3
4
5

{{ form_start(form) }}
    {{ form_widget(form) }}

    <input type="submit" />
{{ form_end(form) }}

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

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

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

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

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

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

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

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

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

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

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

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

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

Доступ к ошибкам формы¶

Вы можете использовать метод getErrors(), чтобы получить доступ к списку ошибок. Он возвращает экземпляр FormErrorIterator:

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

$form = ...;

// ...

// экземпляр FormErrorIterator, но только ошибки, связанные с этим
// уровнем формы (например, глобальные ошибки)
$errors = $form->getErrors();

// экземпляр FormErrorIterator, но только ошибки, связанные с
// полем "firstName"
$errors = $form['firstName']->getErrors();

// экземпляр FormErrorIterator в плоской структуре
// использовать getOrigin(), чтобы определить форму, вызывающую ошибу
$errors = $form->getErrors(true);

// экземпляр FormErrorIterator, представляющий структуру древа формы
$errors = $form->getErrors(true, false);

Clearing Form Errors¶

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

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