Skip to content

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):

1
2
3
4
5
6
7
<?php
// config/bundles.php:应用程序的 Bundle;TwigBundle 集成了
// Twig 视图引擎
return [
    Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
    Symfony\Bundle\TwigBundle\TwigBundle::class => ['all' => true],
];

并进行配置:

1
2
3
4
# 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. 执行

Image

Image

显示的时间对应于 [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 &lt;b&gt;martin</title>
...
  <h1>Hello &lt;b&gt;martin</h1>
  <p>This time, the title of the page comes from the URL.</p>
...

标签 [<b>] 被转义了,尽管动作和视图都没有对它做过任何处理(撇号也被转义了:[&#039;])。最后,下面是由 [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. 执行

Image

生成的页面:

<!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. &lt;b&gt;this is HTML&lt;/b&gt;</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] 的配置中声明:

1
2
3
4
5
6
# 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. 执行

Image

Image

Image

浏览器收到的团队页面:

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"
404

([-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
└── ...

4.4.1. 扩展:src/Twig/FormatsExtension.php

<?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. 执行

Image

Image

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

Image

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. 执行

Image

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

Image

结果页面上的 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 保护。
1
2
3
4
5
# 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]等)。应用程序可以编写自己的主题,或覆盖现有主题的某些块。

4.6.3. 表单类型:src/Form/FieldsType.php

<?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] (子表单列表)等。

4.6.4. 控制器:src/Controller/FormController.php

<?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 行:表单被传递给视图,视图将显示它,连同用户的输入和所有错误。

4.6.5. 视图:templates/form/form.html.twig

{% 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. 执行

Image

默认值是可见的:“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] 的一个可选脚本使用,它能增强保护;在这里没有任何作用。)让我们填写表单并提交:

Image

页面显示了服务器收到的内容:每个字段对应一个参数,复选框和下拉列表有多个值;密码已发送,但不会在其字段中再次显示。隐藏字段 [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
1
2
3
4
5
6
...
    <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 个字符。

4.7.2. 表单:src/Form/RegistrationType.php

<?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],默认为空:一个模板可以根据需要拥有任意多个块。
1
2
3
4
5
6
7
8
{% 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 岁的年龄、过短的密码,以及不一致的确认密码:

Image

输入已被保留(密码除外),每个错误都标示在对应字段的下方。由空格组成的姓名被标示为缺失: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&registration[email]=martin@example.com&registration[age]=abc&registration[password][first]=abcdef&registration[password][second]=abcdef" http://localhost:8000/register
1
2
3
4
5
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] 这样的程序会完全忽略它。规则是绝对的:服务器始终要进行验证;浏览器端验证只是额外的便利。

终于有了一个正确的输入。两侧带有空格输入的姓名已被表单清理:

Image

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
1
2
3
4
5
6
7
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
1
2
3
4
5
6
7
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]):

1
2
3
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 的页面,可以安全地重新加载。

Image

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

Image

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

Image

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 保护和锁。

4.9.2. 服务:src/Service/ContactsService.php

<?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] :由控制器决定如何响应。

4.9.3. 联系人记录的表单:src/Form/ContactType.php

<?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] 的类。

4.9.4. 控制器:src/Controller/ContactsController.php

<?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. 执行

联系人列表:

Image

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

Image

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

Image

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

Image

没有防 CSRF 令牌的请求会被拒绝,而不存在的联系人会返回 404 错误:

curl -i -X POST -d "_method=DELETE" http://localhost:8000/contacts/3
curl -i http://localhost:8000/contacts/9
1
2
3
4
5
6
HTTP/1.1 403 Forbidden
X-Debug-Exception: invalid%20anti-CSRF%20token
...
HTTP/1.1 404 Not Found
X-Debug-Exception: unknown%20contact
...

错误页面仍然是 [Symfony] 调试模式下的详细页面。请求生命周期一章将展示如何用自定义页面替换它们。