对于一个Web开发者来说，处理HTML表单是一个最为普通又具挑战的任务。Symfony2集成了一个Form组件，让处理表单变的容易起来。在这一节里，我们将
从基础开始创建一个复杂的表单，学习表单类库中最重要的内容。
Symfony2 的Form组件是一个独立的类库，你可以在Symfony2项目之外使用它。
创建一个简单的表单：
假设你要创建一个应用程序的todo列表，需要显示一些任务。因为你的用户需要编辑和创建任务，所以你需要创建一个表单。在你开始之前，首先来看通用的Task类，用来表示和存储一个单一任务的数据：
// src/Acme/TaskBundle/Entity/Task.php
namespace Acme\TaskBundle\Entity;
class Task
{
protected $task;
protected $dueDate;
public function getTask()
{
return $this->task;
}
public function setTask($task)
{
$this->task = $task;
}
public function getDueDate()
{
return $this->dueDate;
}
public function setDueDate(\DateTime $dueDate = null)
{
$this->dueDate = $dueDate;
}
}
如果你是按照我们提供的示例编码，那么你需要先创建一个AcmeTaskBundle：
$ php app/console generate:bundle --namespace=Acme/TaskBundle
该类是一个普通的PHP对象类，因为他们没有任何Symfony或者其它类库引用。非常简单的一个PHP对象类，它直接解决的是你程序中表现task的数据。当然，在本节的最后，你将能够通过HTML表单提交一个Task实例数据，校验它的数值，并把它持久化到数据库。
创建一个Form
现在已经创建了一个Task类，下一步就是创建和渲染一个真正的HTML表单了。在symfony2中，它是通过创建一个表单对象并渲染到模板的。现在，可以从controller内部处理form。
//src/Acme/TaskBundle/Controller/DefaultController.php
namespace Acme\TaskBundle\Controller;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Symfony\Component\HttpFoundation\Request;
use Acme\TaskBundle\Entity\Task;
class DefaultController extends Controller
{
//创建一个任务并给它一些假数据作为示例
$task = new Task();
$task->setTask('Write a blog post');
$task->setDueDate(new \DateTime('tomorrow'));
$form = $this->createFormBuilder($task)
->add('task','text')
->add('dueDate','date')
->getForm();
return $this->render('AcmeTaskBundle:Default:new.html.twig',array(
'form' =>$form->createView(),
));
}
上面的示例显示了如何直接在Controller中创建一个表单，为了可以让表单重用你完全可以在一个单独的类文件中创建表单。
因为Symfony2通过一个表单生成器“form builder"来创建表单对象，所以你可以使用很少的代码就能完成创建表单任务。表单生成器的目的是让你能编写简单的表单创建方法，让它来负责繁重的创建任务。
在这个示例中，你已经添加了两个字段到你的表单，一个是task一个是dueDate。它们关联到Task类的task和dueDate属性。你已经为它们分别指定了类型（比如，text，date等），由这些类型来决定为这些字段生成什么样的HTML表单标签。
Symfony2 拥有许多内建的类型，接下来我们将简单的介绍。
渲染一个表单
表单创建以后，下一步就是渲染它。这是通过传递一个特定的表单”view"对象（就是上例中的 $form->createView()返回的view对象）到你的模板并通过一些列的表单帮助函数来实现的。
Twig格式：
{# src/Acme/TaskBundle/Resources/views/Default/new.html.twig #}
PHP代码格式：
在这里假设你已经创建了一个名叫task_new的路由指向AcmeTaskBundle:Default:new Controller。
就是这些了，通过打印form_widget(form),表单中的每个字段都会被渲染出来。同时还有一个文本标签和错误信息。是不是很简单，不过现在它还不够灵活。通常情况下，我们渴望单独渲染表单中的每一个字段，这样我们可以更好的控制表单的样式。我们会在在模板中渲染表单一节介绍。
在继续下去之前，我们注意到，为什么我们渲染出来的task输入框中有一个来自$task对象的属性值“Write a blog post"。这是表单的第一个工作：从一个对象中获取数据并把它转换为合适的格式渲染到一个HTML表单中。
注意，表单系统已经足够聪明，它们能够通过像getTask()和setTask()方法来访问Task类中受保护的属性task。除非一个是公共属性，否则必须有一个getter和setter方法被定义来用于表单组件从这些属性中获取和保持数据。对于布尔型的属性，你可以使用一个”isser"方法（比如 isPublished())替代getter方法(getPublished())。
处理表单提交
表单系统的第二个任务就是传递用户提交的数据回到一个对象的属性中。要做到这一点，用户提交的数据必须绑定到表单才行。添加如下代码到你的Controller类：
//...
public function newAction(Request $request)
{
//只是创建一个新的$task对象（不需要假数据）
$task = new Task();
$form= $this->createFormBuilder($task)
->add('task','text')
->add('dueDate','date')
->getForm();
if($request->getMethod() == "POST"){
$form->bindRequest($request);
if($form->isValid()){
//执行一些行为，比如保持task到数据库
return $this->redirect($this->generateUrl('task_success'));
}
}
//...
}
现在，当表单被提交时，Controller可以绑定被提交的数据到表单，表单会把数据传回$task对象的task和dueDate属性。这些都在bindRequest()方法中完成。只要bindRequest()方法被调用，提交的数据就会立刻被传输到底层对象。不管数据是否被真正的校验通过。
controller一般会遵循一个通用的模式来处理表单，它有三个可能的途径：
1.当在浏览器初始加载一个页面时，请求方法是GET，表单处理仅仅是创建和渲染。
2.当用户提交带有不合法数据的表单（方法为POST)时，表单会并绑定然后渲染，这时候显示所有校验错误。
3.当用户提交的表单带有的数据均合法时，表单绑定并且在页面跳转之前你有机会去使用数据去执行一些业务逻辑活动，比如持久化它到数据库）。
表单校验
在前面我们提到了，如何提交一个带有合法数据和非法数据的表单。在Symfony2中，校验是在底层对象上进行的。换句话说，form表单合法与否不重要，主要看在表单提交数据以后，底层对象比如$task对象是否合法。调用$form->isvalid() 是一个询问底层对象是否获得合法数据的快捷方式。
校验是通过添加一些列规则（约束）到一个类来完成的。我们给Task类添加规则和约束，使它的task属性不能为空，duDate字段不能空并且是一个合法的DateTime对象。
YAML格式：
# Acme/TaskBundle/Resources/config/validation.yml
Acme\TaskBundle\Entity\Task:
properties:
task:
- NotBlank: ~
dueDate:
- NotBlank: ~
- Type: \DateTime
在Task类中声明格式：
// Acme/TaskBundle/Entity/Task.php
use Symfony\Component\Validator\Constraints as Assert;
class Task
{
/**
* @Assert\NotBlank()
*/
public $task;
/**
* @Assert\NotBlank()
* @Assert\Type("\DateTime")
*/
protected $dueDate;
}
XML格式：
\DateTime
PHP代码格式：
// Acme/TaskBundle/Entity/Task.php
use Symfony\Component\Validator\Mapping\ClassMetadata;
use Symfony\Component\Validator\Constraints\NotBlank;
use Symfony\Component\Validator\Constraints\Type;
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属性来监控校验。客户端校验可以通过添加novalidate属性到form标签或者formnovalidate 到提交标签而关闭。这对你想检查服务端校验规则时非常有用。
校验分组
如果你的对象想从校验组中受益，你需要指定你的表单使用哪个校验组。
$form = $this->createFormBuilder($users, array(
'validation_groups' => array('registration'),
))->add(...)
;
如果你创建表单类，你需要添加羡慕的getDefaultOptions()方法：
public function getDefaultOptions(array $options)
{
return array(
'validation_groups' => array('registration')
);
}
在这两种情况下，只有registration 校验组将被用于校验底层对象。
内建字段类型
Symfony标准版含有大量的字段类型，它们几乎涵盖了所有通用表单的字段和数据类型。
文本字段：
text
textarea
email
integer
money
number
password
percent
search
url
选择字段：
choice
entity
country
language
locale
timezone
日期和时间字段：
date
datetime
time
birthday
其它字段：
checkbox
file
radio
字段组：
collection
repeated
隐藏字段：
hidden
csrf
基础字段：
field
form
当然，你也可以定义自己的字段类型。
字段类型选项
每一个字段类型都有一定数量的选项用于配置。比如，dueDate字段当前被渲染成3个选择框。而日期字段可以被配置渲染成一个单一的文本框，用户可以输入字符串作为日期。
->add('dueData','data', array('widget' = 'single_text'))
required选项:
最常用到的选项是required选项，它可以应用于任何字段。默认情况下它被设置为true。这就意味着支持HTML5的浏览器会使用客户端校验来判断字段是否为空。如果你不想让它发生，或者把在你的字段上把required选项设置为false，或者关闭HTML5校验。设置required为true并不意味着服务端校验被应用。换句话说，如果用户提交一个空数值到该字段，它将接受这个控制除非你使用Symfony的NotBlank或者NotNull校验约束。也就是说，required选项是很好，但是服务端校验还是要继续用。
label选项：
表单字段可以使用label选项设置显示字符标签，可以应用于任何字段：
->add('dueDate', 'date',array(
'widget' =>'single_text',
'label' => 'Due Date',
))
字段类型猜测：
现在你已经添加了校验元数据到Task类，Symfony早已经了解一点关于你的字段了。如果你允许，Symfony可以猜到你的字段数据类型并为你设置它。在下面的例子中，Symfony可以根据校验规则猜测到task字段是一个标准的text字段，dueDate是date字段。
public function newAction()
{
$task = new Task();
$form = $this->createFormBuilder($task)
->add('task')
->add('dueDate', null, array('widget' => 'single_text'))
->getForm();
}
当你省略了add方法的第二个参数（或者你输入null)时，Symfony的猜测能力就起作用了。如果你输入一个选项数组作为第三个参数（比如上面的dueDate),那么这些选项会成为Symfony猜测的依据。如果你的表单使用了指定的校验数组，字段类型猜测器将还是要考虑所有的校验规则来综合猜测你的字段类型。
字段类型可选项猜测
除了猜测字段类型，Symfony还能是这猜测一些可选项字段值。当这些可选项被设置时，字段将会被渲染到特定HTML属性中，让HTML5客户端来提供校验。
然而，它们不会在服务端生成相应的校验规则。尽管你需要手动的在服务端添加这些规则，但是这些字段类型选项还是能根据这些信息猜测到。
required： required规则可以在校验规则或者Doctrine元数据的基础上猜测到。这当你的客户端校验将自动匹配你的校验规则时很有用。
max_length: 如果字段是一些列文本字段，那么max_length选项可以从校验规则或者Doctrine元数据中猜到。
如果你喜欢改变一个猜到的数值，你可以通过在可选项数组中传递该选项来重写它。
->add('task',null, array('max_length'=>4))
在模板中渲染表单
到目前为止，我们已经看了一个完整的表单是如何通过一行代码被渲染的。当然，你通常需要更加灵活的渲染方式：
Twig格式：
{# src/Acme/TaskBundle/Resources/views/Default/new.html.twig #}
PHP代码格式：
让我们看看这组代码的详细：
form_enctype(form) 只要有一个字段是文件上传，那么它就会义务的设置为 enctype="multipart/form-data";
form_errors(form) 渲染任何整个form的任何错误信息(特定字段的错误，会显示在每个字段的下面一行）。
form_row(form.dueDate) 默认情况下，为给定的字段在一个p中渲染一个文本标签，任何错误，和HTML表单部件。
form_rest(form) 渲染没有指出的其余任何字段，通常在表单的末尾调用它防止遗忘或者渲染一些你不愿意手动设置的隐藏字段。它同时还能为我们提供CSRF保护。
大部分工作是由form_row帮助方法类完成的，它默认在一个p中为每个字段渲染显示标签，错误信息和HTML表单部件。
注意，你可以通过form.vars.value 来访问你当前是表当数据：
Twig格式：
{{ form.vars.value.task }}
PHP代码格式：
<?php echo $view['form']->get('value')->getTask() ?>
手工渲染每一个表单字段
form_row帮助器能让你很快的渲染你表单中的每一个字段，并且每一行可以被自定义化。但是生活不总是那么简单的，你也可能要手动的渲染每一个字段。
Twig格式：
{{ form_errors(form) }}
{{ form_label(form.task) }}
{{ form_errors(form.task) }}
{{ form_widget(form.task) }}
{{ form_label(form.dueDate) }}
{{ form_errors(form.dueDate) }}
{{ form_widget(form.dueDate) }}
{{ form_rest(form) }}
PHP代码格式:
<?php echo $view['form']->errors($form) ?><?php echo $view['form']->label($form['task']) ?> <?php echo $view['form']->errors($form['task']) ?> <?php echo $view['form']->widget($form['task']) ?>
<?php echo $view['form']->label($form['dueDate']) ?> <?php echo $view['form']->errors($form['dueDate']) ?> <?php echo $view['form']->widget($form['dueDate']) ?>
<?php echo $view['form']->rest($form) ?>
如果自动生成显示标签不准确，那么你可以显式的指定它：
Twig格式：
{{ form_label(form.task, 'Task Description') }}
PHP代码格式：
<?php echo $view['form']->label($form['task'], 'Task Description') ?>
一些字段类型有一些额外的渲染选项可以传入widget，一个常用的选项为attr，它允许你修改表单元素的属性。下面的示例将添加task_field class到渲染的文本输入字段：
Twig格式：
{{ form_widget(form.task, {'attr': {'class':'task_field'} }) }}
PHP代码格式：
<?php echo $view['form']->widget($form['task'], array(
'attr' => array('class' => 'task_field'),
)) ?>
如果你想手工渲染表单字段，你可以单独访问每个字段的值，比如id,name和label，这里我们获取id
Twig格式：
{{ form.task.vars.id }}
PHP代码格式：
<?php echo $form['task']->get('id') ?>
需要获取表单字段名称属性你需要使用full_name值：
Twig格式：
{{ form.task.vars.full_name }}
PHP代码格式：
<?php echo $form['task']->get('full_name') ?>
创建表单类
正如你看到的，一个表单可以直接在controller类中被创建和使用。然而，一个更好的做法是在一个单独的PHP类中创建表单。它可以被重用到你应用程序的任何地方。创建一个新类来保存生成task表单的逻辑：
// src/Acme/TaskBundle/Form/Type/TaskType.php
namespace Acme\TaskBundle\Form\Type;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilder;
class TaskType extends AbstractType
{
public function buildForm(FormBuilder $builder, array $options)
{
$builder->add('task');
$builder->add('dueDate', null, array('widget' => 'single_text'));
}
public function getName()
{
return 'task';
}
}
这个新类包含了所有创建一个task表单所需要的内容，注意getName()方法将返回一个该表单类型的唯一标识，用于快速创建该表单。
// src/Acme/TaskBundle/Controller/DefaultController.php
// 在类上添加这个新的引用语句
use Acme\TaskBundle\Form\Type\TaskType;
public function newAction()
{
$task = // ...
$form = $this->createForm(new TaskType(), $task);
// ...
}
设置data_class
每个表单都需要知道它底层保存数据的类名称，（比如Acme\TaskBundle\Entity\Task)。通常情况下，是根据createForm方法的第二个参数来猜测的。以后，当你开始嵌入表单时，这个可能就不怎么充分了，所以，通常一个好的方法是通过添加下面代码到你的表单类型类来显式的指定data_class 选项。
public function getDefaultOptions(array $options)
{
return array(
'data_class' => 'Acme\TaskBundle\Entity\Task',
);
}
当然，这种做法也不总是必须的。
当你映射表单到一个对象是，所有的字段都被映射。 表单的任何字段如果在映射的对象上不存在那么就会造成抛出异常。在这种情况下，你需要在表单中获取字段（比如，一个“你同意这些说法吗？”复选框）将不能映射到底层对象，那么你需要设置property_path为false以避免抛出异常。
public function buildForm(FormBuilder $builder, array $options)
{
$builder->add('task');
$builder->add('dueDate', null, array('property_path' => false));
}
另外，如果有任何的表单字段没有被包含着提交的数据中，那么这些字段需要显式的设置为null。
在controller类中我们可以访问字段数据：
$form->get('dueDate')->getData();
Forms和Doctrine
表单的目的是把数据从一个底层对象传递给一个HTML表单然后把用户提交的数据传回到原先的底层对象。因此，底层对象把数据持久化到数据库就跟表单没有任何的关系了。但是，如果你已经配置了底层类是通过Doctrine来持久化，（你已经定义了映射元数据在底层类），接下来当表单提交数据后，当表单合法后就可以持久化它了。
if ($form->isValid()) {
$em = $this->getDoctrine()->getEntityManager();
$em->persist($task);
$em->flush();
return $this->redirect($this->generateUrl('task_success'));
}
如果处于某种原因，你不想访问原有的$task对象，你可以从表单中直接获取数据：
$task = $form->getData();
在这里，关键要理解当表单跟底层对象绑定后，用户提交的数据会立刻传递给底层对象。如果你想持久化这些数据，你只需要持久化对象本身即可。
嵌入式表单：（Embedded Forms)
通常，你可能想生成一个表单，它包含来自不同对象的字段。比如，一个注册表单可能包含属于User对象和Address对象的字段。幸运的是，这些对于form组件来说都是很容易很自然的事。嵌入一个单独对象：假设每个Task属于一个Category对象，首先创建这个Category对象：
// src/Acme/TaskBundle/Entity/Category.php
namespace Acme\TaskBundle\Entity;
use Symfony\Component\Validator\Constraints as Assert;
class Category
{
/**
* @Assert\NotBlank()
*/
public $name;
}
接下来，添加一个新的category属性到Task类：
// ...
class Task
{
// ...
/**
* @Assert\Type(type="Acme\TaskBundle\Entity\Category")
*/
protected $category;
// ...
public function getCategory()
{
return $this->category;
}
public function setCategory(Category $category = null)
{
$this->category = $category;
}
}
现在我们来相应我们应用程序的一个新需求，需要创建一个 表单可以让用户修改Category对象。
// src/Acme/TaskBundle/Form/Type/CategoryType.php
namespace Acme\TaskBundle\Form\Type;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilder;
class CategoryType extends AbstractType
{
public function buildForm(FormBuilder $builder, array $options)
{
$builder->add('name');
}
public function getDefaultOptions(array $options)
{
return array(
'data_class' => 'Acme\TaskBundle\Entity\Category',
);
}
public function getName()
{
return 'category';
}
}
我们的最终目的是能够让用户在Task表单中修改Category对象，所以，我们需要添加一个类型为CategoryType表单类的category字段到TaskType 表单类。
public function buildForm(FormBuilder $builder, array $options)
{
// ...
$builder->add('category', new CategoryType());
}
这时我们可以在TaskType类字段渲染的旁边渲染CategoryType类的字段了：
Twig格式:
{# ... #}
Category
{{ form_row(form.category.name) }}
{{ form_rest(form) }}
{# ... #}
PHP代码格式：
Category
<?php echo $view['form']->row($form['category']['name']) ?>
<?php echo $view['form']->rest($form) ?>
当用户提交表单时，提交的Category字段数据被用于创建一个Category实例，然后被设置到Task实例的category字段。该Category实例可以通过Task实例来访问,同时也能被持久化到数据或者用作它用。
$task->getCategory()
嵌入一个表单集合
你也可以将一个表单集合嵌入到一个表单（想象一个Category 表单和许多Product子表单）。它是通过一个字段类型集合类实现的。
表单主题化
表单的每一部分渲染都是可以被自定义个性化的。你可以自由的改变每一个表单行的渲染，改变渲染错误的标志，更或者是textarea标签应该怎样显示等。没有任何限制，不同的个性化设置能用到不同的区域。
Symfony使用模板渲染每一个或者部分表单，比如label标签，input标签，错误信息以及任何其它内容。在Twig中，每个表单片段会被一个Twig block来渲染。要个性化渲染表单，你只需要重写相应的block即可。在PHP模板中，它是通过单独的模板文件来渲染表单片段的，所以你需要通过编写新的模板来替代旧的模板即可。在理解了它们是怎么工作的之后，让我们来个性化form_row片段并添加一个class属性到包裹每一表单行的p元素。首先创建一个新模板文件用于存放新的标志：
Twig格式：
{# src/Acme/TaskBundle/Resources/views/Form/fields.html.twig #}
{% block field_row %}
{% spaceless %}
{{ form_label(form) }}
{{ form_errors(form) }}
{{ form_widget(form) }}
{% endspaceless %}
{% endblock field_row %}
PHP代码格式：
<?php echo $view['form']->label($form, $label) ?> <?php echo $view['form']->errors($form) ?> <?php echo $view['form']->widget($form, $parameters) ?>
field_row表单片段会在通过form_row函数渲染大部分的表单字段时使用。 要告诉你的表单组件使用你的新的field_row片段，需要添加下面的内容到你渲染该表单的模板顶部：
Twig格式：
{# src/Acme/TaskBundle/Resources/views/Default/new.html.twig #}
{% form_theme form 'AcmeTaskBundle:Form:fields.html.twig' %}
{% form_theme form 'AcmeTaskBundle:Form:fields.html.twig' 'AcmeTaskBundle:Form:fields2.html.twig' %}
京公网安备 11010802040832号 | 京ICP备19059560号-6 