Symfony2Book10：表单

对于Web开发者来说，处理HTML表单是最常见的任务（也是挑战）之一。Symfony2集成了Form组件以使得表单处理更为容易。在本章中，你将从头开始构建一个复杂的表单，并且学会表单库中大部分的重要功能。

Symfony2表单组件是一个独立库，它可以在Symfony2项目之外使用。更多详情参见Github中的Symfony2表单组件。

创建一个简单的表单

假设你正在构建一个商店应用程序，它需要显示产品。因为你的用户需要编辑和创建产品，你将需要构建一个表单。但在你开始之前，让我们关注一下Product类，该类代表和保存单个产品的数据：

1. // src/Acme/StoreBundle/Entity/Product.php 
2. namespace Acme\StoreBundle\Entity; 
3.  
4. class Product 
5. { 
6.     public $name; 
7.  
8.     protected $price; 
9.  
10.     public function getPrice() 
11.     { 
12.         return $this->price; 
13.     } 
14.  
15.     public function setPrice($price) 
16.     { 
17.         $this->price = $price; 
18.     } 
19. } 

注：如果你要编写这个例子，那么请确保创建和启动AcmeStoreBundle。运行下列命令并按照屏幕的指示进行：

1. php app/console init:bundle Acme/StoreBundle src/ 

这种类通常被称为“简单PHP对象”（POPO），因为到目前为止它并没有与Symfony2或其它任何库相关。它是个非常简单的，要直接为你应用程序解决问题的标准PHP对象（如它在你的应用程序里代表产品）。当然在本章最后，你将可以提供数据到Product实例（通过表单），验证它的数据，并将其持久化到数据库。

截止到现在，你并没有做任何与“表单”相关的操作，你只是简单地创建了一个PHP类，该类将帮助你解决你应用程序中的问题。本章表单构建的目标是允许你的用户与Product对象的数据交互。

构建表单

现在你已经创建了一个Product类，下一步就是创建并渲染实际的HTML表单。在Symfony2中，可以通过构建Form对象，然后在模板中渲染来实现。这一切都可以通过一个内部的控制器来实现：

1. // src/Acme/StoreBundle/Controller/DefaultController.php 
2. namespace Acme\StoreBundle\Controller; 
3.  
4. use Symfony\Bundle\FrameworkBundle\Controller\Controller; 
5. use Acme\StoreBundle\Entity\Product; 
6.  
7. class DefaultController extends Controller 
8. { 
9.     public function indexAction() 
10.     { 
11.         // create a product and give it some dummy data for this example 
12.         $product = new Product(); 
13.         $product->name = 'Test product'; 
14.         $product->setPrice('50.00'); 
15.  
16.         $form = $this->createFormBuilder($product) 
17.             ->add('name', 'text') 
18.             ->add('price', 'money', array('currency' => 'USD')) 
19.             ->getForm(); 
20.  
21.         return $this->render('AcmeStoreBundle:Default:index.html.twig', array( 
22.             'form' => $form->createView(), 
23.         )); 
24.     } 
25. } 

稍后，当你为Product对象添加验证时，你将学会配置表单项更简便的方法。该方法将在后面表单项类型猜测一节说明。

在Symfony2中构建一个表单是简便的，因为Form对象是通过“表单构造器”来构造的。表单构造器是一个对象，你可以与之交互用来帮助你容易地创建表单对象。

在本例中，你已经为你表单添加了两个表单项，name和price，它们与Porduct类的name和price属性相对应。表单项name是文本类型，意味着用户可以提交简单本文到该项。price是money类型，这是个一特殊的文本类型，可以用区域货币格式显示并提交。Symfony2附带了许多内建类型，我们稍后讨论（参见内建表单项类型）

现在表单已经创建了，下一步就是去渲染它。这一点可以很容易做到。只需要通过发送特殊的表单“视图”对象到你的模板（参见上面控制器中的$from->createView()方法），并使用一些表单帮手函数：

1. {# src/Acme/StoreBundle/Resources/views/Default/index.html.twig #} 
2.  
3. <form action="{{ path('store_product') }}" method="post" {{ form_enctype(form) }}> 
4.     {{ form_widget(form) }} 
5.  
6.     <input type="submit" /> 
7. </form> 

就是这样！通过打印from_widget(form)，表单中的每个伴着标签和最终错误消息的表单项都被渲染。因为它如此容易，所以它（还）不是很灵活。稍后，你将学会如何自定义表单输出。

在继续之前，注意如何渲染name输入表单项，该表单项拥有来自$product对象（如："Test product”）的name属性值。表单的第1项工作：从对象得到数据并将它转换成适当的格式，以便在HTML表单中渲染。

表单系统足够智能，可以通过Product类中的getPrice()和setPrice()方法来访问保护属性price的值。除非属性是公共的，否则它必须有"getter"和"setter“方法，以便表单组件可以取得和设置属性。对于布尔属性而言，你可以使用"isser"方法（如isPublished()）来代替"getter"方法（如getPublished()）。

处理表单提交

表单的第2项工作就是将用户提交的数据返回到对象的属性。为了做到这一点，用户提交的数据必须被限定。在你控制器中添加以下功能：

1. public function indexAction() 
2. { 
3.     // just setup a fresh $product object (no dummy data) 
4.     $product = new Product(); 
5.  
6.     $form = $this->createFormBuilder($product) 
7.         ->add('name', 'text') 
8.         ->add('price', 'money', array('currency' => 'USD')) 
9.         ->getForm(); 
10.  
11.     $request = $this->get('request'); 
12.     if ($request->getMethod() == 'POST') { 
13.         $form->bindRequest($request); 
14.  
15.         if ($form->isValid()) { 
16.             // perform some action, such as save the object to the database 
17.  
18.             return $this->redirect($this->generateUrl('store_product_success')); 
19.         } 
20.     } 
21.  
22.     // ... 
23. } 

 

现在，当提交表单时，控制器会将提交的数据绑定到表单，它将把数据送回给$product对象的name和price属性。这一切通过bindRequest()方法完成。

bindRequest()一被调用，提交的数据就被立即传送给底层对象。举个例子，假定 name表单项的值Foo被提交：

1. $product = new Product(); 
2. $product->name = 'Test product'; 
3.  
4. $form->bindRequest($this->get('request')); 
5. echo $product->name; 

上面的语句将echo Foo，因为bindRequest最终将提交的数据传返回给$product对象。

该控制器遵循一个处理表单的通用模式，有三种可能的路径：

1. 当在浏览器中最初引导表单时，请求方法是GET，这意味着表单可以很方便地被创建和渲染（但没有限制）；
2. 当用户提交表单时（如方法是POST），但提供的数据是无效的（验证将在下一节说明），表单被限制，然后被渲染，这时显示所有的验证错误；
3. 当用户提交有效数据的表单时，表单被限制，在重定向用户到其它页（如“谢谢”或“成功”页面）之前，你有机会用$Product对象去执行一些操作（如将其持久化到数据库）。

在成功提交表单之后将用户重定向可以防止用户去点击“刷新”按钮并再次提交数据。

表单验证

在上一节，你学到了用表单来提交有效数据或无效数据会如何。在Symfony2中 ,验证被应用于底层对象（如：Product）。换句话说，问题不是“表单”是否合法，而是表单提交数据给$product之后，该对象是否合法。调用$form->isValid()是询问$product对象是否拥有有效数据的快捷方法。

验证可以通过向类添加一个工具集（称为限制）来实现。在本例中，添加验证限制以便name表单项不能为空，price表单项不能为空且必须是非负数：

1. Acme\StoreBundle\Entity\Product: 
2.     properties: 
3.         name: 
4.             - NotBlank: ~ 
5.         price: 
6.             - NotBlank: ~ 
7.             - Min: 0 

就是这样！如果你使用非法数据重新提交表单，你将看到表单会打印出相应的错误。

如果你有看一下生成的HTML代码，你会发现Form组件会生成的HTML5新字段中包含了特殊的"required"属性，它可以通过Web浏览器来直接强制进行一些验证。一些现代浏览器如Firefox4、Chrome3.0或Opera9.5理解这一特殊的"required"属性。

验证是Symfony2一个非常强大功能，并拥有它自己独立的章节。

内建表单项类型

Symfony2标配了大量的表单项类型，它涵盖了所有的常见表单项以及你所遇到的数据类型：

 

常用表单项类型选项

你也许注意到price表单项是附带着选项数组发送的：

1. ->add('price', 'money', array('currency' => 'USD')) 

每个字段类型有大量的选项是可以随之一起发送。对于每个类型而言，它们许多都指定了表单项的类型和细节，这样都可以在文档中找到。然而，一些选项也在大多数表单项中共享：

• required [type: Boolean, default: true]

  required选项可以用来渲染成HTML5的required属性. 注意它是独立于表单验证的：如果你在表单项包含了required属性，但忽略了required验证，那么该对象将在你的应用程序中显示一个空值。换句话说，这是一个很好地功能，可以为支持HTML5的浏览器提供基于客户端的验证。然而，这并不能代替服务端验证。

• max_length [type: integer]

  该选项被用于添加max_length属性，该属性通过浏览器来限制表单项中文本的长度。

表单类型猜测

现在你已经为Produce类添加了验证元数据，Symfony2已经知道一点关于你表单项的情况。如果你允许，Symfony2可以“猜”你表单项的类型，并为你设置它。在本例中，Symfony2将从验证规则中猜出name和price表单项是正常的文本选项。因为对于name表单项来说是对的，所以你可以修改你的代码以便Symfony2为你猜表单项：

1. public function indexAction() 
2. { 
3.     $product = new Product(); 
4.  
5.     $form = $this->createFormBuilder($product) 
6.         ->add('name') 
7.         ->add('price', 'money', array('currency' => 'USD')) 
8.         ->getForm(); 
9. } 

name表单项的文本类型现在已被忽略，因为它能被验证规则正确地猜出。然而price表单项仍然保持money类型，因为它比系统能够猜出的（text）更特殊。

createBuilder()方法最多需要3个参数（但只有第一个是必须的）：

在模板中渲染表单

到目前为止，你已经看到了整个表单是如何通过一行代码就被渲染的。当然，在渲染时你需要更多的灵活性：

1. {# src/Acme/StoreBundle/Resources/views/Default/index.html.twig #} 
2.  
3. <form action="{{ path('store_product') }}" method="post" {{ form_enctype(form) }}> 
4.     {{ form_errors(form) }} 
5.  
6.     {{ form_row(form.name) }} 
7.     {{ form_row(form.price) }} 
8.  
9.     {{ form_rest(form) }} 
10.  
11.     <input type="submit" /> 
12. </form> 

让我们看看每个部分：

• form_enctype(form) - 如果至少有一个文件上传的表单项，那么这个渲染就必须强制为enctype="multipart/form-data"；
• form_errors(form) - 渲染整个表单的全局错误（特定表单项的错误将显示在该表单项的后面）；
• form_row(form.price) - 渲染标签、错误和指定表单项（如price）的HTML表单部件；
• form_rest(form) - 渲染任何尚未渲染的表单项。这通常是个好主意：在每个表单的底部放置对该帮手函数的调用（如果你忘记输出一个表单项或者不想手工渲染隐藏表单项）。该帮手函数在利用自动进行CSRF攻击保护方面也是很有用的。

大部分工作已经通过form_row帮手函数完成了。在缺省状态下，该函数可以渲染在div标识中的标签、错误和每个表单项的HTML表单部件。在表单主题化一节，你将学习form_row输出是如何在许多不同等级上定制。

手工渲染每个表单项

form_row 帮手函数是有用的，因为它可以使你非常快速地渲染你表单中的每个表单项（为"row"使用的标识还可以自定义）但是生活并不总是简单的，你也可以手工渲染整个表单的表单项：

1. {{ form_errors(form) }} 
2.  
3. <div> 
4.     {{ form_label(form.name) }} 
5.     {{ form_errors(form.name) }} 
6.     {{ form_widget(form.name) }} 
7. </div> 
8.  
9. <div> 
10.     {{ form_label(form.price) }} 
11.     {{ form_errors(form.price) }} 
12.     {{ form_widget(form.price) }} 
13. </div> 
14.  
15. {{ form_rest(form) }} 

如果自动生成的表单项标签并不正确，你也可以指定它：

1. {{ form_label(form.name, 'Product name') }} 

最后，一些有着附加渲染选项的表单项类型被发送到部件。这些选项记录着每个类型，但一个常用的选项是attr，可以让你去修改表单元素的属性。下面的例子将name_field类添加到输入文本表单项中：

1. {{ form_widget(form.name, { 'attr': {'class': 'name_field'} }) }} 

创建Form类

如你所见，可以在控制器中直接创建表单并使用它。然而更好地方法是在独立、隔离的PHP类中构建表单，然后该类可以在你应用程序的任何地方重用。创建一个新类将包含构建产品表单的逻辑：

1. // src/Acme/StoreBundle/Form/ProductType.php 
2.  
3. namespace Acme\StoreBundle\Form; 
4.  
5. use Symfony\Component\Form\AbstractType; 
6. use Symfony\Component\Form\FormBuilder; 
7.  
8. class ProductType extends AbstractType 
9. { 
10.     public function buildForm(FormBuilder $builder, array $options) 
11.     { 
12.         $builder->add('name'); 
13.         $builder->add('price', 'money', array('currency' => 'USD')); 
14.     } 
15. } 

 

这个新类包含所有创建产品表单所需要的语句。它也被用于在控制器中快速构建表单对象：

1. // src/Acme/StoreBundle/Controller/DefaultController.php 
2.  
3. // add this new use statement at the top of the class 
4. use Acme\StoreBundle\Form\ProductType; 
5.  
6. public function indexAction() 
7. { 
8.     $product = // ... 
9.     $form = $this->createForm(new ProductType(), $product); 
10.  
11.     // ... 
12. } 

你也可以通过setData()方法在表单上设置数据：

1. $form = $this->createForm(new ProductType()); 
2. $form->setData($product); 

 

如果你使用setData方法，并想利用表单项类型猜测，那么请确保在你的表单类中添加了下列内容：

1. public function getDefaultOptions(array $options) 
2. { 
3.     return array( 
4.         'data_class' => 'Acme\StoreBundle\Entity\Product', 
5.     ); 
6. } 

 

这是必须的，因为在表单项类型猜测之后对象将被发送给表单。

将表单逻辑放置到它自己的类中意味着表单可在很容易地在你应用程序的任何地方重用。这是创建表单的最好方式，但选择权最终在你。

表单和Doctrine

表单的目标就是从对象（如Product）将数据转换成HTML表单，然后将用户提交的数据传回原始对象。因此将Product对象持久化到数据库和表单是完全无关的。如果你已经配置成通过Doctrine持久化Product类，那么当表单提交之后，如果表单有效，那么将实现持久化：

1. if ($form->isValid()) { 
2.     $em = $this->get('doctrine')->getEntityManager(); 
3.     $em->persist($product); 
4.     $em->flush(); 
5.  
6.     return $this->redirect($this->generateUrl('store_product_success')); 
7. } 

如果因为某种原因，你没有权限访问你的原始$product对象，你将从表单中实现它：

1. $product = $form->getData(); 

更多信息请参见Doctrine ORM章节

关键是要理解当表单被绑定时，提交的数据被立即传送给底层对象。如果你想持久化数据，你只需要简单地去持久化对象本身（已经包含了提交的数据）即可。

如果表单的底层对象（如Product）被Doctrine ORM映射，那么表单框架可以利用信息，元数据验证，去猜特定的表单项类型。

内嵌表单

通常，你想要构建包含许多不同的对象的表单项。举个例子，注册表单也许包含隶属于User对象和许多Address对象的数据。幸运地是，通过表单组件可以很容易、自然地实现该功能。

内嵌单个对象

假设每个Product都属于单个Category对象：

1. // src/Acme/StoreBundle/Entity/Category.php 
2. namespace Acme\StoreBundle\Entity; 
3.  
4. use Symfony\Component\Validator\Constraints as Assert; 
5.  
6. class Category 
7. { 
8.     /** 
9.      * @Assert\NotBlank() 
10.      */ 
11.     public $name; 
12. } 

Product类有一个新的$category属性，说明它属于哪个Category：

1. use Symfony\Component\Validator\Constraints as Assert; 
2.  
3. class Product 
4. { 
5.     // ... 
6.  
7.     /** 
8.      * @Assert\Type(type="Acme\StoreBundle\Entity\Category") 
9.      */ 
10.     protected $category; 
11.  
12.     // ... 
13.  
14.     public function getCategory() 
15.     { 
16.         return $this->category; 
17.     } 
18.  
19.     public function setCategory(Category $category) 
20.     { 
21.         $this->category = $category; 
22.     } 
23. } 

现在更新你的应用程序以反映新的需求，创建一个form类以便Category对象可以被用户修改：

1. // src/Acme/StoreBundle/Form/CategoryType.php 
2. namespace Acme\StoreBundle\Form; 
3.  
4. use Symfony\Component\Form\AbstractType; 
5. use Symfony\Component\Form\FormBuilder; 
6.  
7. class CategoryType extends AbstractType 
8. { 
9.     public function buildForm(FormBuilder $builder, array $options) 
10.     { 
11.         $builder->add('name'); 
12.     } 
13.  
14.     public function getDefaultOptions(array $options) 
15.     { 
16.         return array( 
17.             'data_class' => 'Acme\StoreBundle\Entity\Category', 
18.         ); 
19.     } 
20. } 

 

name表单项的类型已经从Category对象的元数据验证中被猜出（作为文本表单项）。

最终目标是让Product的Category在产品表单中修改正确。为了做到这一点，将category表单项添加到ProductType对象，它的类型是新建的CategoryType类的一个实例：

1. public function buildForm(FormBuilder $builder, array $options) 
2. { 
3.     // ... 
4.  
5.     $builder->add('category', new CategoryType()); 
6. } 

CategoryType的表单项现在可以与来自ProductType类的其它表单项一起被渲染。与渲染原始Product表单项一样渲染Category表单项：

1. {# ... #} 
2. {{ form_row(form.price) }} 
3.  
4. <h3>Category</h3> 
5. <div class="category"> 
6.     {{ form_row(form.category.name) }} 
7. </div> 
8.  
9. {{ form_rest(form) }} 
10. {# ... #} 

当用户提交表单时，Category表单项所提交的数据被合并进Category对象中。换句话说，正如主Product对象一样，一切正常。Category实例可以通过$product->getCategory()访问，并且可以被持久化到数据库或按你所需来使用。

内嵌一个表单集

你也可以在一个表单中内嵌一个表单集。这可以通过使用collection表单项类型来实现。假设你有一个属性叫reviews，对应的类叫ProductReviewType，你可以在下面的ProductType中实现：

1. public function buildForm(FormBuilder $builder, array $options) 
2. { 
3.     // ... 
4.  
5.     $builder->add('reviews', 'collection', array( 
6.        'type'       => new ProductReviewType(), 
7.     )); 
8. } 

表单主题化

表单渲染的每一步都是可以自定义的。你可以自由改变每个表单“row“的渲染、改变用于渲染错误的标识，甚至自定义一个将被渲染的textarea标签。没有什么不能做到，并且不同的定制可以用于不同的地方。

Symfony2使用模板来渲染表单的每一部分。在Twig中，表单每一个不同的部分，如row、textarea标签和错误，是通过Twig的“区块”来显示的。要定制表单渲染的每一步，你只需要覆写相应的区块即可。

为了理解它是如何工作的，让我们定制一个form_row输出，并向包括每个row的div元素添加类属性。要做到这一点，创建一个有着新标识的新模板文件：

1. {# src/Acme/StoreBundle/Resources/views/Form/fields.html.twig #} 
2. {% extends 'TwigBundle:Form:div_layout.html.twig' %} 
3.  
4. {% block field_row %} 
5. {% spaceless %} 
6.     <div class="form_row"> 
7.         {{ form_label(form) }} 
8.         {{ form_errors(form) }} 
9.         {{ form_widget(form) }} 
10.     </div> 
11. {% endspaceless %} 
12. {% endblock field_row %} 

field_row区块是通过form_row函数渲染大多数表单项所使用的区域名。要使用该模板中定义的field_row区块，在渲染该表单的模板上方添加下列面容：

1. {# src/Acme/StoreBundle/Resources/views/Default/index.html.twig #} 
2. {% form_theme form 'AcmeStoreBundle:Form:fields.html.twig' %} 
3.  
4. <form ...> 

form_theme标签“导入”到模板，在渲染表单时可以使用所有与表单相关区块。换句话说，当模板的form_row被稍后调用时，它将从fields.html.twig模板中使用field_row区块。

要自定义表单的任何部分，你仅需要去覆写相应的区块。精确地知道要覆写哪个区块是下一节的内容。

在接下来的一节中，你将学到更多关于如何自定义表单的不同部分。为了能进行更加广泛地讨论，请参见在Twig模板中如何定制表单渲染。

全局表单主题化

到目前为止，你已经知道如何在模板使用form_theme的Twig区块去自定义表单。你也可以告诉Symfony2在你的应用程序中的所有模板去自动使用某些自定义表单。要从先前创建的fields.html.twig模板中自动包含自定义区块，请修改你的配置文件：

1. # app/config/config.yml 
2. twig: 
3.     form: 
4.         resources: ['AcmeStoreBundle:Form:fields.html.twig'] 
5.     # ... 

任何在fields.html.twig模板中的区块现在被全局地用于定义表单输出。

在单个文件中自定义表单输出

你也可以在模板中拥有根据需要自定义表单区块的权力。但注意这种方法仅当模板通过{% extends %}来继承一些基本模板时才有用：

1. {% extends '::base.html.twig' %} 
2.  
3. {% form_theme form _self %} 
4. {% use 'TwigBundle:Form:div_layout.html.twig' %} 
5.  
6. {% block field_row %} 
7.     {# custom field row output #} 
8. {% endblock field_row %} 
9.  
10. {% block content %} 
11.     {# ... #} 
12.  
13.     {{ form_row(form.name) }} 
14. {% endblock %} 

The {% form_theme form_self %} 标签允许在模板中直接定义表单区块。使用这一方法可以快速自定义表单输出，而这只需要在一个模板中定义。

use标签也是有帮助的，它可以让你访问在div_layout.html.twig中定义的所有区块。举个例子，要遵循下面表单自定义，使用use语句是必须的，因为它让你访问在div_layout.html.twig中的attributes区块：

1. {% block text_widget %} 
2.     <div class="text_widget"> 
3.         <input type="text" {{ block('attributes') }} value="{{ value }}" /> 
4.     </div> 
5. {% endblock %}

CSRF攻击保护

CSRF - 或 跨站请求伪造 - 是一种恶意用户尝试提交一个合法用户不知道也不想提交的数据。幸运的是，你可以通过在你表单中使用CSRF令牌来阻止CSRF攻击。

好消息是，缺省情况下，Symfony2为你自动内嵌了验证CSRF令牌。这意味着你可以无须做任何设置就可以使用CSRF保护。实际上，本章中的每一个表单都已经使用了CSRF保护！

CSRF保护通过在你表单中添加一个表单项来实现，这个表单项缺省被称为_token，它包含一个只有你和你用户才知道的值。这样就确保了用户，不是一些其它的实体，提交了数据。Symfony2自动验证令牌以及它的精度。

_token是一个隐藏表单项，如果你在模板中包含了form_rest()函数（该函数确保所有未渲染的表单项被输出），它将被自动渲染。

CSRF令牌可以被自定义，例如：

1. class ProductType extends AbstractType 
2. { 
3.     public function getDefaultOptions(array $options) 
4.     { 
5.         return array( 
6.             'data_class'      => 'Acme\StoreBundle\Entity\Product', 
7.             'csrf_protection' => true, 
8.             'csrf_field_name' => '_token', 
9.             'intention'  => 'product_creation', 
10.         ); 
11.     } 
12. } 

要禁用CSRF保护，将csrf_protection选项设为false。也可以在你项目中进行全局定制。更多信息请参见表单配置参考一节。

intention选项是可选的，但是通过在不同表单中设置不同的值，它可以极大地提高生成令牌的安全性。