表单

配置表单¶

目前有了 Task 类，下一步创建HTML表单。在Symfony里，这一步将通过创建一个表单对象后然后在模板里渲染它来实现。现在可以直接在Controller里完成:

// src/AppBundle/Controller/DefaultController.php
namespace AppBundleController;

use SymfonyBundleFrameworkBundleControllerController;
use AppBundleEntityTask;
use SymfonyComponentHttpFoundationRequest;

class DefaultController extends Controller
{
    public function newAction(Request $request)
    {
        // create a task and give it some dummy data for this example
        $task = new Task();
        $task->setTask('Write a blog post');
        $task->setDueDate(new DateTime('tomorrow'));

        $form = $this->createFormBuilder($task)
            ->add('task', 'text')
            ->add('dueDate', 'date')
            ->add('save', 'submit', array('label' => 'Create Task'))
            ->getForm();

        return $this->render('default/new.html.twig', array(
            'form' => $form->createView(),
        ));
    }
}

创建表单不需要太多代码因为Symfony的“表单创建器”做了创建表单工作。表单创建器的目的就是让你想写“食谱”一样定义表单，然后就没有然后了，创建器来做剩下的重活儿。

在这个例子里，你在表单中添加了 task 和 dueDate 两个字段，正好对应了 Task 类类的两个属性。同时你也定义了两个字段的显示类型（比如 text，date），决定了该用什么HTML标签来生成字段。

最后，你添加好了一个的提交按钮，还是自定义按钮文字的呢。

Symfony内置超多字段类型，之后我们会介绍（请看 内置表单字段类型）。

生成表单¶

创建好表单后让我们来展现它，我们将传递表单的“view”对象给模板（注意 $form->createView() ）然后使用form相关的助手函数：

三行搞定！

• form_start(form)

• 显示form的开始tag，如有上传文件字段还会包含enctype属性哦

• form_widget(form)

• 显示所有的字段，包括字段本身和label标签，以及错误信息

• form_end(form)

• 显示表单结束的tag以及所有表单里有，但是目前还没有被显示的字段。这个功能超级对于显示隐藏字段超级好用，比如说 CSRF Protection

继续之前，注意 task 输入框里的值是如何从 $task 对象里获取过来的。form的第一个职责就是从对象属性里获取数据，并且绑定到表单对应的字段的值

表单提交的处理¶

Form的第二职责是将用户提交数据转化回对象，为此表单需将用户用户提交数据写入表对象中:

// ...
use SymfonyComponentHttpFoundationRequest;

public function newAction(Request $request)
{
    // just setup a fresh $task object (remove the dummy data)
    $task = new Task();

    $form = $this->createFormBuilder($task)
        ->add('task', 'text')
        ->add('dueDate', 'date')
        ->add('save', 'submit', array('label' => 'Create Task'))
        ->getForm();

    $form->handleRequest($request);

    if ($form->isValid()) {
        // perform some action, such as saving the task to the database

        return $this->redirectToRoute('task_success');
    }

    // ...
}

此控制器展现了除了表单的常见思路，包含3中方式：

1. 当页面被载入时，表单只是被创建然后被显示。 handleRequest() 方法能感知表单没有被提交，然后直接让 isValid() 返回 false

2. 如果用户提交表单， handleRequest() 也能感知到，然后立马把提交的数据转换成 $task 对象 task 和 dueDate 属性的值。当然如果数据校验出问题了（数据校验将在下一小节介绍） isValid() 方法也会返回 false ，然后表单将重新传给模板重新显示，并且包含了所有错误信息。

   注解

   你可以使用 isSubmitted() 来检查表单是否被提交，无论表单能否通过校验。

3. 如果用户再次提交表单信息，提交的数据也在此写入表单对象中，如果这次通过了校验，那么 isValid 会返回 true 了，我们便可以通过 $task 对象在跳转到“提交成功”页之前做一些事情（比如存个库啥的）

   注解

   表单成功提交跳转到其他页面有一个好处就是防止用户点击“刷新”按钮重复提交数据

多按钮表单¶

如果你的表单包含不止一个按钮，而且你又想知道哪一个按钮被点了，你可以这样:

$form = $this->createFormBuilder($task)
    ->add('task', 'text')
    ->add('dueDate', 'date')
    ->add('save', 'submit', array('label' => 'Create Task'))
    ->add('saveAndAdd', 'submit', array('label' => 'Save and Add'))
    ->getForm();

在你的Controller里使用 isClicked() 方法来判断“Save and add”按钮是不是被点击过:

if ($form->isValid()) {
    // ... perform some action, such as saving the task to the database

    $nextAction = $form->get('saveAndAdd')->isClicked()
        ? 'task_new'
        : 'task_success';

    return $this->redirectToRoute($nextAction);
}

• YAML

  # AppBundle/Resources/config/validation.yml
  AppBundleEntityTask:
      properties:
          task:
              - NotBlank: ~
          dueDate:
              - NotBlank: ~
              - Type: DateTime
  

• Annotations

  // AppBundle/Entity/Task.php
  use SymfonyComponentValidatorConstraints as Assert;
  
  class Task
  {
      /**
       * @AssertNotBlank()
       */
      public $task;
  
      /**
       * @AssertNotBlank()
       * @AssertType("DateTime")
       */
      protected $dueDate;
  }
  

• XML

  <!-- AppBundle/Resources/config/validation.xml -->
  <?xml version="1.0" encoding="UTF-8"?>
  <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping
          http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
  
      <class name="AppBundleEntityTask">
          <property name="task">
              <constraint name="NotBlank" />
          </property>
          <property name="dueDate">
              <constraint name="NotBlank" />
              <constraint name="Type">DateTime</constraint>
          </property>
      </class>
  </constraint-mapping>
  

• PHP

  // AppBundle/Entity/Task.php
  use SymfonyComponentValidatorMappingClassMetadata;
  use SymfonyComponentValidatorConstraintsNotBlank;
  use SymfonyComponentValidatorConstraintsType;
  
  class Task
  {
      // ...
  
      public static function loadValidatorMetadata(ClassMetadata $metadata)
      {
          $metadata->addPropertyConstraint('task', new NotBlank());
  
          $metadata->addPropertyConstraint('dueDate', new NotBlank());
          $metadata->addPropertyConstraint(
              'dueDate',
              new Type('DateTime')
          );
      }
  }
  

HTML5 验证

对于HTML5来说，许多浏览器已经实现了在客户端做本地校验。最常见的就是在表单字段上添加 required 属性。只要浏览器支持此HTML5新属性，就会提示你必须输入此字段才能提交。

虽然在客户端通过HTML也可以添加校验了，但有时你也许要把客户端的校验关闭，比如说在测试服务器端的校验功能的时候。此时需要给form标签添加 novalidate 属性，或者在提交按钮上添加 formnovalidate 属性。

验证规则组¶

如果你的对象使用了 validation groups ，你将在表单里设置需要使用哪个校验组来校验。

$form = $this->createFormBuilder($users, array(
    'validation_groups' => array('registration'),
))->add(...);

如果你正创建 form classes （这是最佳实践），你需要添加以下代码到 configureOptions() 方法:

use SymfonyComponentOptionsResolverOptionsResolver;

public function configureOptions(OptionsResolver $resolver)
{
    $resolver->setDefaults(array(
        'validation_groups' => array('registration'),
    ));
}

在这两种情况下， 只有 registration 校验组会被使用。

关闭验证功能¶

有时你需要忽略校验，此时你可以设置 validation_groups 选项为 false:

use SymfonyComponentOptionsResolverOptionsResolver;

public function configureOptions(OptionsResolver $resolver)
{
    $resolver->setDefaults(array(
        'validation_groups' => false,
    ));
}

注意一点如果你这么设置后，表单依然会跑一些基础检查。比如提交文件是否太大，或者一些必填项没填。如果你想完全忽略任何检查，你可以使用 POST_SUBMIT event 。

基于提交数据的验证规则分组¶

如果你程序要一些逻辑来决定使用什么校验组（比如通过提交的数据），你可以通过给 validation_groups 指定回调函数的方式实现。

use SymfonyComponentOptionsResolverOptionsResolver;

// ...
public function configureOptions(OptionsResolver $resolver)
{
    $resolver->setDefaults(array(
        'validation_groups' => array(
            'AppBundleEntityClient',
            'determineValidationGroups',
        ),
    ));
}

在表单提交后，进行校验前， Client 类的 determinValidationGroups() 方法将会被调用。表单对象将被作为一个参数（请看下一个例子）被传如该方法。你也可以直接传入匿名方法。

use AcmeAcmeBundleEntityClient;
use SymfonyComponentFormFormInterface;
use SymfonyComponentOptionsResolverOptionsResolver;

// ...
public function configureOptions(OptionsResolver $resolver)
{
    $resolver->setDefaults(array(
        'validation_groups' => function(FormInterface $form) {
            $data = $form->getData();
            if (Client::TYPE_PERSON == $data->getType()) {
                return array('person');
            }

            return array('company');
        },
    ));
}

使用 validation_groups 参数来重载默认的校验组。如果你也希望使用默认的校验规则，你需要调整一些选项:

use AcmeAcmeBundleEntityClient;
use SymfonyComponentFormFormInterface;
use SymfonyComponentOptionsResolverOptionsResolver;

// ...
public function configureOptions(OptionsResolver $resolver)
{
    $resolver->setDefaults(array(
        'validation_groups' => function(FormInterface $form) {
            $data = $form->getData();
            if (Client::TYPE_PERSON == $data->getType()) {
                return array('Default', 'person');
            }

            return array('Default', 'company');
        },
    ));
}

你可以找到更多的关于校验组以及默认校验的信息在 validation groups

基于提交按钮的验证规则分组¶

如果表单包含不止一个提交按钮，你可以通过按钮来决定校验组。比如说有些带步骤的表单，可能提供上一步按钮，如果上一步按钮被点击，就不应该使用校验，但是数据还是应该保存。

首先，我们需要添加两个按钮:

$form = $this->createFormBuilder($task)
    // ...
    ->add('nextStep', 'submit')
    ->add('previousStep', 'submit')
    ->getForm();

接着，我们需要配置上一步按钮运行某个特殊的校验组。在这个例子中，我们希望它压根就不校验，所以我们设置 validation_groups 为false:

$form = $this->createFormBuilder($task)
    // ...
    ->add('previousStep', 'submit', array(
        'validation_groups' => false,
    ))
    ->getForm();

这时表单将跳过校验。但他依然会执行一些基础检查，比如是否上传过大的文件，或者在数字类型字段里输入了非数字。

文字类¶

• text
• textarea
• email
• integer
• money
• number
• password
• percent
• search
• url

选择类¶

• choice
• entity
• country
• language
• locale
• timezone
• currency

Date and Time Fields¶

• date
• datetime
• time
• birthday

其他类¶

• checkbox
• file
• radio

Field Groups¶

• collection
• repeated

Hidden Fields¶

• hidden

按钮类¶

• button
• reset
• submit

Base Fields¶

• form

你也可以创建你自己的表单字段类型。这在 How to Create a Custom Form Field Type 有讨论

表单字段选项¶

每一个字段类型都有一堆选项。比如说 dueDate 字段就被显示成三个下拉菜单。不过， date field 可以被设置为一个文字输入框，这样用户就可以直接输入时间文字了:

->add('dueDate', 'date', array('widget' => 'single_text'))

每一个表单字段有一堆选项独有的选项可以设置，它们在文档里都可以查到。

->add('dueDate', 'date', array(
    'widget' => 'single_text',
    'label'  => 'Due Date',
))

警告

如果你的表单将使用某个特别的校验组，字段类型推测功能依然是从所有的验证规则里去猜测你的字段类型（即包括所使用的校验规则之外的规则）。

表单字段选项自动预测¶

除了能推测类型，Symfony也可以推测选项。

• required

• required 选项可以通过校验规则猜测出来（比如 NotBlank 或者 NotNull）甚至是通过Doctrine的配置信息（比如 nullable）。非常方便得让你的客户端和服务端有相同的校验规则。

• max_length

• 如果是文字输入框， max_length 将被推测出来（通过 Length 或者 Range）甚至是Doctrine的配置信息 （通过响应属性的 length 信息）。

如果你想改变其中某一个猜测的选项，你可以通过传入选项数组去覆盖它。

->add('task', null, array('attr' => array('maxlength' => 4)))

• Twig

  {# app/Resources/views/default/new.html.twig #}
  {{ form_start(form) }}
      {{ form_errors(form) }}
  
      {{ form_row(form.task) }}
      {{ form_row(form.dueDate) }}
  {{ form_end(form) }}
  

• PHP

  <!-- app/Resources/views/default/newAction.html.php -->
  <?php echo $view['form']->start($form) ?>
      <?php echo $view['form']->errors($form) ?>
  
      <?php echo $view['form']->row($form['task']) ?>
      <?php echo $view['form']->row($form['dueDate']) ?>
  <?php echo $view['form']->end($form) ?>
  

小技巧

您可以通过 form.vars.value 来访问当前的数据：

手动生成每一个表单字段¶

The form_row helper is great because you can very quickly render each field of your form (and the markup used for the “row” can be customized as well). But since life isn’t always so simple, you can also render each field entirely by hand. The end-product of the following is the same as when you used the form_row helper:

If the auto-generated label for a field isn’t quite right, you can explicitly specify it:

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

If you need to render form fields “by hand” then you can access individual values for fields such as the id, name and label. For example to get the id:

To get the value used for the form field’s name attribute you need to use the full_name value:

Twig函数参考¶

If you’re using Twig, a full reference of the form rendering functions is available in the reference manual. Read this to know everything about the helpers available and the options that can be used with each.

注解

This example assumes that you’ve created a route called target_route that points to the controller that processes the form.

• Twig

  {# app/Resources/views/default/new.html.twig #}
  {{ form_start(form, {'action': path('target_route'), 'method': 'GET'}) }}
  

• PHP

  <!-- app/Resources/views/default/newAction.html.php -->
  <?php echo $view['form']->start($form, array(
      'action' => $view['router']->generate('target_route'),
      'method' => 'GET',
  )) ?>
  

注解

If the form’s method is not GET or POST, but PUT, PATCH or DELETE, Symfony will insert a hidden field with the name _method that stores this method. The form will be submitted in a normal POST request, but Symfony’s router is capable of detecting the _method parameter and will interpret it as a PUT, PATCH or DELETE request. Read the cookbook chapter “How to Use HTTP Methods beyond GET and POST in Routes” for more information.

警告

The getName() method returns the identifier of this form “type”. These identifiers must be unique in the application. Unless you want to override a built-in type, they should be different from the default Symfony types and from any type defined by a third-party bundle installed in your application. Consider prefixing your types with app_ to avoid identifier collisions.

设置 data_class

Every form needs to know the name of the class that holds the underlying data (e.g. AppBundleEntityTask). Usually, this is just guessed based off of the object passed to the second argument to createForm (i.e. $task). Later, when you begin embedding forms, this will no longer be sufficient. So, while not always necessary, it’s generally a good idea to explicitly specify the data_class option by adding the following to your form type class:

use SymfonyComponentOptionsResolverOptionsResolver;

public function configureOptions(OptionsResolver $resolver)
{
    $resolver->setDefaults(array(
        'data_class' => 'AppBundleEntityTask',
    ));
}

小技巧

When mapping forms to objects, all fields are mapped. Any fields on the form that do not exist on the mapped object will cause an exception to be thrown.

In cases where you need extra fields in the form (for example: a “do you agree with these terms” checkbox) that will not be mapped to the underlying object, you need to set the mapped option to false:

use SymfonyComponentFormFormBuilderInterface;

public function buildForm(FormBuilderInterface $builder, array $options)
{
    $builder
        ->add('task')
        ->add('dueDate', null, array('mapped' => false))
        ->add('save', 'submit');
}

Additionally, if there are any fields on the form that aren’t included in the submitted data, those fields will be explicitly set to null.

在Controller里可以这样访问表单字段数据:

$form->get('dueDate')->getData();

另外，没有被映射的字段也可以直接被修改:

$form->get('dueDate')->setData(new DateTime());

将表单定义为Service¶

将表单定义为服务是一个好习惯，他将让表单变得更好用

搞定！ 现在你可以直接在Controller里使用你自己的表单类型

// src/AppBundle/Controller/DefaultController.php
// ...

public function newAction()
{
    $task = ...;
    $form = $this->createForm('task', $task);

    // ...
}

甚至可以在其他表单中使用:

// src/AppBundle/Form/Type/ListType.php
// ...

class ListType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        // ...

        $builder->add('someTask', 'task');
    }
}

移步至 Creating your Field Type as a Service 了解更多。

只嵌单个表单¶

假如 Task 属于某个 Category 对象，首先我们得有一个 Category 对象:

// src/AppBundle/Entity/Category.php
namespace AppBundleEntity;

use SymfonyComponentValidatorConstraints as Assert;

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

接下来，给 Task 类添加 category 属性:

// ...

class Task
{
    // ...

    /**
     * @AssertType(type="AppBundleEntityCategory")
     * @AssertValid()
     */
    protected $category;

    // ...

    public function getCategory()
    {
        return $this->category;
    }

    public function setCategory(Category $category = null)
    {
        $this->category = $category;
    }
}

Now that your application has been updated to reflect the new requirements, create a form class so that a Category object can be modified by the user:

// src/AppBundle/Form/Type/CategoryType.php
namespace AppBundleFormType;

use SymfonyComponentFormAbstractType;
use SymfonyComponentFormFormBuilderInterface;
use SymfonyComponentOptionsResolverOptionsResolver;

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

    public function configureOptions(OptionsResolver $resolver)
    {
        $resolver->setDefaults(array(
            'data_class' => 'AppBundleEntityCategory',
        ));
    }

    public function getName()
    {
        return 'category';
    }
}

The end goal is to allow the Category of a Task to be modified right inside the task form itself. To accomplish this, add a category field to the TaskType object whose type is an instance of the new CategoryType class:

use SymfonyComponentFormFormBuilderInterface;

public function buildForm(FormBuilderInterface $builder, array $options)
{
    // ...

    $builder->add('category', new CategoryType());
}

The fields from CategoryType can now be rendered alongside those from the TaskType class.

使用跟显示 Task 同样的方式来显示 Category 的表单字段：

When the user submits the form, the submitted data for the Category fields are used to construct an instance of Category, which is then set on the category field of the Task instance.

The Category instance is accessible naturally via $task->getCategory() and can be persisted to the database or used however you need.

内嵌一组表单¶

You can also embed a collection of forms into one form (imagine a Category form with many Product sub-forms). This is done by using the collection field type.

For more information see the “How to Embed a Collection of Forms” cookbook entry and the collection field type reference.

• Twig

  {# app/Resources/views/form/fields.html.twig #}
  {% block form_row %}
  {% spaceless %}
      <div class="form_row">
          {{ form_label(form) }}
          {{ form_errors(form) }}
          {{ form_widget(form) }}
      </div>
  {% endspaceless %}
  {% endblock form_row %}
  

• PHP

  <!-- app/Resources/views/form/form_row.html.php -->
  <div class="form_row">
      <?php echo $view['form']->label($form, $label) ?>
      <?php echo $view['form']->errors($form) ?>
      <?php echo $view['form']->widget($form, $parameters) ?>
  </div>
  

• Twig

  {# app/Resources/views/default/new.html.twig #}
  {% form_theme form 'form/fields.html.twig' %}
  
  {% form_theme form 'form/fields.html.twig' 'form/fields2.html.twig' %}
  
  {# ... render the form #}
  

• PHP

  <!-- app/Resources/views/default/new.html.php -->
  <?php $view['form']->setTheme($form, array('form')) ?>
  
  <?php $view['form']->setTheme($form, array('form', 'form2')) ?>
  
  <!-- ... render the form -->
  

表单函数命名规则¶

Symfony会把表单的每一个部分都生成HTML表单代码，比如错误信息，表单名称，等等。而定义他们的是某一个Twig文件的表单模板模块集合，或者一堆PHP写的模板文件。

Twig里每一个表单模块都定义在 Twig Bridge 的一个模板文件里（比如 form_div_layout.html.twig ），你可以在此文件里看到表单的每一个字段的默认模板。

在PHP代码里，表单片段都是写单独的模板文件。默认都放在framework bundle的 Resources/views/Form 中（ view on GitHub ）。

每一个片段名都是同样的规律：分成两个部分，并且用一个下划线分割。一些例子：

• form_row - used by form_row to render most fields;
• textarea_widget - used by form_widget to render a textarea field type;
• form_errors - used by form_errors to render errors for a field;

Each fragment follows the same basic pattern: type_part. The type portion corresponds to the field type being rendered (e.g. textarea, checkbox, date, etc) whereas the part portion corresponds to what is being rendered (e.g. label, widget, errors, etc). By default, there are 4 possible parts of a form that can be rendered:

只要知道字段的类型叫什么（比如 textarea），以及你想自定义的地方（比如 widget），你就可以猜出它的名字重载它了 （比如 textarea_widget）。

Template片段继承¶

某些情况，你想自定义的片段可能会找不到，比如说，默认模板没有 textarea_errors 片段。那么textarea的错误怎么自定义呢？

答案是： 通过 form_errors 片段。当Symfony显示textare错误的时候，它会先查找 textarea_errors 片段，然后查找 form_errors。每一个表单字段都有一个 父 类型（ textarea 的父类是 text，text 的父类是 form），如果本身的的错误类型无法找到，Symfony将会使用父类的错误类型。

所以如果要只重载 textarea 的错误信息，复制 form_errors 片段，将其重命名为 textarea_errros 然后修改它。如果要重载 所有 的错误信息，复制后直接修改 form_errors 。

全局表单主题¶

在以上的例子中，你需要用 form_theme 助手方法（Twig）来引入自定义的模板片段。你也可以让Symfony在整个项目里都加载你自定义的模板。

{% extends 'base.html.twig' %}

{# import "_self" as the form theme #}
{% form_theme form _self %}

{# make the form fragment customization #}
{% block form_row %}
    {# custom field row output #}
{% endblock form_row %}

{% block content %}
    {# ... #}

    {{ form_row(form.task) }}
{% endblock %}

注解

intention 为可选项，但如果给每一个表单设置不同的值，会极大提高安全性。

警告

CSRF tokens对于每一个用户都是不一样的，这也意味着如果你想使用页面缓存技术您得注意了。想了解更多请阅读 缓存带CSRF表单的页面 。

小技巧

你也可以通过request对象获取POST的数据（这里为“name”），比如这样:

$request->request->get('name');

不过呢，最好还是用 getData() 方法，因为他返回的是被表单转换化过后的数据。

添加校验规则¶

唯一没提的是校验。通常，当你执行 $form->isValid() 时，对象上的校验规则被读取。但是你得让表和某个对象关联才行（通过 data_class，或者传递一个对象）。请见 校验 查阅更多。

但如果表单并没有关联某个对象，你如何给你的表单添加校验规则呢？

答案是你自己创建校验规则，并且将他们添加到单个的表单字段里。主要目的将在 validation chapter 得以讨论，但这里也有一个简单的演示例子：

use SymfonyComponentValidatorConstraintsLength;
use SymfonyComponentValidatorConstraintsNotBlank;

$builder
   ->add('firstName', 'text', array(
       'constraints' => new Length(array('min' => 3)),
   ))
   ->add('lastName', 'text', array(
       'constraints' => array(
           new NotBlank(),
           new Length(array('min' => 3)),
       ),
   ))
;

new NotBlank(array('groups' => array('create', 'update'))