4. 视图及其模型
到目前为止,动作都是自己生成响应:文本、JSON,以及写成字符串的少量 HTML 标签。在 MVC 应用程序中,这是视图的职责:一个描述页面 HTML 的文件,其中带有占位符,用于放置动作传给它的数据——即视图的模型。
[Symfony] 使用同一团队创建的 [Twig] 视图引擎。[Twig] 视图是一个文件,其名称以 [.html.twig] 结尾(输出格式,后跟引擎),存放在应用程序的 [templates] 文件夹中。它是一个文本文件——这里是 HTML——其中有三类标签会在服务器端被解释:
- [{{ expression }}]:表达式的值,插入到页面中;
- [{% instruction %}]:一条指令 (标签);条件([{% if %}]);循环([{% for %}])、模板继承([{% extends %}]、[{% block %}])、包含([{% include %}])等;
- [{# comment #}]:注释,不会出现在生成的页面中。
其余内容原样复制。表达式不是用 [PHP] 编写的,而是用 [Twig] 的语言,它更简单也更安全:[model.title] 指的是对象 [model] 的属性 [title](或其方法 [getTitle()],或数组的键 [title] :[Twig] 会自行查找);过滤器 转换一个值([name|upper] 将姓名转为大写);函数 执行计算([path('home')] 生成一个 URL)。[Twig] 因此类似于 [Jinja2] ([Flask])——它从中汲取了灵感——或 [Django] 的引擎;它不同于 [Blade] ([Laravel])和 [Razor] ([ASP.NET Core]),后两者把 HTML 与宿主语言的代码混合在一起。[Twig] 视图不能执行任意的 [PHP] 代码:它只能显示传给它的数据。这是有意为之的设计:应用程序逻辑保留在各个类中。视图并不是每次请求都被解释:首次使用时,[Twig] 会将其编译为一个 [PHP] 类,存放在 [var/cache/dev/twig] 文件夹中,只要视图不变就会重复使用它。我们稍后会看到这个文件是什么样子。
4.1. 示例 13:第一个视图
| 13-first-view/
├── config/
│ ├── packages/
│ │ ├── framework.yaml
│ │ └── twig.yaml
│ └── bundles.php
├── src/
│ ├── Controller/
│ │ └── ViewsController.php
│ ├── Model/
│ │ └── PageModel.php
│ └── Kernel.php
├── templates/
│ └── views/
│ ├── unknown.html.twig
│ └── index.html.twig
└── ...
|
4.1.1. 配置:config/bundles.php 和 config/packages/twig.yaml
[Twig] 通过一个 Bundle([Symfony] 的 TwigBundle)集成到 Symfony 中,必须将它添加到应用程序的 Bundle 列表中(示例 01):
| <?php
// config/bundles.php:应用程序的 Bundle;TwigBundle 集成了
// Twig 视图引擎
return [
Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
Symfony\Bundle\TwigBundle\TwigBundle::class => ['all' => true],
];
|
并进行配置:
| # config/packages/twig.yaml:TwigBundle 的配置
twig:
# 视图所在的文件夹
default_path: '%kernel.project_dir%/templates'
|
唯一的键指定视图文件夹:[templates],位于项目文件夹中。这也是默认值。在标准项目中,这两个文件由 [Symfony Flex] 在安装 [Twig] 时创建([composer require twig],参见引言)。
4.1.2. 视图模型:src/Model/PageModel.php
| <?php
// src/Model/PageModel.php:视图的模型,即操作传递给视图的数据
namespace App\Model;
readonly class PageModel
{
public function __construct(
public string $title,
public string $message,
public string $time,
) {
}
}
|
视图模型是一个简单的不可变类(参见示例 03):包含视图将要显示的三项信息。并不要求把视图的模型定义为类:也可以把三个独立的变量传给视图。不过,类可以说明视图期望什么,并让编辑器能够检查动作的代码。案例研究将采用这种做法,每个重要的视图都有自己的模型类。
4.1.3. 控制器:src/Controller/ViewsController.php
| <?php
// src/Controller/ViewsController.php:返回视图的操作
namespace App\Controller;
use App\Model\PageModel;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
#[Route(methods: ['GET'])]
class ViewsController extends AbstractController
{
// render:Twig 引擎根据视图模板
// templates/views/index.html.twig 以及数组中传递的变量(这里
// 只有一个,[model])构建页面;生成的页面就是响应的主体
#[Route('/', name: 'index')]
public function index(): Response
{
$model = new PageModel(
'My first view',
'This page was built by Twig, on the server.',
date('H:i:s'));
return $this->render('views/index.html.twig', ['model' => $model]);
}
// 同一个视图配合另一个模型;或者另一个视图,使用 404 状态码
#[Route('/hello/{name}', name: 'hello')]
public function hello(string $name): Response
{
if ($name === 'unknown') {
// render 的第三个参数:要补全的响应,这里设置了 404 状态码
return $this->render('views/unknown.html.twig', ['name' => $name],
new Response(status: Response::HTTP_NOT_FOUND));
}
$model = new PageModel(
"Hello $name",
'This time, the title of the page comes from the URL.',
date('H:i:s'));
return $this->render('views/index.html.twig', ['model' => $model]);
}
}
|
- 第 20–23 行:动作构建视图模型。[date] 函数,源自 [PHP],用于格式化当前时间:[H] 格式化小时,[i] 格式化分钟,[s] 格式化秒;
- 第 24 行:[render] 方法(来自 [AbstractController] )指示 [Twig] 生成页面。第一个参数是视图的名称:即相对于 [templates] 文件夹的文件路径。第二个参数是一个关联数组,其中每个键都会成为视图中的一个变量——这里只有一个:[model]。[render] 返回一个 [Response] 对象,其主体是生成的页面(类型为 [text/html]);
- 第 31–35 行:另一个视图,带有另一个变量([name])。[render] 的第三个参数是一个待填充的响应:这里是用于自定义错误页面的 404 响应。[new Response(status: ...)] 通过命名参数传递状态码,而其他参数保持默认值;
- 第 36–40 行:与 [index] 动作相同的视图,但使用不同的模型。这就是把动作与视图分离的好处:同一个视图可以被多个动作使用。
4.1.4. 视图:templates/views/index.html.twig
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
{# {{ ... }}:表达式的值,插入到页面中 #}
<title>{{ model.title }}</title>
</head>
<body>
<h1>{{ model.title }}</h1>
<p>{{ model.message }}</p>
<p>Page built at {{ model.time }}.</p>
</body>
</html>
|
- 第 5 行:[Twig] 注释;
- 第 6 行:[{{ model.title }}] 插入变量 [model] 的 [title] 属性的值。句点是 [Twig] 的访问运算符,而 [PHP] 写作 [$model->title]。
由 [{{ }}] 插入的所有内容都会被转义:字符 [<]、[>]、[&]、["]和 ['] 会被替换为对应的 HTML 实体。这正是函数 [htmlspecialchars] 在示例 09 中所起的作用,但这次是自动完成的:因此,视图不会不经意地把用户提供的 HTML 插入页面。
4.1.5. 视图:templates/views/unknown.html.twig
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Unknown</title>
</head>
<body>
<h1>Nobody is called [{{ name }}] here.</h1>
</body>
</html>
|
视图不一定要接收对象:变量 [name] 是一个字符串。
4.1.6. 执行


显示的时间对应于 [PHP] 中配置的时区([date.timezone] 指令,位于 [php.ini] 文件中),这里是协调世界时(UTC);案例研究将展示如何为应用程序设置它。原始响应展示了 [Twig] 所做的工作:[{{ }}] 标签已被替换为它们的值,注释已被删除。
| curl -i http://localhost:8000/
|
| HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>My first view</title>
</head>
<body>
<h1>My first view</h1>
<p>This page was built by Twig, on the server.</p>
<p>Page built at 09:31:47.</p>
</body>
</html>
|
“home”错误页面,后接一个包含 HTML 的名称([<b>martin],经 URL 编码):
| curl -i http://localhost:8000/hello/unknown
curl http://localhost:8000/hello/%3Cb%3Emartin
|
| HTTP/1.1 404 Not Found
Content-Type: text/html; charset=UTF-8
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Unknown</title>
</head>
<body>
<h1>Nobody is called [unknown] here.</h1>
</body>
</html>
...
<title>Hello <b>martin</title>
...
<h1>Hello <b>martin</h1>
<p>This time, the title of the page comes from the URL.</p>
...
|
标签 [<b>] 被转义了,尽管动作和视图都没有对它做过任何处理(撇号也被转义了:['])。最后,下面是由 [Twig] 编译的视图,位于 [var/cache/dev/twig] 文件夹中(使用生成的名称,例如 [f1/f1e0ff0a8a0dc68657a0b1aa94f3ef4b.php]),已精简到只剩要点:
| /* views/index.html.twig */
class __TwigTemplate_9c9473b678a753b61e2666e1a8e3a2a4 extends Template
{
...
protected function doDisplay(array $context, array $blocks = []): iterable
{
// line 1
yield "<!doctype html>
<html lang=\"en\">
<head>
<meta charset=\"utf-8\">
";
// line 6
yield " <title>";
yield (string) $this->escaper->escape(CoreExtension::getAttribute($this->env, $this->source,
... $context["model"] ..., "title", ...), "html", null, true);
yield "</title>
...
|
视图已变成一个名为 [PHP] 的类,其方法 [doDisplay] 逐段生成页面([yield])。每个 [{{ model.title }}] 都变成了对 [CoreExtension::getAttribute] 的调用(它查找属性、方法或键 [title]),其结果再传给方法 [escape] (转义)。因此,[Twig] 视图只是编写生成 HTML 的 [PHP] 文件的一种更安全、更易读的方式。
4.2. 示例 14:Twig 语言
本示例将 [Twig] 的主要结构组合到同一个视图中。
4.2.1. 模型与动作
视图的模型由三个不可变类定义,每个类各占一个文件([PHP] 并不要求每个文件一个类,但 [Composer] 的类加载器会在文件 [App\Model\Product] 中查找类 [src/Model/Product.php]):
| <?php
// src/Model/Product.php:一个产品
namespace App\Model;
readonly class Product
{
public function __construct(
public string $name,
public float $price,
public bool $inStock,
) {
}
}
|
| <?php
// src/Model/Address.php:一个地址
namespace App\Model;
readonly class Address
{
public function __construct(
public string $street,
public string $city,
) {
}
}
|
| <?php
// src/Model/BasicsModel.php:示例 14 的视图的模型
namespace App\Model;
readonly class BasicsModel
{
/**
* @param list<Product> $products
* @param list<Product> $cart
*/
public function __construct(
public string $title,
public string $name,
public ?string $nickname,
public string $html,
public bool $loggedIn,
public string $currency,
public array $products,
public array $cart,
public Address $address,
) {
}
}
|
模型包含各种类型的值:字符串、[null]、布尔值、对象数组、空数组,以及包含其他对象的对象。这里的价格类型为 [float],以简化视图中的计算(示例 06 说明了为什么我们更倾向于使用整数分)。
| <?php
// src/Controller/BasicsController.php:一个使用 Twig 主要结构的视图
namespace App\Controller;
use App\Model\Address;
use App\Model\BasicsModel;
use App\Model\Product;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
class BasicsController extends AbstractController
{
#[Route('/', name: 'index', methods: ['GET'])]
public function index(): Response
{
$model = new BasicsModel(
title: 'Twig basics',
name: 'Martin',
nickname: null,
html: '<b>this is HTML</b>',
loggedIn: true,
currency: '€',
products: [
new Product('Keyboard', 25, true),
new Product('Mouse', 12.5, false),
new Product('Screen', 149, true),
],
cart: [],
address: new Address('12 rue des Lilas', 'Angers'));
return $this->render('basics/index.html.twig', ['model' => $model]);
}
}
|
动作使用命名参数 构建模型(参见示例 02):每个值前面都带有它所对应的参数名称,这使得尽管参数很多,调用依然易读。
4.2.2. 视图:templates/basics/index.html.twig
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>{{ model.title }}</title>
</head>
<body>
{# set:视图的变量;reduce 过滤器将价格相加,length 过滤器统计产品数量 #}
{% set total = model.products|reduce((sum, p) => sum + p.price, 0) %}
{% set count = model.products|length %}
<h1>{{ model.title }}</h1>
{# 1. 显示模型的一个值;null 显示为空字符串;
default 过滤器会替换空值。这条 Twig 注释不会出现
在生成的页面中 #}
<p>1. Name: {{ model.name }} - nickname: [{{ model.nickname }}] [{{ model.nickname|default('none') }}]</p>
{# 2. {{ }} 会转义 HTML;raw 过滤器则按原样插入 #}
<p>2a. {{ model.html }}</p>
<p>2b. {{ model.html|raw }}</p>
{# 3. 一个条件 #}
{% if model.loggedIn %}
<p>3. You are logged in.</p>
{% else %}
<p>3. You are not logged in.</p>
{% endif %}
{# 4. 一个循环:loop 变量描述循环的状态 #}
<p>4. Our products:</p>
<ul>
{% for product in model.products %}
<li>no. {{ loop.index0 }}: {{ product.name }}, {{ product.price }} {{ model.currency }}
{{ product.inStock ? '(in stock)' : '(sold out)' }}
{% if loop.first %} - the first one{% endif %}
{% if loop.last %} - the last one, seen by {{ model.name }}{% endif %}
</li>
{% endfor %}
</ul>
{# 5. 空列表:for 循环的 else 块 #}
<p>5. Your cart:
{% for p in model.cart %}<span>{{ p.name }}</span>{% else %} it is empty.{% endfor %}
</p>
{# 6. 计算表达式、set 变量,以及 number_format 过滤器 #}
<p>6. {{ count }} products, for a total of {{ total }} {{ model.currency }};
average price: {{ (total / count)|number_format(2, '.', ',') }} {{ model.currency }}</p>
{# 7. 对象中的对象,以及一个转换为大写的过滤器 #}
<p>7. Address: {{ model.address.street }}, {{ model.address.city|upper }}</p>
{# 8. verbatim:Twig 原样复制、不加解释的文本 #}
<p>8. Braces displayed as is: {% verbatim %}{{ model.name }}{% endverbatim %}</p>
</body>
</html>
|
- 第 9–10 行:[{% set %}] 语句在视图中创建一个变量。总价由过滤器 [reduce]计算,它把数组归约为单个值(类似 [array_reduce],示例 06):其函数接收累加值和当前元素;[(sum, p) => sum + p.price] 是 [Twig] 的箭头函数。过滤器 [length] 返回数组中元素的数量(或字符串中的字符数)。这些计算应仅限于展示目的:计算通常属于动作;
- 第 15 行:[null] 值显示为空字符串。[default] 过滤器用默认值替换空值(或缺失的值);
- 第 17–18 行:[{{ }}] 会转义 HTML(2a);而过滤器 [raw]则按原样插入值,不进行转义(2b)。[raw] 仅用于应用程序自己生成的 HTML,绝不用于用户输入;
- 第 20–24 行:条件:[{% if %}]、[{% elseif %}]、[{% else %}]、[{% endif %}]。每个块都以 [{% end... %}] 语句结束;
- 第 28–34 行:循环 [{% for ... in ... %}] …… [{% endfor %}]。在循环内部,特殊变量 [loop] 描述循环的状态:[loop.index0] (迭代序号,从 0 开始)、[loop.index] (从 1 开始)、[loop.first]、[loop.last] (在第一次和最后一次迭代时为 true)、[loop.length] (元素数量)。循环之外的变量([model.name])仍然可以访问;
- 第 30 行:三元运算符 [condition ? a : b] ([Twig] 也接受 [condition ? a],条件为假时它返回空字符串);
- 第 38 行:[for] 循环可以带有一个 [{% else %}] 块,在列表为空时执行。这比用 [{% if %}] 检查列表长度更简单;
- 第 41–42 行:计算表达式([total / count])以及来自 [set] 的变量。过滤器 [number_format] 用于格式化数字:两位小数,小数点作为小数分隔符,逗号作为千位分隔符。在示例 16 中,我们将看到一种更好的数字和金额格式化方式;
- 第 44 行:句点可以穿透对象([model.address.city]),过滤器 [upper] 将字符串转为大写(并能正确处理带重音的字符);
- 第 46 行:[{% verbatim %}] 指令原样复制其内容而不加解释:当页面包含供 [JavaScript] 框架使用的花括号时,这很有用。
[Twig] 约有五十个过滤器([lower]、[capitalize]、[trim]、[join]、[split]、[slice]、[sort]、[date]、[json_encode]、[escape]……)、约十五个函数([range]、[min]、[max]、[random]……)以及测试 ([is defined]、[is empty]、[is null]、[is iterable]、[is even]……);[Symfony] 的 Bundle 还会增加一些([path]、[asset]、[form_row]、[is_granted]……),应用程序也可以编写自己的(示例 16)。
4.2.3. 执行

生成的页面:
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Twig basics</title>
</head>
<body>
<h1>Twig basics</h1>
<p>1. Name: Martin - nickname: [] [none]</p>
<p>2a. <b>this is HTML</b></p>
<p>2b. <b>this is HTML</b></p>
<p>3. You are logged in.</p>
<p>4. Our products:</p>
<ul>
<li>no. 0: Keyboard, 25 €
(in stock)
- the first one </li>
<li>no. 1: Mouse, 12.5 €
(sold out)
</li>
<li>no. 2: Screen, 149 €
(in stock)
- the last one, seen by Martin </li>
</ul>
<p>5. Your cart:
it is empty. </p>
<p>6. 3 products, for a total of 186.5 €;
average price: 62.17 €</p>
<p>7. Address: 12 rue des Lilas, ANGERS</p>
<p>8. Braces displayed as is: {{ model.name }}</p>
</body>
</html>
|
注释和指令已经消失,但它们留下了空白:[Twig] 会删除标签后面的换行符,但不会删除其前面的缩进。这没有任何影响:浏览器会忽略这些空白。(标签内的连字符——例如 [{%- ... -%}] 或 [{{- ... -}}]——会删除其周围的空白。)插入页面的 [float] 数字使用小数点书写([12.5]);[number_format] 使用传给它的分隔符。
4.3. 示例 15:模板、片段、静态文件
网站的各个页面通常共享相同的结构:页眉、导航栏、页脚,以及相同的样式表。与其在每个视图中重复这种结构,不如在一个模板 (布局)中只写一次,由各个页面继承它。本示例还使用 [Bootstrap],这个使用最广泛的 CSS 框架,来进行布局。
| 15-layout/
├── config/
│ ├── packages/
│ │ └── twig.yaml
│ └── services.yaml
├── public/
│ └── css/
│ └── styles.css
├── src/
│ ├── Controller/
│ │ └── PagesController.php
│ ├── Model/
│ │ └── Member.php
│ └── Kernel.php
├── templates/
│ ├── fragments/
│ │ └── navbar.html.twig
│ ├── layout.html.twig
│ ├── macros.html.twig
│ └── pages/
│ ├── home.html.twig
│ ├── raw.html.twig
│ └── team.html.twig
└── ...
|
4.3.1. 静态文件
HTML 页面会引用其他文件:样式表、[JavaScript] 脚本和图像。这些由服务器原样发送的文件称为静态文件。在 [Symfony] 中,它们存放在 [public] 文件夹中,Web 服务器会原样提供该文件夹中的内容(示例 01):文件 [public/css/styles.css] 可通过 URL [/css/styles.css]访问,无需 [Symfony] 介入。
| /* 在 Bootstrap 之外的一些额外设置 */
body {
background-color: #f5f7fa;
}
/* 布局的页脚 */
.footer {
margin-top: 2rem;
font-size: 0.85rem;
color: #6c757d;
}
/* 错误消息,位于页面底部,背景为浅粉色 */
.error-area {
margin-top: 1.5rem;
padding: 0.75rem 1rem;
background-color: #fdecef;
border: 1px solid #f5c2c7;
border-radius: 0.375rem;
color: #842029;
}
|
在 [Bootstrap] 之外增加的几条 CSS 规则:浅灰色背景、页脚样式,以及将在后续示例中使用的错误区域样式。
[Bootstrap] 用于示例 15 到 28。示例并没有在每个示例的 [public] 文件夹中各放一份副本,而是共享它:它位于 [examples/common/bootstrap] 文件夹中。该文件夹不由 Web 服务器直接提供:由所有这些示例共享的一个控制器来提供其中的文件。这就是文件 [examples/common/BootstrapController.php]:
| <?php
// common/BootstrapController.php:一个提供 Bootstrap 文件的控制器,
// 由示例 15 到 28 共享(examples/common/bootstrap 文件夹),位于
// /bootstrap/... URL 下。这些示例中的每一个都在其
// config/services.yaml 文件中声明它
namespace Common;
use Symfony\Component\HttpFoundation\BinaryFileResponse;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Routing\Requirement\Requirement;
class BootstrapController
{
#[Route('/bootstrap/{file}', name: 'bootstrap', requirements: ['file' => Requirement::CATCH_ALL],
methods: ['GET'])]
public function serve(string $file): BinaryFileResponse
{
$folder = realpath(__DIR__.'/bootstrap');
// realpath:所请求文件的绝对路径,不含 . 和 ..;
// 如果文件不存在则为 false
$path = realpath($folder.'/'.$file);
// 一个存在的文件,并且确实位于该文件夹内(没有用 ../ 跳出该文件夹)
if ($path === false || ! str_starts_with($path, $folder.DIRECTORY_SEPARATOR) || ! is_file($path)) {
throw new NotFoundHttpException("unknown file: $file");
}
// 一个发送文件内容的响应;其类型根据扩展名确定
$response = new BinaryFileResponse($path);
$types = ['css' => 'text/css', 'js' => 'text/javascript', 'map' => 'application/json'];
$response->headers->set('Content-Type', $types[pathinfo($path, PATHINFO_EXTENSION)] ?? 'application/octet-stream');
return $response;
}
}
|
- 第 7 行:该类位于 [Common] 命名空间中,文件 [examples/composer.json] 将它与文件夹 [examples/common] 关联起来(参见引言):因此 [Composer] 的类加载器无论在哪个示例中都能找到它;
- 第 16–17 行:一个路由,其参数 [{file}] 接受任何路径结尾,包括斜杠(示例 02):URL [/bootstrap/css/bootstrap.min.css] 指向文件夹中的 [css/bootstrap.min.css] 文件。该路由名为 [bootstrap];
- 第 20–27 行:提供由 URL 指定的文件需要谨慎:诸如 [/bootstrap/..%2F..%2F15-layout%2F.env] (其中 [/] 被编码为 [%2F])的 URL 绝不能允许访问文件夹之外的文件。[realpath] 函数(属于 [PHP] )计算文件的绝对路径,去除其中的 [.] 和 [..] 部分,如果文件不存在则返回 [false] 。我们验证所得路径是否以文件夹路径开头([str_starts_with]),并且它指向一个文件([is_file]);否则返回 404 错误。[DIRECTORY_SEPARATOR] 是系统的路径分隔符:在 [\] 下为 [Windows],其他系统下为 [/] ;
- 第 29–32 行:[BinaryFileResponse] 对象是发送文件内容的响应。内容类型根据文件扩展名确定(由 [pathinfo] 提供),从而使样式表被正确声明为 [text/css]:浏览器会拒绝被声明为其他类型的样式表。
每个使用 [Bootstrap] 的示例都在其 [config/services.yaml] 文件中将此控制器声明为服务:
| # config/services.yaml:应用程序的服务(见示例 06)
services:
_defaults:
autowire: true
autoconfigure: true
App\:
resource: '../src/'
# 提供 Bootstrap 的控制器,由示例 15 到 28 共享(见示例 15)
Common\BootstrapController: ~
|
- 第 11 行:[Common\BootstrapController] 服务,没有特定配置([~] 是 [null] 在 [YAML] 中的值):它沿用 [_defaults] 中的配置,并且 [autoconfigure] 把它变成控制器,其路由并入应用程序的路由(示例 02)。
4.3.2. 模板:templates/layout.html.twig
| <!doctype html>
{# 页面的布局:页面扩展(EXTEND)它,并填充它的块 #}
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
{# block:页面可以填充的插槽;这里带有默认内容 #}
<title>{% block title %}Home{% endblock %} - {{ site_name }}</title>
{# path():名为 [bootstrap] 的路由的 URL;asset():public/ 中某个文件的 URL #}
<link rel="stylesheet" href="{{ path('bootstrap', {file: 'css/bootstrap.min.css'}) }}">
<link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
<div class="container py-3">
{# 插入 fragments/navbar.html.twig 文件 #}
{% include 'fragments/navbar.html.twig' %}
<main>
{# 操作所请求的页面内容插入在这里 #}
{% block content %}{% endblock %}
</main>
{# app:Symfony 提供给所有视图的变量(当前请求...);
site_name:全局变量(见 config/packages/twig.yaml) #}
<footer class="footer">Page [{{ app.request.pathInfo }}] - © {{ 'now'|date('Y') }} {{ site_name }}</footer>
</div>
</body>
</html>
|
- 第 6 行:[viewport] 标签指示移动浏览器按屏幕宽度显示页面,这正是 [Bootstrap] 所期望的;
- 第 8 行:[{% block %}] 指令标记一个命名的插槽,继承该模板的页面可以通过定义同名的块来填充它。写在 [{% block title %}] 和 [{% endblock %}] 之间的内容是占位符的默认内容,未定义该块的页面会使用它。[site_name] 是一个全局变量,存在于所有视图中(参见下面的 [config/packages/twig.yaml]);
- 第 10–11 行:函数 [path] 根据命名路由的参数值生成该路由的 URL(示例 04),这些参数值以 [Twig] 的关联数组 ([{file: '...'}],相当于 [['file' => '...']] 在 [PHP] 中的写法)提供。[asset] 函数根据 [public] 文件夹中的文件生成 URL。手动编写文件的 URL([/css/styles.css])同样可行,但如果应用程序安装在某个 URL 前缀之下,则只有 [path] 和 [asset] 才能正常工作;
- 第 16 行:[{% include %}] 插入另一个视图的内容,这里是导航栏。被包含的视图可以访问包含它的视图的变量;
- 第 19 行:每个页面用自己的内容填充的空间;
- 第 23 行:变量 [app] 存在于所有视图中:[Symfony] 在其中存放当前请求([app.request])、会话([app.session])、已登录用户([app.user],参见安全一节)、路由名称([app.current_route])等。[app.request.pathInfo] 是所请求 URL 的路径。过滤器 [date] 用于格式化日期;字符串 ['now'] 表示当前时间。
[container] 类(来自 [Bootstrap] )使内容居中并限制其宽度;[py-3] 添加垂直方向的内边距(padding):[Bootstrap] 提供数百个这类类,它们在 [class] 属性中组合使用。全局变量 [site_name] 在 [Twig] 的配置中声明:
| # config/packages/twig.yaml:TwigBundle 的配置
twig:
default_path: '%kernel.project_dir%/templates'
# 全局变量,存在于所有视图中
globals:
site_name: 'My site'
|
键 [globals] 下的变量会被添加到所有视图中,而无需动作来提供它们。全局变量也可以是一个服务(['@App\Service\...']),视图将调用它的方法。
4.3.3. 导航栏:templates/fragments/navbar.html.twig
| {# 片段:页面的一部分,通过 include 插入 #}
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
<span class="navbar-brand">{{ site_name }}</span>
<div class="navbar-nav">
{# path():由名称指定的路由的 URL #}
<a class="nav-link" href="{{ path('home') }}">Home</a>
<a class="nav-link" href="{{ path('team') }}">Team</a>
<a class="nav-link" href="{{ path('raw') }}">Page without layout</a>
</div>
</nav>
|
片段:页面的一部分,本身没有意义。类 [navbar]、[navbar-brand]和 [nav-link] 是 [Bootstrap] 导航栏的类。链接由 [path] 根据路由名称生成。
4.3.4. 宏:templates/macros.html.twig
| {# 宏(MACROS):带有参数的页面片段,就像函数一样 #}
{# 一张 Bootstrap 卡片,带有姓名和角色 #}
{% macro card(name, role = '') %}
<div class="card">
<div class="card-body">
<h5 class="card-title">{{ name }}</h5>
<p class="card-text">{{ role }}</p>
</div>
</div>
{% endmacro %}
|
- 第 4 行:宏 是页面中带有参数的一段内容;这就是 [Twig] 的函数。它通过 [{% macro name(parameters) %}] …… [{% endmacro %}] 声明;参数可以有默认值([role = ''])。一个文件可以包含多个宏。卡片([card])是 [Bootstrap] 的一个组件。
宏只能访问它自己的参数(以及全局变量);它不能访问调用它的视图的变量。这正是它可复用的原因。([Symfony UX Twig Component] 库提供功能更丰富的组件——与视图关联的 [PHP] 类——它们以 HTML 标签的形式使用:[<twig:Card name="..." />];我们用不到它们。)
4.3.5. 页面
| {# 该页面扩展(EXTEND)布局:它只提供其块的内容 #}
{% extends 'layout.html.twig' %}
{# macros.html.twig 文件中的宏,使用名称 m #}
{% import 'macros.html.twig' as m %}
{% block content %}
<h1>Welcome</h1>
<p>This page only contains its own content: the header, the navigation
bar and the footer come from the <code>layout.html.twig</code> layout.</p>
{# [card] 宏,调用时当场写出两个参数 #}
{{ m.card('A macro', 'called with parameters written on the spot') }}
{% endblock %}
|
- 第 2 行:页面继承模板:[Twig] 生成模板页面,用页面定义的块替换模板中的块。在继承模板的视图中,所有内容都必须位于块内:写在块之外的文本不会出现在生成的页面中;
- 第 4 行:[{% import %}] 从文件中导入宏,并使用你选择的名称([m]);
- 第 6–12 行:块 [content],用于填充同名的插槽。该页面没有定义块 [title]:插槽保留其默认内容“Home”;
- 第 11 行:以函数形式调用宏 [card]:[m.card(...)],写在 [{{ }}] 内,因为它产生要插入的文本。它的输出不会被二次转义:[Twig] 知道它已经是安全的 HTML(不过,它的参数已在宏内被转义)。
| {% extends 'layout.html.twig' %}
{% import 'macros.html.twig' as m %}
{% block title %}Our team{% endblock %}
{% block content %}
<h1>Our team</h1>
<div class="row g-3">
{% for member in members %}
<div class="col-md-4">
{# 宏的参数可以是任何表达式 #}
{{ m.card(member.name, member.role) }}
</div>
{% endfor %}
</div>
{% endblock %}
|
- 第 4 行:[title] 块,写在一行内;
- 第 8–15 行:每位团队成员一张卡片,放在 [Bootstrap] 的网格中([row]、[col-md-4]:在中等或大屏幕上为三列,在窄屏幕上为一列);
- 第 12 行:宏的参数可以是任意表达式。
控制器不包含新的内容:
| <?php
// src/Controller/PagesController.php:三个页面
namespace App\Controller;
use App\Model\Member;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
#[Route(methods: ['GET'])]
class PagesController extends AbstractController
{
#[Route('/', name: 'home')]
public function home(): Response
{
return $this->render('pages/home.html.twig');
}
#[Route('/team', name: 'team')]
public function team(): Response
{
$members = [
new Member('Marie Pélissier', 'Director'),
new Member('Jacques Bromard', 'Developer'),
new Member('Philippe Jandot', 'Graphic designer'),
];
return $this->render('pages/team.html.twig', ['members' => $members]);
}
#[Route('/raw', name: 'raw')]
public function raw(): Response
{
return $this->render('pages/raw.html.twig');
}
}
|
最后,第三个页面不使用模板:
| <!doctype html>
{# 该视图不使用布局:它是一个完整的页面 #}
<html lang="en">
<head>
<meta charset="utf-8">
<title>Raw page</title>
</head>
<body>
<p>This page does not use the layout: no Bootstrap, no navigation bar.</p>
<p><a href="{{ path('home') }}">Back to home</a></p>
</body>
</html>
|
4.3.6. 执行



浏览器收到的团队页面:
| curl http://localhost:8000/team
|
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Our team - My site</title>
<link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
<link rel="stylesheet" href="/css/styles.css">
</head>
<body>
<div class="container py-3">
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
<span class="navbar-brand">My site</span>
<div class="navbar-nav">
<a class="nav-link" href="/">Home</a>
<a class="nav-link" href="/team">Team</a>
<a class="nav-link" href="/raw">Page without layout</a>
</div>
</nav>
<main>
<h1>Our team</h1>
<div class="row g-3">
<div class="col-md-4">
<div class="card">
<div class="card-body">
<h5 class="card-title">Marie Pélissier</h5>
<p class="card-text">Director</p>
</div>
</div>
</div>
...
</div>
</main>
<footer class="footer">Page [/team] - © 2026 My site</footer>
</div>
</body>
</html>
|
浏览器收到了一个完整的页面:模板、片段、页面和宏都是在服务器上组装的。样式表的 URL 由 [path] 和 [asset] 生成:它们是相对于站点的 URL。你可以验证样式表是否被正确提供([-I] 选项(属于 [curl] )只显示响应头):
| curl -I http://localhost:8000/bootstrap/css/bootstrap.min.css
curl -I http://localhost:8000/css/styles.css
|
| HTTP/1.1 200 OK
Cache-Control: public
Last-Modified: Sun, 27 Sep 2026 09:32:39 GMT
Content-Type: text/css; charset=UTF-8
Content-Length: 232111
Accept-Ranges: bytes
...
HTTP/1.1 200 OK
Content-Type: text/css; charset=UTF-8
Content-Length: 435
|
第一个文件由我们的控制器发送([BinaryFileResponse] 会添加文件的修改日期并允许缓存:[Cache-Control: public]);第二个文件由开发服务器直接发送,不经过 [Symfony]。最后,尝试跳出该文件夹:
| curl -s -o /dev/null -w "%{http_code}\n" "http://localhost:8000/bootstrap/..%2F..%2F15-layout%2F.env"
|
([-s -o /dev/null -w "%{http_code}\n"] 选项只显示响应码;在 [Windows] 下,请输入 [-o NUL]。)
4.4. 示例 16:Twig 扩展
视图经常需要格式化值:带货币的金额、完整写出的日期,或大写文本。这类代码不属于动作(动作不处理展示),[Twig] 也不允许把它写在视图中(视图不能执行 [PHP];参见本章引言)。它用 [PHP] 编写,放在 [Twig] 的扩展中:这是一个类,为视图语言添加自己的过滤器、函数或测试。一些库提供了现成的扩展,例如 [twig/intl-extra](随示例一起安装),它根据语言格式化日期和金额。最后,宏用于创建 HTML 片段(示例 15)。
| 16-extensions/
├── config/
│ └── services.yaml
├── src/
│ ├── Controller/
│ │ └── PagesController.php
│ ├── EventListener/
│ │ └── SetLanguage.php
│ ├── Model/
│ │ └── Product.php
│ ├── Twig/
│ │ └── FormatsExtension.php
│ └── Kernel.php
├── templates/
│ ├── fragments/
│ │ └── navbar.html.twig
│ ├── layout.html.twig
│ ├── macros.html.twig
│ └── pages/
│ ├── home.html.twig
│ └── products.html.twig
└── ...
|
| <?php
// src/Twig/FormatsExtension.php:一个 Twig 扩展(EXTENSION),为视图语言
// 添加两个过滤器:money 和 long_date
namespace App\Twig;
use DateTimeInterface;
use IntlDateFormatter;
use NumberFormatter;
use Symfony\Component\HttpFoundation\RequestStack;
use Twig\Extension\AbstractExtension;
use Twig\TwigFilter;
class FormatsExtension extends AbstractExtension
{
// 请求栈,用于获知当前请求的语言
public function __construct(private RequestStack $requests)
{
}
// 扩展的过滤器:它们在视图中的名称,以及实现它们的方法
public function getFilters(): array
{
return [
new TwigFilter('money', $this->money(...)),
new TwigFilter('long_date', $this->longDate(...)),
];
}
// 以某种货币表示的金额(以分为单位),采用请求语言的格式:
// 114990 -> 英语为 "€1,149.90",法语为 "1 149,90 €"。
// PHP 的 intl 扩展了解每个国家的惯例
public function money(int $cents, string $currency = 'EUR'): string
{
$formatter = new NumberFormatter($this->language(), NumberFormatter::CURRENCY);
return $formatter->formatCurrency($cents / 100, $currency);
}
// 用完整单词表示的日期,使用请求的语言:"Sunday, September 27, 2026"
public function longDate(DateTimeInterface $day): string
{
$formatter = new IntlDateFormatter($this->language(), IntlDateFormatter::FULL, IntlDateFormatter::NONE);
return $formatter->format($day);
}
private function language(): string
{
return $this->requests->getCurrentRequest()?->getLocale() ?? 'en';
}
}
|
- 第 14 行:[Twig] 的扩展继承自 [AbstractExtension] 类。它是一个服务,与 [src] 文件夹中的每个类一样;[Symfony] 会把它识别为扩展([autoconfigure])并传递给 [Twig];
- 第 17–19 行:扩展需要当前请求的语言。它接收请求栈 ([RequestStack]),这是 [Symfony] 中知道当前请求的服务(之所以有栈,是因为一个请求可能在内部触发另一个请求);
- 第 22–28 行:方法 [getFilters] 返回扩展的过滤器:对每个过滤器,给出它在视图中的名称和实现它的函数。[$this->money(...)] (带省略号)并不调用该方法:它把方法变成一个值——一个可以稍后调用的函数(一等可调用对象)。扩展还可以提供函数([getFunctions])和测试([getTests]);
- 第 33–37 行:格式化以分为单位接收的金额(参见示例 06)。这取决于语言:法语中为 [1 149,90 €] (空格分隔千位,小数点用逗号,符号在金额之后);英语中为 [€1,149.90]。[NumberFormatter] 类,属于 [intl] 扩展(来自 [PHP]),支持所有国家的习惯(它使用 Unicode 项目 CLDR 的数据):它针对一种语言和一种样式创建(这里是 [CURRENCY],用于金额),而 [formatCurrency] 格式化金额,货币由其国际代码指定([EUR]、[USD])。过滤器的第一个参数是被过滤的值;其后的参数是它在视图中的属性([priceCents|money('USD')]);
- 第 40–44 行:使用 [IntlDateFormatter] 类(来自 [intl] 扩展)格式化日期:样式 [FULL] 完整写出日期,包括星期几([Sunday, September 27, 2026]);而用于时间的样式 [NONE]则不包含时间。类型 [DateTimeInterface] 接受来自 [PHP] 的所有日期;
- 第 46–49 行:当前请求的语言([fr]、[en]),如果没有请求(例如在控制台命令中),则为英语。我们接下来会看到由谁来设置它。
4.4.2. 每个请求的语言:src/EventListener/SetLanguage.php
| <?php
// src/EventListener/SetLanguage.php:每个请求的语言
namespace App\EventListener;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpKernel\Event\RequestEvent;
use Symfony\Component\HttpKernel\KernelEvents;
// priority:同一事件的监听器的顺序(数值最大的最先);
// 20:在路由(32)之后,在使用语言的 Symfony 监听器(16、15)之前
#[AsEventListener(event: KernelEvents::REQUEST, priority: 20)]
class SetLanguage
{
// URL 的 ?lang=fr 参数,否则为英语
public function __invoke(RequestEvent $event): void
{
$request = $event->getRequest();
$request->setLocale($request->query->get('lang') === 'fr' ? 'fr' : 'en');
}
}
|
每个请求都有一种语言 (区域设置),默认为配置中指定的语言 [default_locale] (如果未配置任何内容,则为 [en] )。这里,URL 参数 [?lang=fr] 选择法语;英语是默认语言。 一个针对 [kernel.request] 事件的监听器(示例 12)在每个动作之前使用请求的 [setLocale] 方法来设置它。属性的 [priority] 参数设定同一事件的各监听器的顺序:优先级最高的最先处理(默认为 0)。[Symfony] 自身有若干 [kernel.request] 的监听器:路由(优先级 32),其后是准备与语言相关的服务的监听器(16 和 15)。我们的监听器必须在这两者之间运行:20。命令 [php bin/console debug:event-dispatcher kernel.request] 按顺序显示该事件的所有监听器。以这种方式设置的语言只适用于当前请求:下一个请求将恢复为默认语言。国际化一章将使用这同一种语言来翻译文本。
4.4.3. 配置:config/services.yaml
| # config/services.yaml:应用程序的服务(见示例 06)
services:
_defaults:
autowire: true
autoconfigure: true
App\:
resource: '../src/'
# 提供 Bootstrap 的控制器,由示例 15 到 28 共享(见示例 15)
Common\BootstrapController: ~
# Twig 的 Intl 扩展(twig/intl-extra 库):过滤器
# format_currency、format_date、format_number...
Twig\Extra\Intl\IntlExtension: ~
|
- 第 15 行:[twig/intl-extra] 库的过滤器由 [IntlExtension] 扩展提供。它的类不在 [src] 文件夹中:它被声明为服务,[Symfony] 会把它识别为 [Twig] 的扩展([autoconfigure])。(在标准项目中,由 [twig/extra-bundle] 包(由 [Symfony Flex] 安装)自行处理这一点。)
4.4.4. 控制器:src/Controller/PagesController.php
| <?php
// src/Controller/PagesController.php:两个页面
namespace App\Controller;
use App\Model\Product;
use DateTimeImmutable;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
#[Route(methods: ['GET'])]
class PagesController extends AbstractController
{
#[Route('/', name: 'home')]
public function home(): Response
{
return $this->render('pages/home.html.twig', ['today' => new DateTimeImmutable('today')]);
}
#[Route('/products', name: 'products')]
public function products(): Response
{
return $this->render('pages/products.html.twig', ['products' => [
new Product('keyboard', 2500, 12),
new Product('mouse', 1250, 0),
new Product('screen', 114990, 3),
]]);
}
}
|
动作把原始值传给视图:一个日期([new DateTimeImmutable('today')],今天午夜的日期)和以分为单位的金额。格式化由视图负责。[Product] 类包含名称、价格(以分为单位;参见示例 06)和库存量。
4.4.5. 视图
| {# 导航栏的一个链接,如果
当前页面位于 [path] 路径之下,它会获得 [active] 类。app.request.pathInfo:当前
请求的路径;starts with:一个 Twig 测试 #}
{% macro link(href, path, text) %}
<a class="nav-link{{ app.request.pathInfo starts with path ? ' active' }}" href="{{ href }}">{{ text }}</a>
{% endmacro %}
{# 一个 Bootstrap 徽章:产品有库存时为绿色,否则为红色 #}
{% macro badge(stock) %}
<span class="badge {{ stock > 0 ? 'text-bg-success' : 'text-bg-danger' }}">{{ stock > 0 ? stock ~ ' in stock' : 'sold out' }}</span>
{% endmacro %}
|
- 第 4–6 行:一个为导航栏创建链接的宏。当前页面的链接会被赋予 [active] 类(来自 [Bootstrap]),使其高亮显示。宏可以访问全局变量 [app] (示例 15):[app.request.pathInfo] 是当前请求的路径;[starts with] 是 [Twig] 的运算符,用于检查字符串的开头。不带“else”子句的三元运算符([condition ? ' active'])在条件为假时返回空字符串(示例 14);
- 第 9–11 行:来自 [Bootstrap] 的徽章,根据库存显示为绿色([text-bg-success])或红色([text-bg-danger])。[~] 运算符(属于 [Twig] )用于连接两个字符串(相当于 [.] 在 [PHP] 中的作用)。
| {% import 'macros.html.twig' as m %}
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
<span class="navbar-brand">Extensions</span>
<div class="navbar-nav">
{# 1. 写在视图中的条件;app.current_route:当前路由的名称 #}
<a class="nav-link{{ app.current_route == 'home' ? ' active' }}" href="{{ path('home') }}">Home</a>
{# 2. [link] 宏 #}
{{ m.link(path('products'), '/products', 'Products') }}
{# 3. path() 构建具名路由的 URL;不属于路由参数的
参数会添加到 URL 的末尾:/products?lang=fr #}
<a class="nav-link" href="{{ path('products', {lang: 'fr'}) }}">Produits (fr)</a>
</div>
</nav>
|
- 第 1 行:被包含的片段(示例 15)不会继承包含它的视图的导入:它自行导入所需的宏;
- 第 6 行:与宏相同,直接写在视图中,使用三元运算符。[app.current_route] 是当前请求路由的名称。宏避免了为每个链接重复条件;
- 第 8 行:宏调用;
- 第 11 行:[path] 的一个不是路由参数的参数会作为参数添加到 URL 中:[/products?lang=fr]。
| {% extends 'layout.html.twig' %}
{% block title %}Home{% endblock %}
{% block content %}
<h1>Home</h1>
{# 我们的 long_date 过滤器 #}
<p>Today is {{ today|long_date }}.</p>
{# app.request.locale:请求的语言,由 SetLanguage 监听器设置 #}
<p>Formatting language: {{ app.request.locale }}
(<a href="{{ path('home', {lang: 'fr'}) }}">in French</a>, <a href="{{ path('home') }}">in English</a>)</p>
{% endblock %}
|
- 第 7 行:我们的过滤器 [long_date];
- 第 9 行:[app.request.locale],请求的语言,由监听器 [SetLanguage] 设置。
| {% extends 'layout.html.twig' %}
{% import 'macros.html.twig' as m %}
{% block title %}Products{% endblock %}
{% block content %}
<h1>Products</h1>
<table class="table table-sm w-auto">
<thead><tr><th>Product</th><th>Price</th><th>Price in dollars</th><th>Stock</th></tr></thead>
<tbody>
{% for product in products %}
<tr>
{# 一个 Twig 过滤器(upper),然后是我们的 money 过滤器,先不带参数,再带参数 #}
<td>{{ product.name|upper }}</td>
<td>{{ product.priceCents|money }}</td>
<td>{{ product.priceCents|money('USD') }}</td>
{# [badge] 宏构建徽章的 HTML #}
<td>{{ m.badge(product.stock) }}</td>
</tr>
{% endfor %}
</tbody>
</table>
{# Intl 扩展的 format_currency 过滤器:一个金额(这里以元为单位)、一种
货币,以及请求的语言 #}
<p>Total stock value: {{ (products|reduce((s, p) => s + p.priceCents * p.stock, 0) / 100)|format_currency('EUR', locale: app.request.locale) }}</p>
{% endblock %}
|
- 第 13 行:[Twig] 的过滤器;
- 第 14–15 行:我们的 [money] 过滤器,先使用其默认货币,然后带一个参数;
- 第 17 行:调用 [badge] 宏;
- 第 24 行:Intl 扩展的 [format_currency] 过滤器:一个金额(这里以欧元计:由 [reduce] 计算出的库存总额,再除以 100)、一种货币,以及请求的语言,通过 命名参数 (来自 [Twig] )传递([locale: ...])。该扩展还提供 [format_date]、[format_datetime]、[format_number]、[country_name]、[language_name]等。因此我们的过滤器 [money] 有重复功能:我们编写它是为了演示如何编写扩展。
模板 [layout.html.twig] 是示例 15 中模板的简化版;它的 [lang] 属性接收请求的语言([<html lang="{{ app.request.locale }}">])。
4.4.6. 执行


同一个页面,带参数 [?lang=fr]。只有数字的格式发生变化:文本本身是硬编码在视图中的。国际化一章还会翻译文本。

HTML 的一个片段生成:
| curl "http://localhost:8000/products?lang=en"
|
| ...
<tr>
<td>KEYBOARD</td>
<td>€25.00</td>
<td>$25.00</td>
<td> <span class="badge text-bg-success">12 in stock</span>
</td>
</tr>
...
<p>Total stock value: €3,749.70</p>
...
|
4.5. 示例 17:GET 表单
HTML 表单根据其 [method] 属性,以两种方式之一向服务器发送字段:
- [method="get"]:字段作为参数添加到 URL 中([/search?keyword=le&genre=novel])。这是执行查询的表单(搜索或筛选)所使用的方法。包含结果的 URL 可以被加入书签、分享,或安全地重新加载;
- [method="post"]:字段包含在请求体中(参见示例 11)。这是修改数据(注册、添加或删除)的表单所使用的方法。
这第一个表单是图书搜索。它直接用 HTML 手工编写在视图中;后面的示例将使用 [Symfony] 的 Form 组件来处理表单。
4.5.1. 模型:src/Model/Book.php 和 SearchModel.php
| <?php
// src/Model/Book.php:一本书
namespace App\Model;
readonly class Book
{
public function __construct(
public string $title,
public string $author,
public string $genre,
) {
}
}
|
| <?php
// src/Model/SearchModel.php:视图的模型:输入(以便再次
// 显示)、类别、结果
namespace App\Model;
readonly class SearchModel
{
/**
* @param list<string> $genres
* @param list<Book> $results
*/
public function __construct(
public string $keyword,
public string $genre,
public array $genres,
public array $results,
) {
}
}
|
- 第 14–19 行:视图模型包含用户的输入(表单会显示它)、建议的类型列表以及搜索结果。
4.5.2. 控制器:src/Controller/BooksController.php
| <?php
// src/Controller/BooksController.php:通过 GET 发送的搜索表单
namespace App\Controller;
use App\Model\Book;
use App\Model\SearchModel;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
class BooksController extends AbstractController
{
// 类常量:数据,为了示例而写在代码中
private const GENRES = ['novel', 'poetry', 'drama'];
/** @return list<Book> */
private static function books(): array
{
return [
new Book('Le Rouge et le Noir', 'Stendhal', 'novel'),
new Book('Les Fleurs du mal', 'Baudelaire', 'poetry'),
new Book('Madame Bovary', 'Flaubert', 'novel'),
new Book('Alcools', 'Apollinaire', 'poetry'),
new Book('Le Cid', 'Corneille', 'drama'),
];
}
// GET / 和 GET /search?keyword=...&genre=...:表单及其结果;
// 同一个操作对应两个路由:#[Route] 属性可以重复使用
#[Route('/', name: 'books_home', methods: ['GET'])]
#[Route('/search', name: 'books_search', methods: ['GET'])]
public function search(Request $request): Response
{
// getString:以字符串形式表示的参数(缺失时为 '')
$keyword = $request->query->getString('keyword');
$genre = $request->query->getString('genre');
$word = mb_strtolower($keyword);
$results = array_values(array_filter(self::books(), fn (Book $book) =>
($word === '' || str_contains(mb_strtolower($book->title), $word)
|| str_contains(mb_strtolower($book->author), $word))
&& ($genre === '' || $book->genre === $genre)));
return $this->render('books/search.html.twig', [
'model' => new SearchModel($keyword, $genre, self::GENRES, $results),
]);
}
}
|
- 第 16 行:一个私有的类常量 ,名为 [self::GENRES] ([self] 指代当前类)。常量不能包含对象:因此图书由一个静态方法提供(第 19–28 行)。在真实的应用程序中,它们会来自数据库;
- 第 32–33 行:同一个动作的两条路由:[#[Route]] 属性可以重复。首次访问([/])时没有参数,会显示所有图书;
- 第 37–38 行:表单字段被作为 URL 参数读取(示例 07)。[getString] 方法以字符串形式返回参数,如果参数不存在则返回空字符串;
- 第 40–43 行:筛选。[array_filter] 函数保留数组中使给定函数返回 [true] 的元素:如果关键字为空,或出现在书名或作者中(两边都转为小写;[mb_strtolower] 能正确处理带重音的字符),并且类型为空或与该书的类型匹配,则该书被选中。[array_filter] 会保留所选元素的键(0、2……):[array_values] 把它们从 0 开始重新编号;
- 第 44–46 行:视图模型。
4.5.3. 视图:templates/books/search.html.twig
| {% extends 'layout.html.twig' %}
{% block content %}
<h1 class="h3">Book search</h1>
{# method="get":字段通过 URL 发送(?keyword=...&genre=...) #}
<form method="get" action="{{ path('books_search') }}" class="row g-2 align-items-end mb-3">
<div class="col-auto">
<label class="form-label" for="keyword">Title or author</label>
{# value:字段重新显示所输入的内容(由 {{ }} 转义) #}
<input class="form-control" id="keyword" name="keyword" value="{{ model.keyword }}">
</div>
<div class="col-auto">
<label class="form-label" for="genre">Genre</label>
<select class="form-select" id="genre" name="genre">
<option value="">(all)</option>
{% for genre in model.genres %}
{# 布尔属性 selected,条件为 true 时写出,否则省略 #}
<option value="{{ genre }}"{{ genre == model.genre ? ' selected' }}>{{ genre }}</option>
{% endfor %}
</select>
</div>
<div class="col-auto">
<button class="btn btn-primary" type="submit">Search</button>
</div>
</form>
<p>{{ model.results|length }} book(s) found.</p>
<ul>
{% for book in model.results %}
<li><i>{{ book.title }}</i>, {{ book.author }} ({{ book.genre }})</li>
{% endfor %}
</ul>
{% endblock %}
|
- 第 6 行:[<form>] 标签。[action] 属性是表单提交到的 URL;[method="get"] 把字段放在 URL 中。[Bootstrap] 的类把这些字段排列在同一行;
- 第 8 行:标签。它的 [for] 属性指定它所描述的字段的标识符([id]):点击标签会把光标置于该字段中,屏幕阅读器会连同字段一起朗读标签;
- 第 10 行:输入字段。它的属性 [name] 是发送到服务器的参数名称:这就是表单与动作之间的联系([$request->query->getString('keyword')])。属性 [value] 是显示的值:即重新显示的上一次输入(并由 [{{ }}] 转义,这在属性中至关重要:包含引号 ["] 的输入否则会使属性提前结束);
- 第 14–20 行:下拉列表。每个 [<option>] 都有一个发送到服务器的值([value])和一段显示的文本。第一个选项的值为空,表示“所有类型”;
- 第 18 行:上一次请求中选中的选项会被赋予属性 [selected]。这是一个布尔属性:只要出现即可,不需要值。不带“else”部分的三元运算符在条件为真时写出它,否则什么也不写。[==] 是 [Twig] 的相等比较;
- 第 23 行:提交按钮;
- 第 26 行:结果数量。
4.5.4. 执行

我们输入 [le] 并选择类型 [novel]:

结果页面上的 URL 包含表单字段:[/search?keyword=le&genre=novel]。表单的响应:
| curl "http://localhost:8000/search?keyword=le&genre=novel"
|
| ...
<form method="get" action="/search" class="row g-2 align-items-end mb-3">
<div class="col-auto">
<label class="form-label" for="keyword">Title or author</label>
<input class="form-control" id="keyword" name="keyword" value="le">
</div>
<div class="col-auto">
<label class="form-label" for="genre">Genre</label>
<select class="form-select" id="genre" name="genre">
<option value="">(all)</option>
<option value="novel" selected>novel</option>
<option value="poetry">poetry</option>
<option value="drama">drama</option>
</select>
</div>
...
</form>
<p>1 book(s) found.</p>
<ul>
<li><i>Le Rouge et le Noir</i>, Stendhal (novel)</li>
</ul>
...
|
“Madame Bovary”没有被选中:“le”既没有出现在书名中,也没有出现在作者姓名中。
4.6. 示例 18:表单字段
本示例展示 HTML 表单中的所有字段类型,这次通过 POST 提交。它演示了如何用当前值重新显示每种字段类型、浏览器如何发送每种字段的值,以及服务器如何验证收到的值确实是可用选项之一。像示例 17 那样手工编写这一切既耗时又重复。[Symfony] 把这项任务委托给它的 Form 组件:表单由一个类来描述,即它的类型;[Symfony] 生成 HTML、读取提交的字段、转换它们、验证它们,并带着用户的输入和所有错误重新显示表单。这相当于 [Python] 中的 [WTForms]。
| 18-fields/
├── config/
│ └── packages/
│ ├── framework.yaml
│ └── twig.yaml
├── src/
│ ├── Controller/
│ │ └── FormController.php
│ ├── Form/
│ │ └── FieldsType.php
│ ├── Service/
│ │ └── ListsService.php
│ └── Kernel.php
├── templates/
│ ├── form/
│ │ └── form.html.twig
│ └── layout.html.twig
└── ...
|
4.6.1. 列表服务:src/Service/ListsService.php
| <?php
// src/Service/ListsService.php:表单提供的列表。在
// 真实的应用程序中,它们将来自数据库。
namespace App\Service;
class ListsService
{
// 每个列表:一个关联数组,显示的文本 => 发送的值
public function titles(): array
{
return ['Mr' => 'Mr', 'Mme' => 'Mme', 'Melle' => 'Melle'];
}
public function countries(): array
{
return ['France' => 'fr', 'Belgium' => 'be', 'Switzerland' => 'ch', 'Canada' => 'ca'];
}
public function hobbies(): array
{
return ['reading' => 'reading', 'music' => 'music', 'sport' => 'sport', 'cinema' => 'cinema'];
}
public function languages(): array
{
return ['French' => 'French', 'English' => 'English', 'Spanish' => 'Spanish',
'German' => 'German'];
}
}
|
表单的下拉列表(称谓、国家、爱好、语言)由一个服务提供,遵循示例 06 中的模型:在真实的应用程序中,它们会来自数据库。每个列表都是一个关联数组:键是显示的文本,值是发送到服务器的内容(这是 Form 组件所期望的顺序)。
4.6.2. 配置
| # config/packages/framework.yaml:FrameworkBundle 的配置
framework:
secret: '%env(APP_SECRET)%'
# 英语的消息(表单的错误)(见示例 09)
default_locale: en
translator:
default_path: '%kernel.project_dir%/translations'
# 会话(SESSION):表单的防 CSRF 令牌保存在其中(见示例 20)
session: true
# 表单的防 CSRF 保护(见后文)
csrf_protection: true
|
- 第 5–7 行:语言和翻译器(示例 09):Form 组件的错误消息与验证器的一样,将是英文的;
- 第 9 行:用户的会话,我们将在示例 20 中进一步讨论:Form 组件把防 CSRF 令牌存放在其中(见下文);
- 第 11 行:表单的防 CSRF 保护。
| # config/packages/twig.yaml:TwigBundle 的配置
twig:
default_path: '%kernel.project_dir%/templates'
# 表单的主题(THEME):字段使用 Bootstrap 5 的类绘制
form_themes: ['bootstrap_5_layout.html.twig']
|
- 第 5 行:表单主题。[Symfony] 使用 [Twig] 块来渲染每个字段;主题提供适合某个 CSS 框架的版本。[bootstrap_5_layout.html.twig] 主题随 [Symfony] 一起提供,使用 [Bootstrap] 5 的类([form-control]、[form-label]、[is-invalid]等)。应用程序可以编写自己的主题,或覆盖现有主题的某些块。
| <?php
// src/Form/FieldsType.php:表单的描述:其字段、类型和选项
namespace App\Form;
use App\Service\ListsService;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
use Symfony\Component\Form\Extension\Core\Type\DateType;
use Symfony\Component\Form\Extension\Core\Type\HiddenType;
use Symfony\Component\Form\Extension\Core\Type\PasswordType;
use Symfony\Component\Form\Extension\Core\Type\TextareaType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\Validator\Constraints\NotBlank;
class FieldsType extends AbstractType
{
// 表单类型是一个服务:它接收列表服务
public function __construct(private ListsService $lists)
{
}
// 表单的字段,按其显示顺序排列
public function buildForm(FormBuilderInterface $builder, array $options): void
{
$builder
// 单选按钮:一个选项列表(ChoiceType),“expanded”;
// constraints:该字段的验证约束(见示例 08)
->add('title', ChoiceType::class, [
'choices' => $this->lists->titles(),
'expanded' => true,
'label_attr' => ['class' => 'radio-inline'],
'constraints' => [new NotBlank(message: 'The title is required.')],
])
// 一个输入字段;required => false:该字段不是必填的
->add('name', TextType::class, ['required' => false])
// 密码:绝不会在页面中再次显示
->add('password', PasswordType::class, ['label' => 'Password', 'required' => false])
// 日期:一个 <input type="date"> 字段;其值是 yyyy-mm-dd 字符串
->add('birth_date', DateType::class, [
'label' => 'Date of birth',
'widget' => 'single_text',
'input' => 'string',
'required' => false,
])
// 复选框:一个展开的选项列表,可多选
->add('hobbies', ChoiceType::class, [
'choices' => $this->lists->hobbies(),
'expanded' => true,
'multiple' => true,
'label_attr' => ['class' => 'checkbox-inline'],
'required' => false,
])
// 下拉列表:一个未展开的选项列表
->add('country', ChoiceType::class, ['choices' => $this->lists->countries()])
// 多选列表,显示为四行
->add('languages', ChoiceType::class, [
'label' => 'Spoken languages',
'choices' => $this->lists->languages(),
'multiple' => true,
'attr' => ['size' => 4],
'required' => false,
])
->add('comment', TextareaType::class, ['required' => false, 'attr' => ['rows' => 2]])
// 一个隐藏字段
->add('token', HiddenType::class);
}
}
|
- 第 17 行:表单类型继承自 [AbstractType] 类。它是一个服务(位于 [src] 文件夹中):它可以接受其他服务,这里是列表服务(第 20 行);
- 第 25 行:[buildForm] 方法通过将字段添加([add])到表单构建器中来描述这些字段:对每个字段给出其名称、类型和选项。字段名称也是它所显示数据的名称;它的标签默认是其名称格式化后的文本([name] 变为“Name”);
- 第 30–35 行:[ChoiceType] 字段是由 [choices] 选项定义的下拉列表。使用 [expanded] 选项时,它变成一组单选按钮 (单选字段)。选项 [label_attr] 为分组标签指定一个类:[radio-inline] 在主题中表示按钮并排显示。选项 [constraints] 设置字段的验证约束 (示例 08):称谓是必填的;
- 第 37 行:[TextType] 字段是一个输入字段。选项 [required] 默认为 [true]:[Symfony] 随后会把 HTML 属性设置为 [required],由浏览器进行检查(示例 19)。它不会向服务器发送任何信息:让字段对服务器而言必填的是一个约束([NotBlank]);
- 第 39 行:密码([PasswordType]),它永远不会返回到页面:显示时其字段总是空的;
- 第 41–46 行:日期([DateType]),由单个字段 [<input type="date">] 显示(选项 [widget])。无论浏览器以何种格式显示,这样的字段都以 [yyyy-mm-dd] 格式与服务器交换其值;[input] 选项指定数据是字符串(而不是默认的 [DateTime] 对象);
- 第 48–54 行:带有多项选择([multiple])的列表:复选框;
- 第 56 行:未展开的多选列表:下拉列表;
- 第 58–64 行:未展开的多选列表:多选列表框,显示为四行(HTML 属性 [size],由选项 [attr] 指定);
- 第 65 行:文本框([TextareaType]),占两行;
- 第 67 行:隐藏字段([HiddenType])。
[Symfony] 提供约三十种字段类型:[EmailType]、[IntegerType]、[MoneyType]、[UrlType]、[CheckboxType]、[FileType]、[CountryType]、[RepeatedType] (示例 19)、[CollectionType] (子表单列表)等。
| <?php
// src/Controller/FormController.php:一个使用所有字段类型的表单
namespace App\Controller;
use App\Form\FieldsType;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
class FormController extends AbstractController
{
// GET:带初始值的表单;POST:读取发送的字段,
// 进行验证,然后由同一个表单再次显示
#[Route('/form', name: 'form', methods: ['GET', 'POST'])]
public function form(Request $request): Response
{
// 初始值(每个字段一个,多值字段则为数组)
$initial = ['title' => 'Mme', 'country' => 'fr', 'languages' => ['French'], 'token' => 'A7X2'];
// createForm:根据其描述构建的表单
$form = $this->createForm(FieldsType::class, $initial);
// handleRequest:如果请求是 POST,则将收到的字段复制
// 到表单中,然后进行验证
$form->handleRequest($request);
$model = ['form' => $form];
if ($form->isSubmitted()) {
// 浏览器实际发送的内容,逐个字段
$received = [];
foreach ($request->request->all() as $name => $value) {
foreach ((array) $value as $key => $v) {
$received[] = "{$name}[$key] = [".implode(', ', (array) $v).']';
}
}
$model += [
'received' => implode("\n", $received),
'valid' => $form->isValid(),
// getErrors(true):所有字段的错误
'errors' => $form->getErrors(true),
// getData():表单的值,由每个字段进行转换
'data' => $form->getData(),
];
}
return $this->render('form/form.html.twig', $model);
}
}
|
- 第 16 行:一个动作同时处理两种方法:GET 显示表单,POST 处理表单。这是使用 [Symfony] 编写表单动作的标准方式;
- 第 20 行:表单的初始值:一个关联数组,每个字段对应一个值(多值字段对应一个数组);
- 第 22 行:[createForm] 根据表单类型和初始数据创建表单——一个 [Form] 对象;
- 第 25 行:[handleRequest] 检查请求。对于 GET,它什么也不做。对于包含表单字段的 POST,它把这些字段复制到表单中:每个字段转换自己的值(日期、列表等),验证所选内容是否在提供的选项之中,然后表单再验证约束和防 CSRF 令牌;
- 第 27 行:[isSubmitted]:表单是否已提交?
- 第 29–34 行:针对本示例,列出浏览器实际发送的内容。[Symfony] 表单的字段以表单名称命名:[fields[name]], [fields[hobbies][]]。因此 [PHP] 把它们组织成一个名为 [fields] 的数组 (示例 10),然后对其进行遍历。[(array) $value] 将单个值转换为只有一个元素的数组(数组仍然是数组);[implode] 把数组的元素合并为一个字符串,以第一个参数作为分隔符;
- 第 35–42 行:视图模型接收服务器收到的内容:验证结果([isValid])、错误([getErrors(true)]:所有字段的错误)以及表单数据 ([getData]),由各字段转换。[+=] 运算符将这些键添加到 [$model] 数组中;
- 第 44 行:表单被传递给视图,视图将显示它,连同用户的输入和所有错误。
| {% extends 'layout.html.twig' %}
{% block content %}
<h1 class="h3">A complete form</h1>
{# form_start:<form> 标签,这里使用 POST 方法和页面的 URL #}
{{ form_start(form, {attr: {style: 'max-width: 40rem'}}) }}
{# form_row:一个完整的字段(标签、输入字段、错误) #}
{{ form_row(form.title) }}
<div class="row g-2">
<div class="col">{{ form_row(form.name) }}</div>
<div class="col">{{ form_row(form.password) }}</div>
<div class="col">{{ form_row(form.birth_date) }}</div>
</div>
{{ form_row(form.hobbies) }}
<div class="row g-2">
<div class="col">{{ form_row(form.country) }}</div>
<div class="col">{{ form_row(form.languages) }}</div>
</div>
{{ form_row(form.comment) }}
<button class="btn btn-primary" type="submit">Send</button>
{# form_end:其余的字段(隐藏字段、防 CSRF 令牌),然后是 </form> #}
{{ form_end(form) }}
{# is defined:如果收到的变量已传递给视图(表单已发送)则为 true #}
{% if received is defined %}
<h2 class="h5 mt-3">What the server received</h2>
<pre class="bg-light p-2 border">{{ received }}</pre>
<p>Valid form: {{ valid ? 'yes' : 'no' }}</p>
<ul>
{% for error in errors %}
{# error.origin:出错的字段;error.message:消息 #}
<li>{{ error.origin.getName() }}: {{ error.message }}</li>
{% endfor %}
</ul>
{% if valid %}
<p>The data of the form:</p>
<ul>
{# 对关联数组的循环:键和值 #}
{% for key, value in data %}
<li>{{ key }}: {{ value is iterable ? value|join(', ') : value }}</li>
{% endfor %}
</ul>
{% endif %}
{% endif %}
{% endblock %}
|
- 第 6 行:函数 [form_start] 写出标签 [<form>]:默认使用 POST 方法和当前页面的 URL;第二个参数添加 HTML 属性;
- 第 8 行:[form_row] 函数使用主题的类写出一个完整的字段:它的标签、它的输入字段(带当前值)及其错误。[form.title] 指表单中的 [title] 字段。你也可以分开写各个部分:[form_label]、[form_widget]、[form_errors];
- 第 9–19 行:其他字段,由 [Bootstrap] 的网格类排列;
- 第 22 行:[form_end] 写出尚未写出的字段(这里是隐藏字段 [token] 和隐藏字段 [_token],即防 CSRF 令牌),然后关闭 [</form>] 标签;
- 第 25 行:[is defined] 检查:变量 [received] 只有在提交之后才存在;
- 第 30–33 行:错误。每个错误都是一个 [FormError] 对象,其中 [origin] 是包含该错误的字段;
- 第 39–41 行:对关联数组的 [for] 循环,同时遍历键和值。[is iterable] 测试用于区分数组(由 [join] 过滤器合并)和单个值。
整个表单本可以只写一行:[{{ form(form) }}]。函数 [form_start]、[form_row]、和 [form_end] 让你可以按需排列字段。
4.6.6. 执行

默认值是可见的:“Mme”单选按钮、国家“France”和语言“French”。HTML 生成如下内容(摘录,分多行显示):
| <form name="fields" method="post" style="max-width: 40rem">
<fieldset class="mb-3"><legend class="col-form-label required">Title</legend>
<div id="fields_title">
<div class="form-check form-check-inline">
<input type="radio" id="fields_title_0" name="fields[title]" required="required" class="form-check-input" value="Mr" />
<label class="form-check-label required" for="fields_title_0">Mr</label></div>
<div class="form-check form-check-inline">
<input type="radio" id="fields_title_1" name="fields[title]" required="required" class="form-check-input" value="Mme" checked="checked" />
...
<div class="mb-3"><label for="fields_name" class="form-label">Name</label>
<input type="text" id="fields_name" name="fields[name]" class="form-control" /></div>
...
<input type="checkbox" id="fields_hobbies_0" name="fields[hobbies][]" class="form-check-input" value="reading" />
...
<select id="fields_country" name="fields[country]" class="form-select">
<option value="fr" selected="selected">France</option><option value="be">Belgium</option>...
<select id="fields_languages" name="fields[languages][]" size="4" class="form-select" multiple="multiple">
<option value="French" selected="selected">French</option>...
...
<input type="hidden" id="fields_token" name="fields[token]" value="A7X2" />
<input type="hidden" id="fields__token" name="fields[_token]" data-controller="csrf-protection" value="9863be7bac.KU7NzSfFyCspR2sfBG_fTqNV6UuMueZ2pOsuPACnvFo.X32P9UOQm1FPIxhHUVqHGvcBmWbl36Il8KJsCVnS8A1ZJYGudJSrRmwoWw" />
</form>
|
[Symfony] 写出了一切:标识符([fields_title_1])、与字段关联的标签、多值字段以 [[]] 结尾的名称(示例 10)、公共值的 [checked] 和 [selected] 属性,以及 [Bootstrap] 的类。最后一个隐藏字段 [fields[_token]] 包含防 CSRF 令牌。CSRF 攻击(跨站请求伪造)是指恶意网站诱骗受害者的浏览器向我们的应用程序提交表单。浏览器会在请求中带上我们应用程序的 Cookie——从而带上已登录用户的会话——使请求看起来合法。对策是:我们应用程序中的每个表单都包含一个与用户会话关联的随机令牌,恶意网站无法得知它。Form 组件会为每个表单添加这个令牌,而 [handleRequest] 会拒绝任何令牌缺失或不正确的表单:任何表单都不能省略它。([data-controller] 属性由 [Symfony] 的一个可选脚本使用,它能增强保护;在这里没有任何作用。)让我们填写表单并提交:

页面显示了服务器收到的内容:每个字段对应一个参数,复选框和下拉列表有多个值;密码已发送,但不会在其字段中再次显示。隐藏字段 [token] 被原样返回:这是来回传送用户看不到的信息的方法(案例研究用它来传送记录的版本号)。不过,隐藏字段并不是受保护的字段:用户可以使用浏览器的开发者工具修改它,服务器必须像验证其他字段一样验证它。防 CSRF 令牌也包含在收到的字段中;它不属于表单数据。
现在让我们用 [curl] 发送一个没有令牌的表单,并选择一个不在选项中的国家:
| curl -g -d "fields[name]=Martin&fields[country]=xx" http://localhost:8000/form
|
| ...
<h2 class="h5 mt-3">What the server received</h2>
<pre class="bg-light p-2 border">fields[name] = [Martin]
fields[country] = [xx]</pre>
<p>Valid form: no</p>
<ul>
<li>fields: The CSRF token is invalid. Please try to resubmit the form.</li>
<li>title: The title is required.</li>
<li>country: The selected choice is invalid.</li>
</ul>
...
|
该表单无效 有三个原因:缺少防 CSRF 令牌(该错误与表单本身关联)、没有提交称谓,以及国家 [xx] 不在可用选项之中。最后这项检查由 [ChoiceType] 字段自己执行,无需我们要求:恶意用户可以提交任何内容,而不仅仅是页面提供的内容。消息是英文的:Form 组件的消息由 [Symfony] 翻译,验证器的消息也是如此(示例 09)。响应的状态码为 422(Unprocessable Content):[render] 在遇到已提交的无效表单时会自动选择它。请注意与其他框架的区别:[Symfony] 不会在动作之前拒绝请求;是表单声明自己无效,由动作决定如何继续。
要使令牌被接受,[curl] 必须表现得像浏览器:先请求表单,同时保留会话 Cookie(选项 [-c],将收到的 Cookie 保存到文件中),然后重新发送该 Cookie(选项 [-b])以及从页面中读取的令牌。选项 [--data-urlencode] 会对令牌值本身进行编码:
| curl -c cookies.txt http://localhost:8000/form
curl -b cookies.txt -g --data-urlencode "fields[_token]=9863be7bac.KU7N..." -d "fields[name]=Martin&fields[country]=xx" http://localhost:8000/form
|
| ...
<ul>
<li>title: The title is required.</li>
<li>country: The selected choice is invalid.</li>
</ul>
...
|
(令牌是第一条命令所收到页面中的那个。)只剩下两个输入错误。
4.7. 示例 19:表单验证
一个注册表单,其中每个字段都有自己的验证规则。如果出现错误,表单会连同用户的输入一起重新显示,并在每个有错误的字段下方给出一条消息。本示例使用 [Symfony] 的标准方法:表单数据是一个对象,其类包含约束(示例 08);表单填充该对象,然后验证它。
| 19-form-validation/
├── src/
│ ├── Controller/
│ │ └── RegistrationController.php
│ ├── Form/
│ │ └── RegistrationType.php
│ ├── Model/
│ │ └── Registration.php
│ └── Kernel.php
├── templates/
│ ├── registration/
│ │ ├── welcome.html.twig
│ │ └── registration.html.twig
│ └── layout.html.twig
└── ...
|
文件 [config/packages/framework.yaml] 和 [config/packages/twig.yaml] 与示例 18 中的相同。
4.7.1. 数据及其约束:src/Model/Registration.php
| <?php
// src/Model/Registration.php:注册表单的数据及其约束
namespace App\Model;
use Symfony\Component\Validator\Constraints as Assert;
class Registration
{
#[Assert\NotBlank(message: 'The name is required.')]
#[Assert\Length(max: 20, maxMessage: 'The name must not exceed 20 characters.')]
public ?string $name = null;
// Email:有效的地址,带有完整的域名(example.com,而不是 example)
#[Assert\NotBlank(message: 'The email address is required.')]
#[Assert\Email(message: 'Invalid email address.')]
public ?string $email = null;
#[Assert\NotBlank(message: 'The age is required.')]
#[Assert\Range(notInRangeMessage: 'The age must be between 18 and 120 years.', min: 18, max: 120)]
public ?int $age = null;
#[Assert\NotBlank(message: 'The password is required.')]
#[Assert\Length(min: 6, minMessage: 'The password must have at least 6 characters.')]
public ?string $password = null;
}
|
- 第 8 行:一个常规类,其属性是公共的且可修改;表单将逐个填充它们。所有属性都初始化为 [null];对象在首次显示时是空的;
- 第 10–12 行:姓名是必填的,且不得超过 20 个字符。这里每个约束都被赋予了自己的消息,为英文(示例 09):[message] 用于 [NotBlank],[maxMessage] 用于超出 [Length] 限制;
- 第 15–17 行:约束 [Email] 验证地址是否有效,并要求使用完全限定域名([example.com],而不是 [example]);
- 第 19–21 行:年龄是 18 到 120 之间的整数([notInRangeMessage]:当同时存在最小值和最大值时,[Range] 使用的消息)。表单会把输入转换为整数;
- 第 23–25 行:密码长度至少为 6 个字符。
| <?php
// src/Form/RegistrationType.php:注册表单的字段
namespace App\Form;
use App\Model\Registration;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\EmailType;
use Symfony\Component\Form\Extension\Core\Type\IntegerType;
use Symfony\Component\Form\Extension\Core\Type\PasswordType;
use Symfony\Component\Form\Extension\Core\Type\RepeatedType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;
class RegistrationType extends AbstractType
{
public function buildForm(FormBuilderInterface $builder, array $options): void
{
$builder
// attr:输入字段上额外的 HTML 属性(用于
// 浏览器验证,见后文)
->add('name', TextType::class, ['attr' => ['maxlength' => 20]])
->add('email', EmailType::class, ['label' => 'Email address'])
// IntegerType:整数;不是整数的输入会产生
// invalid_message 错误
->add('age', IntegerType::class, [
'label' => 'Age',
'attr' => ['min' => 18, 'max' => 120],
'invalid_message' => 'An integer is expected.',
])
// RepeatedType:两个必须接收相同值的字段(密码
// 及其确认);数据中只有一个值
->add('password', RepeatedType::class, [
'type' => PasswordType::class,
'first_options' => ['label' => 'Password', 'attr' => ['minlength' => 6]],
'second_options' => ['label' => 'Confirmation'],
'invalid_message' => 'The confirmation does not match the password.',
]);
}
// 表单的选项:其数据是一个 Registration 对象
public function configureOptions(OptionsResolver $options): void
{
$options->setDefaults(['data_class' => Registration::class]);
}
}
|
- 第 23 行:[attr] 选项为输入字段添加 HTML 属性:[maxlength] 在浏览器中限制输入;
- 第 24 行:[EmailType] 字段生成 [<input type="email">],浏览器可以对其进行验证;
- 第 27–31 行:[IntegerType] 字段生成 [<input type="number">] 并把输入转换为整数。不是整数的输入无法转换:这是一个转换错误(不是验证错误;参见示例 08),其错误消息由 [invalid_message] 选项提供;
- 第 34–39 行:[RepeatedType] 字段由两个字段(这里是两个 [PasswordType] fields)组成,二者必须包含相同的值:密码及其确认。每个字段都有自己的选项([first_options]、[second_options]);如果两次输入不同,错误为 [invalid_message]。数据只有一个值:密码;
- 第 43–46 行:方法 [configureOptions] 设置表单本身的选项:[data_class] 表示其数据是一个 [Registration] 对象。每个字段读写同名的属性。
[Symfony] 还可以根据约束和属性的类型来推断字段的类型:[->add('age')] 没有指定类型,会生成一个 [IntegerType],其属性 [min] 和 [max] 由 [Range] 推断得出。为清晰起见,我们在这里明确写了出来。
4.7.3. 控制器:src/Controller/RegistrationController.php
| <?php
// src/Controller/RegistrationController.php:由服务器验证的表单
namespace App\Controller;
use App\Form\RegistrationType;
use App\Model\Registration;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\MapQueryParameter;
use Symfony\Component\Routing\Attribute\Route;
class RegistrationController extends AbstractController
{
// GET /register:表单;?html5=true:我们让浏览器在发送之前
// 对其进行验证。POST /register:发送的表单
#[Route('/register', name: 'register', methods: ['GET', 'POST'])]
public function register(Request $request, #[MapQueryParameter] bool $html5 = false): Response
{
$registration = new Registration();
$form = $this->createForm(RegistrationType::class, $registration);
$form->handleRequest($request);
// isValid:字段可以被转换,并且 Registration 对象
// 符合其约束
if ($form->isSubmitted() && $form->isValid()) {
return $this->render('registration/welcome.html.twig', ['registration' => $registration]);
}
// 首次显示,或者无效的表单连同输入和错误再次显示
// (render 随后以 422 状态码将其发回)
return $this->render('registration/registration.html.twig',
['form' => $form, 'html5' => $html5]);
}
}
|
- 第 19 行:参数 [?html5=true] 启用浏览器验证(见下文)。[#[MapQueryParameter]] 将其转换为布尔值(示例 07);
- 第 21–23 行:空对象 [Registration] 被传递给表单;[handleRequest] 会使用提交的字段填充它;
- 第 26–28 行:[isValid] 在每个字段都能被转换、并且 [Registration] 对象满足其约束时为真。欢迎页面随后会接收填好的对象(下一个示例将表明,POST 成功后最好进行重定向);
- 第 31–32 行:否则,显示表单:首次显示时为空;提交无效后,它会显示输入和错误,并附带状态码 422(示例 18)。
因此,无效的表单由 POST 动作本身重新显示,它保留输入和错误:这是 [Symfony] 采用的方法。其他框架,例如 [Laravel],则是重定向到表单页面作为响应,同时把输入和错误保留在会话中供下一个请求使用。
4.7.4. 视图
| {% extends 'layout.html.twig' %}
{% block content %}
<h1 class="h3">Registration</h1>
{% if html5 %}
<p>Browser validation <b>enabled</b> - <a href="{{ path('register') }}">disable it</a></p>
{% else %}
<p>Browser validation <b>disabled</b> - <a href="{{ path('register', {html5: 'true'}) }}">enable it</a></p>
{% endif %}
{# novalidate:浏览器忽略 required、min... 属性,并按原样发送
表单;只有服务器进行验证 #}
{{ form_start(form, {attr: html5 ? {} : {novalidate: 'novalidate'}}) }}
{# form_widget:表单的所有字段,每个字段都带有其标签和错误 #}
{{ form_widget(form) }}
<button class="btn btn-primary" type="submit">Register</button>
{{ form_end(form) }}
{% endblock %}
{% block page_bottom %}
{# 全局错误,位于页面底部,背景为浅粉色。vars:表单的
信息(是否已发送?是否有效?) #}
{% if form.vars.submitted and not form.vars.valid %}
<div class="error-area" role="alert">The form contains errors.</div>
{% endif %}
{% endblock %}
|
- 第 12 行:属性 [novalidate] 禁用浏览器验证:表单按原样提交,只有服务器对其进行验证。这正是我们首先想要观察的。三元运算符在两个属性数组之间进行选择;
- 第 14 行:[form_widget(form)] 应用于整个表单,写出它的所有字段,每个字段都带有标签、输入和错误消息:[Bootstrap] 主题会把无效字段标为红色(类 [is-invalid]),并在其下方显示消息(类 [invalid-feedback])。为此我们无需编写任何组件;
- 第 19–25 行:由模板定义的 [page_bottom] 块(见下文)。[form.vars] 包含为视图计算出的表单数据:[submitted] (是否已提交?)、[valid] (是否有效?)、[value]、[errors]等。如果表单已提交且无效,则会在一个字段中显示一条总体消息,其样式由 [public/css/styles.css] 定义(示例 15)。[role="alert"] 属性向屏幕阅读器标示这一点。
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Registration</title>
<link rel="stylesheet" href="{{ path('bootstrap', {file: 'css/bootstrap.min.css'}) }}">
<link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
<div class="container py-3" style="max-width: 36rem">
<main>
{% block content %}{% endblock %}
</main>
{# 页面可以填充的块,位于页面底部 #}
{% block page_bottom %}{% endblock %}
</div>
</body>
</html>
|
- 第 15 行:第二个块 [page_bottom],默认为空:一个模板可以根据需要拥有任意多个块。
| {% extends 'layout.html.twig' %}
{% block content %}
{# registration:Registration 对象,由表单填充 #}
<h1 class="h3">Welcome {{ registration.name }}</h1>
<p>Your registration is saved: address <b>{{ registration.email }}</b>,
age <b>{{ registration.age }}</b> years.</p>
{% endblock %}
|
[registration] 是对象 [Registration],已填充并验证:姓名已去除空格(见下文),年龄是整数。
4.7.5. 执行
让我们提交一个满是错误的表单:由空格组成的姓名、没有完整域名的地址、12 岁的年龄、过短的密码,以及不一致的确认密码:

输入已被保留(密码除外),每个错误都标示在对应字段的下方。由空格组成的姓名被标示为缺失:Form 组件会去除每个输入两端的空格(字段选项 [trim],默认为 true)。而密码只有一个错误,位于确认字段:当两次输入不同时,[RepeatedType] 字段不返回任何值,因此不检查长度。URL 是表单的 ID,而 [/register] 表示该页面是由动作响应 POST 而显示的。使用 [curl],像示例 18 那样提供防 CSRF 令牌,你还可以发送浏览器不会发送的内容——非数字的年龄:
| curl -i -b cookies.txt -g --data-urlencode "registration[_token]=..." -d "registration[name]=Martin®istration[email]=martin@example.com®istration[age]=abc®istration[password][first]=abcdef®istration[password][second]=abcdef" http://localhost:8000/register
|
| HTTP/1.1 422 Unprocessable Content
...
<input type="number" id="registration_age" name="registration[age]" required="required" min="18" max="120" aria-describedby="registration_age_error1" aria-invalid="true" class="form-control is-invalid" value="abc" />
<div class="invalid-feedback d-block" id="registration_age_error1">An integer is expected.</div>
...
|
我们看到输入被重新显示,同时还有 HTML5 属性([required]、[min]、[max])、类 [is-invalid]、转换消息,以及属性 [aria-...],它们为屏幕阅读器把字段与其消息关联起来。
4.7.6. 浏览器验证
让我们通过点击“启用”链接(参数 [?html5=true])来移除 [novalidate] 属性。这样浏览器在提交表单之前会检查 [required]、[type="email"]、[min]、[maxlength] 等属性,并在第一个有错误的字段下方的提示框中显示它自己的消息(“请填写此字段”“值必须大于或等于 18”等):只要还有错误,表单就不会被提交。[Symfony] 会自动生成这些属性:[required] 用于任何字段(选项 [required],例如 18),[type="email"] 和 [type="number"] 根据字段类型生成;[maxlength]、[min]、[max]和 [minlength] 来自我们的 [attr] 选项。它们必须与约束保持一致。
这种验证对用户来说很方便:它是即时的,无需与服务器往返。但它不能取代服务器端验证:用户可以禁用它,而像 [curl] 这样的程序会完全忽略它。规则是绝对的:服务器始终要进行验证;浏览器端验证只是额外的便利。
终于有了一个正确的输入。两侧带有空格输入的姓名已被表单清理:

4.8. 示例 20:Post/Redirect/Get 模式
当 POST 动作以页面作为响应时,该页面是 POST 的结果。如果用户重新加载页面(按 [F5]),浏览器会重新发送 POST 请求,并在此之前显示一条很少有人阅读的警告:命令被发送了两次,消息也被发布了两次。Post/Redirect/Get 模式(PRG)可以避免这个问题:成功的 POST 动作不返回页面;它以重定向 (示例 04)到一个 GET 页面作为响应,浏览器会立即请求该页面。重新加载这个页面只是重新执行 GET 动作。
还剩一个问题:GET 页面想要显示一条消息(“任务已添加”),但知道这条消息的是 POST 动作,而它无法向尚未发生的请求传递变量。解决方案是:闪现消息,由 POST 动作放入会话 中,保留到被读取为止,显示一次后即被丢弃。
4.8.1. 配置:config/packages/framework.yaml
| # config/packages/framework.yaml:FrameworkBundle 的配置
framework:
secret: '%env(APP_SECRET)%'
# 会话(SESSION):其数据存储在服务器上,每个会话一个文件,
# 位于 var/sessions/dev 文件夹中(handler_id: null:PHP 自己的文件)
session:
handler_id: null
save_path: '%kernel.project_dir%/var/sessions/%kernel.environment%'
# 锁(Lock 组件):var/lock 文件夹中被锁定的文件(flock)
lock: 'flock://%kernel.project_dir%/var/lock'
|
- 第 6–8 行:用户的会话 (参见作用域一章):特定于浏览器的数据,在一个请求到下一个请求之间保留。它存储在服务器上;浏览器只在 Cookie 中保存它的标识符。[handler_id: null] 把存储这些数据的任务委托给 [PHP] 本身,它把每个会话存储在一个文件中;[save_path] 选择文件夹——[var/sessions/dev]——以便我们检查这些文件。[%kernel.environment%] 是环境([dev]);
- 第 10 行:锁 (Lock 组件,下文介绍),存储在文件夹 [var/lock] 中。
4.8.2. 服务:src/Service/TasksService.php
| <?php
// src/Service/TasksService.php:任务列表,由所有
// 用户共享。在 PHP 中,对象不会在请求之后保留:该列表
// 存储在应用程序的缓存中(这里是 var/cache/dev/pools 文件夹中的一个文件)
namespace App\Service;
use Psr\Cache\CacheItemPoolInterface;
use Symfony\Component\Lock\LockFactory;
class TasksService
{
private const KEY = 'tasks';
// 应用程序的缓存(cache.app 服务)和锁工厂
public function __construct(
private CacheItemPoolInterface $cache,
private LockFactory $locks,
) {
}
/** @return list<string> */
public function list(): array
{
// 存储在 [tasks] 键下的缓存项;isHit:它存在
$item = $this->cache->getItem(self::KEY);
return $item->isHit() ? $item->get() : ['Read chapter 3'];
}
public function add(string $label): void
{
// 多个请求可能同时运行(服务器用多个进程
// 处理它们):锁保证同一时间只有一个请求
// 读取、修改并重写该列表
$lock = $this->locks->createLock('tasks');
// acquire(true):等待锁空闲,然后获取它
$lock->acquire(true);
try {
$tasks = $this->list();
$tasks[] = $label;
// 缓存项接收其新值,没有任何时间限制
$item = $this->cache->getItem(self::KEY);
$this->cache->save($item->set($tasks));
} finally {
// finally:无论如何都会释放锁,即使在异常之后也是如此
$lock->release();
}
}
}
|
任务列表由所有用户共享,并且必须在一个请求到下一个请求之间持久保存。在 [Java]、[C#]或 [Python] 中,它会保存在单个服务的内存中。在 [PHP] 中这是不可能的:正如我们在示例 01 和 06 中看到的,没有任何东西能在请求结束后留存。因此,列表必须存储在 [PHP] 之外:数据库、文件……或者应用程序缓存中,这里我们使用的就是缓存。
- 第 16–20 行:该服务从 [Symfony] 接收两个服务。第一个是应用程序缓存 (来自 Cache 组件的 [cache.app] 服务),一个键值对存储,由标准化接口 [CacheItemPoolInterface] (PSR-6 标准)表示。默认情况下,它把值存储在 [var/cache/dev/pools] 文件夹的文件中;在生产环境中,更倾向于使用专用服务器,例如 [Redis] (只需一行配置)。第二个是 Lock 组件的锁工厂 ;
- 第 23–28 行:[getItem] 检索存储在某个键下的缓存项;[isHit] 检查它是否存在,[get] 返回它的值。可以存储任何值(这里是字符串数组):[Symfony] 会对其进行序列化——也就是说,使用 [serialize] 函数(来自 [PHP])将其转换为文本;
- 第 35–47 行:开发服务器与生产服务器一样,可以跨多个进程同时处理多个请求(环境变量 [PHP_CLI_SERVER_WORKERS] 设置 [php -S] 的进程数)。两个同时进行的添加操作可能读取到同一个列表,各自向其中添加自己的任务,然后再写回:第二次写入会覆盖第一个任务。锁 确保同一时刻只有一个请求执行它所保护的代码:[createLock('tasks')] 创建一个命名锁;[acquire(true)] 等待它变为可用,然后获取它;[release()] 释放它。这里,锁是 [var/lock] 文件夹中的一个文件,由操作系统锁定([flock] 函数);此外,多个服务器可以共享存储在 [Redis] 或数据库中的锁;
- 第 38–47 行:[try] …… [finally] 块确保在任何情况下都会释放锁,即使异常中断了它所保护的代码;
- 第 42–43 行:缓存元素获得新值([set]),然后被保存([save])。如果不指定生存期,它将被无限期保留([expiresAfter(3600)] 会把它保留一小时)。
4.8.3. 控制器:src/Controller/TasksController.php
| <?php
// src/Controller/TasksController.php:Post / Redirect / Get 模式
namespace App\Controller;
use App\Service\TasksService;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
class TasksController extends AbstractController
{
public function __construct(private TasksService $tasks)
{
}
// GET /tasks:列表和添加表单
#[Route('/tasks', name: 'tasks', methods: ['GET'])]
public function display(): Response
{
return $this->render('tasks/tasks.html.twig', ['tasks' => $this->tasks->list()]);
}
// POST /tasks:Post / Redirect / Get 模式
#[Route('/tasks', name: 'tasks_add', methods: ['POST'])]
public function add(Request $request): Response
{
$label = trim($request->request->getString('label'));
if ($label === '' || mb_strlen($label) > 40) {
// 无效的输入:我们再次显示页面,而不重定向
return $this->render('tasks/tasks.html.twig', ['tasks' => $this->tasks->list(),
'label' => $label,
'error' => 'The label must have 1 to 40 characters.']);
}
$this->tasks->add($label);
// addFlash 在会话中留下一条“闪现”消息:它会在重定向之后
// 保留到下一次请求
$this->addFlash('success', "The task [$label] has been added.");
// 没有页面:重定向到 GET 页面
return $this->redirectToRoute('tasks');
}
// POST /tasks/without-prg:反例(对 POST 直接响应一个页面)
#[Route('/tasks/without-prg', name: 'tasks_without_prg', methods: ['POST'])]
public function addWithoutPrg(Request $request): Response
{
$this->tasks->add(trim($request->request->getString('label')) ?: '(untitled)');
return $this->render('tasks/tasks.html.twig', ['tasks' => $this->tasks->list(), 'withoutPrg' => true]);
}
}
|
- 第 29–35 行:为了使示例简洁,输入由手工验证([trim] 去除两端的空格)。无效的输入会重新显示而不重定向:因为没有任何内容被修改,所以无需防范重复提交;
- 第 39 行:[addFlash] 方法(来自 [AbstractController] )把一条类型为 闪现 [success] 的消息放入会话中(类型是任意的:它可用于区分成功消息和错误消息等);
- 第 41 行:重定向到名为 [tasks] 的 GET 页面(示例 04);
- 第 45–50 行:反例:对 POST 的响应是一个页面。运算符 [?:] 在左操作数为“真”(这里是非空字符串)时返回左操作数,否则返回右操作数。
4.8.4. 视图
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Tasks</title>
<link rel="stylesheet" href="{{ path('bootstrap', {file: 'css/bootstrap.min.css'}) }}">
<link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
<div class="container py-3" style="max-width: 36rem">
{# [success] 闪现消息,位于页面顶部:在重定向之前留下;
app.flashes 在读取它们的同时将其从会话中移除 #}
{% for message in app.flashes('success') %}
<div class="alert alert-success" role="status">{{ message }}</div>
{% endfor %}
<main>
{% block content %}{% endblock %}
</main>
{% if error is defined %}
<div class="error-area" role="alert">{{ error }}</div>
{% endif %}
</div>
</body>
</html>
|
- 第 13–15 行:[app.flashes('success')] 返回类型为 [success] 的闪现消息列表 并将它们从会话中移除:闪现消息只显示一次。[alert alert-success] 类(来自 [Bootstrap] )把消息显示在绿色边框中;
- 第 19–21 行:错误消息,位于页面底部,当动作生成了错误消息时显示。
| {% extends 'layout.html.twig' %}
{% block content %}
<h1 class="h3">My tasks</h1>
<ol>
{% for task in tasks %}
<li>{{ task }}</li>
{% endfor %}
</ol>
<form method="post" action="{{ path('tasks_add') }}" class="d-flex gap-2">
<input class="form-control" name="label" value="{{ label ?? '' }}" placeholder="New task">
<button class="btn btn-primary text-nowrap" type="submit">Add</button>
{# formaction:该按钮将同一个表单发送到另一个地址 #}
<button class="btn btn-outline-secondary text-nowrap" type="submit" formaction="{{ path('tasks_without_prg') }}">Add without PRG</button>
</form>
{% if withoutPrg is defined %}
<p class="text-danger mt-2">Page displayed in response to a POST: press F5 and the task will be added a second time.</p>
{% endif %}
{% endblock %}
|
- 第 11 行:[??] 运算符(属于 [Twig] )在左操作数不存在(或等于 [null])时返回右操作数:变量 [label] 只有在输入无效之后才存在;
- 第 14 行:按钮的 [formaction] 属性把表单提交到不同于其 [action] 属性所指定的地址:因此,单个表单可以触发两个不同的动作。
这个手工编写的表单缺少防 CSRF 令牌:为了让示例保持简单,我们将在下一个示例中添加它。
4.8.5. 闪现消息存储在哪里?
在 POST 请求和随后的 GET 请求之间,消息必须存储在某个地方:用户的会话 中,或服务器上。让我们用 [curl] 来检查,同时把 Cookie 存储在文件中(选项 [-c] 和 [-b],示例 18):
| curl -i -b cookies.txt -c cookies.txt -d "label=Do%20the%20exercises" http://localhost:8000/tasks
|
| HTTP/1.1 302 Found
Cache-Control: max-age=0, must-revalidate, private
Location: /tasks
Content-Type: text/html; charset=utf-8
Expires: Sun, 27 Sep 2026 09:36:41 GMT
Set-Cookie: PHPSESSID=1e1f574eccd93268b1eb829dd714a029; path=/; httponly; samesite=lax
...
|
对 POST 的响应是一个重定向(状态码 302,请求头 [Location]),并附带会话 Cookie [PHPSESSID] ([PHP] 为该 Cookie 指定的名称),其中包含会话 ID:32 个无法猜测的随机字符。该 Cookie 是 [httponly] 的(页面上的 [JavaScript] 无法读取它),并且是 [samesite=lax] 的(浏览器不会在来自其他站点的 POST 请求中发送它)。请求头 [Cache-Control] 和 [Expires] 防止缓存依赖于会话的响应。该标识符同时也是服务器上会话文件的名称:[var/sessions/dev/sess_1e1f574eccd93268b1eb829dd714a029]。下面是 POST 请求之后的该文件:
| _symfony_flashes|a:1:{s:7:"success";a:1:{i:0;s:43:"The task [Do the exercises] has been added.";}}_sf2_meta|a:3:{s:1:"u";i:1790501801;s:1:"c";i:1790501801;s:1:"l";i:0;}
|
这是 [PHP] 中会话的序列化格式:每项会话数据都以 [name|serialized value] 的形式写入。[a:1:{...}] 声明一个有 1 个元素的数组,[s:7:"success"] 表示一个 7 字节的字符串……它包含按类型排序的闪现消息([_symfony_flashes]),以及来自 [Symfony] 的元数据([_sf2_meta]:会话的创建日期和最后使用日期)。让我们把 Cookie 发回去,跟随重定向:
| curl -i -b cookies.txt -c cookies.txt http://localhost:8000/tasks
|
| HTTP/1.1 200 OK
...
<div class="alert alert-success" role="status">The task [Do the exercises] has been added.</div>
...
<li>Read chapter 3</li>
<li>Do the exercises</li>
...
|
消息由 [app.flashes] 显示并从会话中移除。现在已为空的会话甚至消失了:[Symfony] 不存储空会话,该文件已被删除。再发出一个 GET 请求,就不会再显示这条消息。而任务列表则存储在一个缓存文件中,其名称根据键计算得出([var/cache/dev/pools/app/VT2eLxVxyZ/P/W/CElt3eODhIKkushDZW1A]):
| 0
tasks
a:2:{i:0;s:14:"Read chapter 3";i:1;s:16:"Do the exercises";}
|
第一行是值的过期日期(0:永不过期),第二行是键,第三行是序列化后的列表。至于锁,它是一个空文件 [var/lock/sf.tasks.CFFUCEx.lock],系统会在修改期间锁定它。
4.8.6. 执行
添加任务:浏览器跟随了重定向;URL 是对应于 GET 的页面,可以安全地重新加载。

无效输入,连同其错误消息一起重新显示:

反例:页面是对 POST 的响应,其 URL 为 [/tasks/without-prg]。如果点击 [F5],浏览器会询问是否要重新提交表单;如果你同意,任务就会被第二次添加。

4.9. 示例 21:链接、按钮与确认
HTTP 协议的一条原则:GET 请求不会改变任何东西。浏览器、搜索引擎和预加载页面的工具会不经用户许可就随意跟随链接。因此,“删除”链接([<a href="/contacts/2/delete">])会很危险:爬取网站的机器人会把一切都删除。在 Web 应用程序中:
- 查看通过链接 ([<a href>])完成,它发送 GET 请求;
- 编辑(保存、复制、删除)通过放置在表单中的按钮 完成,表单受防 CSRF 令牌保护。
本示例管理一个联系人列表,并在每次删除之前显示确认窗口。
4.9.1. 配置:config/packages/framework.yaml
| # config/packages/framework.yaml:FrameworkBundle 的配置
framework:
secret: '%env(APP_SECRET)%'
# 包含 _method 字段(DELETE、PUT...)的 POST 表单会被处理
# 为该方法的请求
http_method_override: true
# 会话(闪现消息、防 CSRF 令牌),存储在 var/sessions 中(见示例 20)
session:
handler_id: null
save_path: '%kernel.project_dir%/var/sessions/%kernel.environment%'
csrf_protection: true
lock: 'flock://%kernel.project_dir%/var/lock'
|
- 第 6 行:HTML 表单只能发送 GET 和 POST 请求。然而,HTTP 协议还规定了其他方法:用于删除的 DELETE,以及用于修改的 PUT 和 PATCH。[Symfony] 绕过了这一限制:通过 [http_method_override] 选项,包含值为 [_method] 的隐藏字段 [DELETE](或 [PUT]、[PATCH])的 POST 表单会被视为该方法的请求。这就是方法伪装;
- 其余各行与示例 18 和 20 中的相同:会话、CSRF 保护和锁。
| <?php
// src/Service/ContactsService.php:联系人,由所有人共享,存储在
// 应用程序的缓存中(见示例 20)
namespace App\Service;
use App\Model\Contact;
use Psr\Cache\CacheItemPoolInterface;
use Symfony\Component\Lock\LockFactory;
class ContactsService
{
private const KEY = 'contacts';
public function __construct(
private CacheItemPoolInterface $cache,
private LockFactory $locks,
) {
}
/** @return array{contacts: list<Contact>, lastId: int} */
private function data(): array
{
$item = $this->cache->getItem(self::KEY);
return $item->isHit() ? $item->get() : [
'contacts' => [
new Contact(1, 'Marie Durand', '01 23 45 67 89'),
new Contact(2, 'Paul Martin', '06 12 34 56 78'),
new Contact(3, 'Philippe Jandot', '02 98 76 54 32'),
],
'lastId' => 3,
];
}
// 在锁定状态下修改数据:函数接收数据,
// 对其进行修改(&),并返回操作的结果
private function editData(callable $operation): mixed
{
$lock = $this->locks->createLock('contacts');
$lock->acquire(true);
try {
$data = $this->data();
$result = $operation($data);
$this->cache->save($this->cache->getItem(self::KEY)->set($data));
return $result;
} finally {
$lock->release();
}
}
/** @return list<Contact> */
public function list(): array
{
return $this->data()['contacts'];
}
// 联系人,如果不存在则为 null
public function read(int $id): ?Contact
{
return array_find($this->list(), fn (Contact $c) => $c->id === $id);
}
public function edit(int $id, string $name, string $phone): ?Contact
{
return $this->editData(function (array &$data) use ($id, $name, $phone) {
foreach ($data['contacts'] as $i => $contact) {
if ($contact->id === $id) {
// 联系人是不可变的(readonly):我们构建一个新的联系人,
// 用它替换数组中的旧联系人
return $data['contacts'][$i] = new Contact($id, $name, $phone);
}
}
return null;
});
}
public function add(string $name, string $phone): Contact
{
return $this->editData(function (array &$data) use ($name, $phone) {
$contact = new Contact(++$data['lastId'], $name, $phone);
$data['contacts'][] = $contact;
return $contact;
});
}
public function delete(int $id): ?Contact
{
return $this->editData(function (array &$data) use ($id) {
foreach ($data['contacts'] as $i => $contact) {
if ($contact->id === $id) {
// array_splice 从数组中删除第 i 项,并对后面的项重新编号
array_splice($data['contacts'], $i, 1);
return $contact;
}
}
return null;
});
}
}
|
联系人存储在缓存中,就像示例 20 中的任务一样。每个联系人是一个不可变的 [Contact] 对象(ID、姓名、电话号码),存储在一个数组中,并带有最近分配的 ID。关于 [PHP] 的几点说明:
- 第 37–49 行:所有修改都遵循相同的模式:获取锁、读取数据、修改数据、写回数据、释放锁。此方法只对数组写入一次;每次修改都向它传递一个函数(类型为 [callable],“可调用”),该函数接收数据并修改它。该函数必须修改数组本身,而不是副本:其参数声明为 [array &$data],其中 [&] 表示按引用传递 (没有 [&] 时,数组会被复制;参见示例 06)。匿名函数中的关键字 [use] 使其可以访问外层函数中的变量(第 65 行:[$id], [$name], [$phone]);
- 第 44 行:调用依次进行:[getItem] 返回该元素,[set] 为其赋值并返回元素本身,[save] 存储它;
- 第 63–75 行:联系人是不可变的:会创建一个新联系人,替换数组中的旧联系人。赋值是一个表达式,其值就是被赋的值:[return $data['contacts'][$i] = new Contact(...)] 替换联系人并返回它;
- 第 80 行:放在变量前面的 [++] 使变量加 1 并返回新值;
- 第 92 行:[array_splice] 从数组中移除一个元素,并对后面的元素重新编号;
- 对于不存在的联系人,这些方法返回 [null] :由控制器决定如何响应。
| <?php
// src/Form/ContactType.php:联系人详细信息的表单,带有两个提交按钮
namespace App\Form;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\SubmitType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\Validator\Constraints\NotBlank;
class ContactType extends AbstractType
{
public function buildForm(FormBuilderInterface $builder, array $options): void
{
$builder
->add('name', TextType::class, ['constraints' => [new NotBlank()]])
->add('phone', TextType::class, ['label' => 'Phone', 'constraints' => [new NotBlank()]])
// 两个提交按钮:表单会知道点击的是哪一个
->add('save', SubmitType::class, ['attr' => ['class' => 'btn-primary']])
->add('duplicate', SubmitType::class, ['attr' => ['class' => 'btn-outline-primary']]);
}
}
|
- 第 17–18 行:这两个字段是必填的;
- 第 20–21 行:两个提交按钮 ([SubmitType])是表单的一部分。提交表单时,浏览器会发送被点击按钮的名称,表单由此知道是哪一个。选项 [attr] 为它们指定来自 [Bootstrap] 的类。
| <?php
// src/Controller/ContactsController.php:链接(GET)和按钮(POST、DELETE)
namespace App\Controller;
use App\Form\ContactType;
use App\Model\Contact;
use App\Service\ContactsService;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Form\SubmitButton;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
use Symfony\Component\Routing\Attribute\Route;
#[Route('/contacts', name: 'contacts')]
class ContactsController extends AbstractController
{
public function __construct(private ContactsService $contacts)
{
}
// 联系人,如果不存在则返回 404 响应
private function contactOr404(?Contact $contact): Contact
{
return $contact ?? throw $this->createNotFoundException('unknown contact');
}
// 一个链接(<a href>):GET 请求,不修改任何内容
#[Route('', name: '', methods: ['GET'])]
public function list(): Response
{
return $this->render('contacts/list.html.twig', ['contacts' => $this->contacts->list()]);
}
// GET /contacts/2:详细信息;POST /contacts/2:它的两个按钮之一
#[Route('/{id<\d+>}', name: '_details', methods: ['GET', 'POST'])]
public function details(Request $request, int $id): Response
{
$contact = $this->contactOr404($this->contacts->read($id));
$form = $this->createForm(ContactType::class,
['name' => $contact->name, 'phone' => $contact->phone]);
$form->handleRequest($request);
if ($form->isSubmitted() && $form->isValid()) {
['name' => $name, 'phone' => $phone] = $form->getData();
$duplicate = $form->get('duplicate');
// isClicked:发送表单的按钮
if ($duplicate instanceof SubmitButton && $duplicate->isClicked()) {
$copy = $this->contacts->add("$name (copy)", $phone);
$this->addFlash('success', "The contact [$copy->name] has been created.");
} else {
$this->contacts->edit($id, $name, $phone);
$this->addFlash('success', "The contact [$name] has been edited.");
}
return $this->redirectToRoute('contacts');
}
return $this->render('contacts/details.html.twig', ['contact' => $contact, 'form' => $form]);
}
// 一个 DELETE 请求,由 POST 表单模拟(隐藏的 _method 字段)
#[Route('/{id<\d+>}', name: '_delete', methods: ['DELETE'])]
public function delete(Request $request, int $id): Response
{
// 表单的防 CSRF 令牌,专用于该联系人
if (! $this->isCsrfTokenValid("delete-contact-$id", $request->request->getString('_token'))) {
throw new AccessDeniedHttpException('invalid anti-CSRF token');
}
$contact = $this->contactOr404($this->contacts->delete($id));
$this->addFlash('success', "The contact [$contact->name] has been deleted.");
return $this->redirectToRoute('contacts');
}
}
|
- 第 16 行:名称前缀 [contacts]:因此列表路由(其名称为空,见第 30 行)被命名为 [contacts],而记录路由为 [contacts_details]……;
- 第 24–27 行:一个工具函数:对于不存在的联系人,动作会以 404 响应终止;
- 第 30–34 行:列表的 GET 动作,它不修改任何内容;
- 第 37–58 行:联系人的记录。在 GET 中,它显示表单,并填入联系人的信息;在 POST 中,它处理表单。因此,查看和保存使用同一个 URL 和 [/contacts/2];
- 第 45 行:表单数据,一个非结构化的关联数组:[['name' => $name, 'phone' => $phone] = ...] 把每个元素存入一个变量;
- 第 46–54 行:[get('duplicate')] 返回表单上的 [duplicate] 按钮;[isClicked()] 判断提交表单的是否是它([instanceof SubmitButton] 测试向编辑器确认对象类型)。根据按钮的不同,动作要么复制联系人,要么保存联系人;
- 第 55 行:在这两种情况下,都采用 PRG 模式(示例 20),并带有一条闪现消息;
- 第 61–71 行:删除,由 DELETE 请求处理(URL 相同,但使用不同的方法)。删除表单是硬编码在视图中的:动作使用 [isCsrfTokenValid] 方法(来自 [AbstractController])验证它自己的防 CSRF 令牌。令牌与一个标识符 (这里是 [delete-contact-2])相关联:表单的令牌只对该表单有效。令牌缺失或无效时,动作会以 403 错误(Forbidden)终止。(设置在动作上的 [#[IsCsrfTokenValid('...')]] 属性也会执行同样的验证。)
4.9.5. 视图
| {% extends 'layout.html.twig' %}
{% block content %}
<h1 class="h3">Contacts</h1>
<table class="table align-middle">
<tbody>
{% for contact in contacts %}
<tr>
<td>{{ contact.name }}</td>
<td>{{ contact.phone }}</td>
<td class="text-end">
{# view:一个简单的链接;path() 将 id 放入路径中:/contacts/2 #}
<a class="btn btn-sm btn-outline-primary" href="{{ path('contacts_details', {id: contact.id}) }}">View</a>
{# delete:一个表单,其提交将需要确认 #}
<form method="post" class="d-inline" action="{{ path('contacts_delete', {id: contact.id}) }}"
data-confirmation="Delete the contact {{ contact.name }}?">
{# DELETE 方法,HTML 表单无法发送它 #}
<input type="hidden" name="_method" value="DELETE">
{# 防 CSRF 令牌,专用于该联系人 #}
<input type="hidden" name="_token" value="{{ csrf_token('delete-contact-' ~ contact.id) }}">
<button class="btn btn-sm btn-outline-danger" type="submit">Delete</button>
</form>
</td>
</tr>
{% endfor %}
</tbody>
</table>
{% endblock %}
|
- 第 13 行:一个链接,通过 [Bootstrap] 的类([btn]……)显示为按钮:外观与 HTTP 方法无关。[path('contacts_details', {id: contact.id})] 把 ID 放入路径:[/contacts/2];
- 第 15–22 行:每个“删除”按钮对应一个表单 ,除方法和令牌外没有其他字段。[d-inline] 类使其与链接显示在同一行。[data-confirmation] 属性包含确认消息:[data-...] 属性不被预先赋予含义,是留给页面上的 [JavaScript] 使用的;
- 第 18 行:隐藏字段 [_method],它把这个 POST 变成 DELETE 请求;
- 第 20 行:防 CSRF 令牌,由 [csrf_token] 函数(来自 [Twig])为标识符 [delete-contact-2] 生成([~] 运算符用于连接,示例 16)。
| {% extends 'layout.html.twig' %}
{% block content %}
<h1 class="h3">Contact no. {{ contact.id }}</h1>
{{ form_start(form) }}
{{ form_row(form.name) }}
{{ form_row(form.phone) }}
{# 同一个表单的两个提交按钮,并排放置 #}
<div class="d-flex gap-2">
{{ form_widget(form.save) }}
{{ form_widget(form.duplicate) }}
<a class="btn btn-link" href="{{ path('contacts') }}">Back to the list</a>
</div>
{{ form_end(form) }}
{% endblock %}
|
- 第 10–11 行:两个表单按钮,由 [form_widget] 渲染,并排显示;
- 第 12 行:返回列表的链接。[form_end] 将生成防 CSRF 令牌,Form 组件会自己验证它(示例 18)。
4.9.6. 确认窗口
浏览器可以显示确认对话框([JavaScript] 的函数 [confirm]),但它不太美观,而且外观取决于浏览器。这里我们使用来自 [Bootstrap] 的模态窗口,通过几行 [JavaScript] 来显示。该窗口是包含在模板中的片段,因此存在于所有页面上——尽管是隐藏的:
| {# 整个页面只有一个窗口,起初是隐藏的(d-none) #}
<div id="confirmation-modal" class="d-none">
<div class="modal-backdrop fade show"></div>
<div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true">
<div class="modal-dialog modal-dialog-centered">
<div class="modal-content">
<div class="modal-header">
<h5 class="modal-title">Confirmation</h5>
</div>
<div class="modal-body">
<p class="mb-0" id="confirmation-modal-message"></p>
</div>
<div class="modal-footer">
<button type="button" class="btn btn-secondary" data-action="no">No, go back</button>
<button type="button" class="btn btn-danger" data-action="yes">Yes, confirm</button>
</div>
</div>
</div>
</div>
</div>
|
- 第 2 行:来自 [d-none] 的 [Bootstrap] 类用于隐藏元素;
- 第 3–4 行:灰色背景以及随后的窗口,由 [Bootstrap] 的类渲染;
- 第 11 行:消息的位置;
- 第 14–15 行:两个按钮,类型为 [button] (而不是 [submit]:它们不提交任何表单),通过各自的 [data-action] 属性来区分。
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Contacts</title>
<link rel="stylesheet" href="{{ path('bootstrap', {file: 'css/bootstrap.min.css'}) }}">
<link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
<div class="container py-3" style="max-width: 40rem">
{% for message in app.flashes('success') %}
<div class="alert alert-success" role="status">{{ message }}</div>
{% endfor %}
<main>
{% block content %}{% endblock %}
</main>
</div>
{# 确认窗口,存在于所有页面中 #}
{% include 'fragments/confirmation.html.twig' %}
{# 脚本,位于页面末尾:它查找的元素已经存在 #}
<script src="{{ asset('js/app.js') }}"></script>
</body>
</html>
|
- 第 19 行:窗口,包含在所有页面上;
- 第 21 行:脚本,放在页面末尾:运行时,它所查找的元素已经存在。它存放在 [public/js] 文件夹中。
脚本 [public/js/app.js]:
| // 对带有 data-confirmation="..." 属性的表单进行确认
// 没有 JavaScript 时,这些表单只是不经确认直接发送。
(() => {
const modal = document.getElementById('confirmation-modal');
const message = document.getElementById('confirmation-modal-message');
let pending = null; // 用户确认时要发送的表单
// 1. 我们拦截需要确认的表单的提交
document.querySelectorAll('form[data-confirmation]').forEach((form) => {
form.addEventListener('submit', (event) => {
event.preventDefault(); // 提交被暂停
pending = form;
message.textContent = form.dataset.confirmation;
modal.classList.remove('d-none'); // 窗口出现
});
});
// 2. 窗口的两个按钮
modal.addEventListener('click', (event) => {
const action = event.target.dataset.action;
if (action === 'yes') {
pending.submit(); // 提交,不再次触发 'submit' 事件
} else if (action === 'no') {
modal.classList.add('d-none');
pending = null;
}
});
})();
|
- 第 3 行:代码被包含在一个匿名函数中,该函数立即执行;它的变量不会与页面上其他脚本的变量相互干扰;
- 第 4–6 行:窗口、消息位置,以及等待确认的表单;
- 第 9–17 行:对于每个带有 [data-confirmation] 属性的表单,拦截 [submit] 事件——表单提交时触发。[preventDefault()] 暂停提交;表单被搁置,其消息([dataset.confirmation],即 [data-confirmation] 属性的值)显示在窗口中,窗口随之出现;
- 第 20–28 行:窗口中点击事件的单一处理程序:[event.target] 是被点击的元素;其属性 [data-action] 指明是哪个按钮。“是”使用 [submit()] 方法提交待处理的表单,与点击按钮不同,该方法不会触发 [submit] 事件(否则窗口会再次出现);“否”则隐藏窗口。
没有 [JavaScript] 时,表单会不经确认直接提交:页面仍然可用。这就是渐进增强:[JavaScript] 增加便利,但应用程序并不依赖它。
4.9.7. 执行
联系人列表:

点击“Delete”会显示确认窗口:

确认之后,(模拟的)DELETE 请求、重定向和弹出消息:

联系人的资料页,带有它的两个提交按钮:

没有防 CSRF 令牌的请求会被拒绝,而不存在的联系人会返回 404 错误:
| curl -i -X POST -d "_method=DELETE" http://localhost:8000/contacts/3
curl -i http://localhost:8000/contacts/9
|
| HTTP/1.1 403 Forbidden
X-Debug-Exception: invalid%20anti-CSRF%20token
...
HTTP/1.1 404 Not Found
X-Debug-Exception: unknown%20contact
...
|
错误页面仍然是 [Symfony] 调试模式下的详细页面。请求生命周期一章将展示如何用自定义页面替换它们。