Компонент Форма¶

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

Чтобы обработать даныные формы, вам понадобится вызвать метод 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';

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

$twig = new Twig_Environment(new Twig_Loader_Filesystem(array(
    $viewsDir,
    $vendorTwigBridgeDir.'/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;

$vendorDir = realpath(__DIR__.'/../vendor');
$vendorFormDir = $vendorDir.'/symfony/form';
$vendorValidatorDir = $vendorDir.'/symfony/validator';

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

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

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

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

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

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

То, как именно вы получит доступ к вашей фабрике форм - зависит от вас. Если вы используете сервис-контейнер (как предоставленный с компонентом 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, но только ошибки, связанные с этим
// уровнем формы (например, "global errors)
$errors = $form->getErrors();

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

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

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