Skip to content

3. 动作模型

动作需要浏览器发送的信息:URL 的参数([?name=martin&age=42])、表单字段、JSON 请求正文,有时还有一个 HTTP 请求头。本课程把所有这些信息统称为动作模型。本章展示 [Symfony] 动作如何获取这些信息、把它们转换为正确的类型并验证它们。这个过程称为数据绑定。

[Symfony] 通过 [Request] 对象(示例 05)提供对请求信息的访问,以字符串的形式,并附带一些转换方法。它还可以绑定 这些信息到动作的参数上,方法是使用属性([#[MapQueryParameter]]、[#[MapQueryString]]、[#[MapRequestPayload]]),并验证它,使用的是其 Validator 组件:我们用约束 (“必填”“0 到 150 之间的整数”等)来描述期望的数据,这些约束写成 [PHP] 属性之类的形式,由验证器检查数据是否符合它们。我们先手工读取参数(示例 07),然后让框架负责它们的转换和验证(示例 08 至 12)。在下一章中,同样的约束将用来验证 HTML 表单。

请注意术语:在下一章中,“模型”一词主要指动作传递给其视图的数据。本章中所用的动作模型,则是它所接收的数据。

示例 07 至 12 的运行方式与上一章的示例相同:打开到示例文件夹的终端,[php -S localhost:8000 -t public];[Ctrl-C] 关闭服务器。大多数示例使用示例 03 中的监听器 [ReadableJson] ,从而得到可读的 JSON。我们只会在它们的配置文件引入新内容时才加以说明。

3.1. 示例 07:URL 的参数

URL 的参数是跟在 [?] 之后的部分:[?name=martin&age=42]。这一部分称为查询字符串。每个参数是一个 [name=value] 对;各对之间用 [&] 分隔。控制器 [ParametersController]:

<?php
// src/Controller/ParametersController.php:URL 的参数(“查询字符串”)

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\MapQueryParameter;
use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
use Symfony\Component\Routing\Attribute\Route;

#[Route('/parameters', name: 'parameters_', methods: ['GET'])]
class ParametersController extends AbstractController
{
    // /parameters/action01?name=martin:$request->query 包含
    // URL 的参数;get 返回参数的值,如果缺失则返回 null
    #[Route('/action01', name: 'action01')]
    public function action01(Request $request): Response
    {
        $name = $request->query->get('name');
        return new Response("name = [$name], of type ".get_debug_type($name));
    }

    // /parameters/action02?age=42:getInt 将值(字符串)转换为
    // 整数;缺失的参数得到 0,不是整数的值则会产生
    // 400 错误
    #[Route('/action02', name: 'action02')]
    public function action02(Request $request): Response
    {
        $age = $request->query->getInt('age');
        return new Response("age = [$age], of type ".get_debug_type($age));
    }

    // /parameters/action03?age=42:必需的参数,手动转换;
    // 缺失或不是整数的值会产生 400 响应
    #[Route('/action03', name: 'action03')]
    public function action03(Request $request): Response
    {
        $text = $request->query->get('age');
        if ($text === null) {
            // 一个 HTTP 异常:Symfony 会将其转换为 400 响应(Bad Request)
            throw new BadRequestHttpException('the [age] parameter is required');
        }
        // filter_var 返回字符串中包含的整数,或者 false
        $age = filter_var($text, FILTER_VALIDATE_INT);
        if ($age === false) {
            throw new BadRequestHttpException("[$text] is not an integer");
        }
        return new Response("age = [$age], of type ".get_debug_type($age));
    }

    // /parameters/action04?page=2:参数缺失时使用默认值
    #[Route('/action04', name: 'action04')]
    public function action04(Request $request): Response
    {
        $page = $request->query->getInt('page', 1);
        return new Response("page = [$page]");
    }

    // /parameters/action05?q=symfony:URL 参数的名称不一定与
    // PHP 变量的名称相同
    #[Route('/action05', name: 'action05')]
    public function action05(Request $request): Response
    {
        $search = $request->query->get('q');
        return new Response("search = [$search]");
    }

    // /parameters/action06?name=martin&age=42:一次性获取所有参数,以数组形式
    #[Route('/action06', name: 'action06')]
    public function action06(Request $request): JsonResponse
    {
        return $this->json($request->query->all());
    }

    // /parameters/action07?age=42&page=2:#[MapQueryParameter] 属性将
    // URL 参数绑定到同名的操作参数,并将其转换为
    // 相应的类型。没有默认值的参数是必需的
    #[Route('/action07', name: 'action07')]
    public function action07(#[MapQueryParameter] int $age, #[MapQueryParameter] int $page = 1): Response
    {
        return new Response("age = [$age], page = [$page]");
    }
}
  • 第 22 行:请求的 [query] 属性在一个参数“包”(一个 [InputBag] 对象)中包含 URL 的参数,其 [get] 方法返回某个参数的值(已解码),如果参数不存在则返回 [null] ;
  • 第 23 行:该动作显示值及其类型:函数 [get_debug_type] 返回值的类型名称。从 URL 获取的值始终是字符串([string])。运算符 [.] 把插值后的字符串与类型连接起来;
  • 第 32 行:[getInt] 方法读取参数并把它转换为整数。缺少的参数返回 0;不是整数的值([abc])会导致 400 错误(Bad Request)。类似地,还有 [getBoolean]([1]、[true]、[on] 和 [yes] 为真)、[getString]、[getAlpha] (仅字母)、[getDigits] (仅数字)、[getEnum] (一个列表);
  • 第 41–51 行:一个必填参数,以及区分两种可能错误的手工转换。[throw new BadRequestHttpException(message)] 以 400 响应终止操作,并附带该消息(见示例 03,其中也抛出过 404 异常)。[filter_var] 函数来自 [PHP],配合过滤器 [FILTER_VALIDATE_INT],返回字符串中包含的整数,如果字符串不是整数则返回 [false] ;
  • 第 58 行:[getInt] 的第二个参数是默认值,在参数缺失时使用。列表中的页码通常就是这种情况;
  • 第 67 行:并没有要求 [PHP] 变量必须与 URL 参数同名。搜索引擎经常使用一个简短的参数 [q] (query);
  • 第 75 行:[all()] 以关联数组的形式返回 URL 的所有 参数,动作再把它转换为 JSON(见示例 03);
  • 第 81–85 行:声明式的做法。属性 [#[MapQueryParameter]] 放在动作参数之前,把该参数与 URL 中的同名参数关联起来,并把它转换为所声明的类型([int])。没有默认值的参数是必填的:如果它缺失或无法转换,就会导致 404 错误(按所写的 URL 不对应任何有效页面)。默认值([$page = 1])使它成为可选的。这正是第 41–51 行所做的事情,只用一行就完成了。

让我们用 [curl] 测试每个动作。先是带参数的情况,然后是不带参数的情况:

curl -i "http://localhost:8000/parameters/action01?name=martin"
curl http://localhost:8000/parameters/action01
1
2
3
4
5
HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8

name = [martin], of type string
name = [], of type null

URL 两边的引号在终端中是必需的:没有引号的话,shell 会解释 [&] (它在 [Linux] 下会在后台运行一条命令)和 [?]。值 [null] 插入字符串时会变成空字符串。包含空格或特殊字符的值必须在 URL 中进行编码 :空格变成 [%20],而 [&] 变成 [%26] (否则它会分隔两个参数)。浏览器会自动处理这一点;使用 [curl] 时,则必须自己写出来。[PHP] 会在动作读取值之前对其解码:

curl "http://localhost:8000/parameters/action01?name=jean%20dupont%20%26%20fils"
name = [jean dupont & fils], of type string

使用 [getInt] 进行转换——成功、失败,然后是没有参数的情况:

1
2
3
curl "http://localhost:8000/parameters/action02?age=42"
curl -i "http://localhost:8000/parameters/action02?age=abc"
curl http://localhost:8000/parameters/action02
1
2
3
4
5
6
age = [42], of type int
HTTP/1.1 400 Bad Request
Content-Type: text/html; charset=UTF-8
X-Debug-Exception: Input%20value%20%22age%22%20cannot%20be%20converted%20to%20%22int%22.
...
age = [0], of type int

[Symfony] 拒绝把 [abc] 转换为整数:这是客户端错误,因此是 400 代码(“Input value 'age' cannot be converted to 'int'”)。然而,缺少参数时会悄悄地返回 0:动作无法把这种情况与实际输入的年龄 0 区分开来。动作 03 的必填参数缺失,因此无效。我们请求 JSON 响应(头部 [Accept],见示例 03),其中包含异常消息:

curl -i -H "Accept: application/json" http://localhost:8000/parameters/action03
curl -H "Accept: application/json" "http://localhost:8000/parameters/action03?age=abc"
1
2
3
4
5
HTTP/1.1 400 Bad Request
Content-Type: application/json

{"type":"https:\/\/tools.ietf.org\/html\/rfc2616#section-10","title":"An error occurred","status":400,"detail":"the [age] parameter is required","class":"Symfony\\Component\\HttpKernel\\Exception\\BadRequestHttpException","trace":[...]}
{"type":"https:\/\/tools.ietf.org\/html\/rfc2616#section-10","title":"An error occurred","status":400,"detail":"[abc] is not an integer","class":"Symfony\\Component\\HttpKernel\\Exception\\BadRequestHttpException","trace":[...]}

(这个紧凑的 JSON 不会被我们的监听器重新格式化,见示例 03)。在浏览器中,在调试模式下,400 响应会显示 [Symfony] 错误页面,并带有消息:

Image

默认值和重命名的参数:

1
2
3
curl http://localhost:8000/parameters/action04
curl "http://localhost:8000/parameters/action04?page=3"
curl "http://localhost:8000/parameters/action05?q=symfony"
1
2
3
page = [1]
page = [3]
search = [symfony]

同时给出所有参数。参数 [name] 出现了两次:

curl "http://localhost:8000/parameters/action06?name=martin&age=42&name=durand"
1
2
3
4
{
    "name": "durand",
    "age": "42"
}

参数 [name] 只保留它的最后一个值:这是 [PHP] 的规则,我们会在示例 10 中再次看到。年龄仍然是字符串(["42"],在 JSON 中用引号括起):因为没有请求转换。在浏览器中(这里是 [Chromium]),JSON 按服务器格式化的样子原样显示;如果它尚未缩进,“Pretty-print”复选框可以为它添加缩进。地址栏还显示了 URL 中带重音字符的编码([é] 变成 [%C3%A9],其两个字节采用 [UTF-8]):

Image

最后是通过 [#[MapQueryParameter]] 进行的绑定,分别带有和不带可选参数,然后是无效年龄的情况:

1
2
3
curl "http://localhost:8000/parameters/action07?age=42"
curl "http://localhost:8000/parameters/action07?age=42&page=3"
curl -i "http://localhost:8000/parameters/action07?age=abc"
1
2
3
4
5
6
age = [42], page = [1]
age = [42], page = [3]
HTTP/1.1 404 Not Found
Content-Type: text/html; charset=UTF-8
X-Debug-Exception: Invalid%20query%20parameter%20%22age%22.
...

如果没有参数 [age],消息将是“Missing query parameter 'age'”。404 代码可能会让人意外:该属性接受参数 [validationFailedStatusCode],可让你选择另一个代码([#[MapQueryParameter(validationFailedStatusCode: 400)]])。

第一个示例说明了手工方式的局限:对每个参数,你都必须编写读取、转换以及对缺失值和错误的处理。如果有十个参数,动作的代码就会被这些检查淹没。[#[MapQueryParameter]] 简化了转换,但对规则(“长度为 2 到 20 个字符的字符串”)只字未提。更好的做法是描述期望的内容,然后让框架来验证。这正是下一个示例的目的。

3.2. 示例 08:用类描述的动作模型

动作的模型可以用一个类来描述:每个期望的参数对应一个属性及其类型,并且以属性的形式写出它必须满足的约束 。[Symfony] 随后自己根据请求创建该对象、验证它,并把它传递给动作。这些约束是 Validator 组件的类:[NotBlank] (必填)、[Length] (长度)、[Range] (区间)、[Choice] (值列表)、[Email]、[Regex]……[Symfony] 提供了七十多个这样的约束。

3.2.1. 模型:src/Model/PersonModel.php

<?php
// src/Model/PersonModel.php:操作的模型,一个描述
// 预期参数及其约束的类

namespace App\Model;

use Symfony\Component\Validator\Constraints as Assert;

readonly class PersonModel
{
    public function __construct(
        // 必填,然后是 2 到 20 个字符的字符串:Sequentially 按顺序检查
        // 各个约束,并在第一个不满足的约束处停止
        #[Assert\Sequentially([
            new Assert\NotBlank(),
            new Assert\Length(min: 2, max: 20),
        ])]
        public ?string $name = null,
        // 必填,0 到 150 之间的整数
        #[Assert\NotNull]
        #[Assert\Range(min: 0, max: 150)]
        public ?int $age = null,
        // 必填,仅限这三个值之一
        #[Assert\NotBlank]
        #[Assert\Choice(choices: ['Mr', 'Mme', 'Melle'])]
        public ?string $title = null,
        // 可选;如果存在,则必须是有效的电子邮件地址
        #[Assert\Email]
        public ?string $email = null,
    ) {
    }
}
  • 第 7 行:导入约束命名空间,使用短名称 [Assert]:约束将写成 [Assert\NotBlank]、[Assert\Length]……这是所有 [Symfony] 项目中的标准做法;
  • 第 9–31 行:一个不可变类,其属性由构造函数初始化(示例 03)。每个属性都有默认值 [null],以及可空类型([?string]、[?int]:字符串,或 [null]):如果 URL 中缺少某个参数,该属性默认为 [null],再由一个约束来决定它是否必填。这是编写这类类的标准方式;
  • 第 14–18 行:姓名是必填的([NotBlank] 会拒绝 [null] 和空字符串),并且必须由 2 到 20 个字符组成([Length])。约束 [Sequentially] 按顺序检查它所包含的约束,并在第一个失败的约束处停止:空姓名只会产生一个错误,而不是两个。约束的参数是具名参数 ([min: 2]),这是自 [Symfony] 8 起的要求;
  • 第 20–22 行:年龄是必填的([NotNull]),并且必须在 0 到 150 之间([Range])。它的类型是 [?int]:[Symfony] 会把来自 URL 的字符串转换为整数;
  • 第 24–26 行:称谓是必填的,并且必须是所列三个值之一([Choice]);
  • 第 28–29 行:电子邮件地址是可选的(没有 [NotBlank] 约束);如果提供,它必须有效。除了约束 [NotBlank] 之外,其余的约束都接受 [null]:它们只验证存在的值。

这个模型描述了期望的数据;它不包含任何验证指令。这称为声明式风格。

3.2.2. 动作:src/Controller/PersonsController.php

<?php
// src/Controller/PersonsController.php:一个其模型为类的操作

namespace App\Controller;

use App\Model\PersonModel;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpKernel\Attribute\MapQueryString;
use Symfony\Component\Routing\Attribute\Route;

class PersonsController extends AbstractController
{
    // /persons/action01?name=martin&age=42&title=Mr
    // #[MapQueryString]:Symfony 根据 URL 的参数
    // 构建一个 PersonModel 对象,并在调用操作之前对其进行验证。无效的
    // 模型会引发异常(见 src/EventListener/ValidationErrors.php),
    // 并且操作永远不会被调用
    #[Route('/persons/action01', name: 'persons_action01', methods: ['GET'])]
    public function action01(Request $request, #[MapQueryString] PersonModel $person): JsonResponse
    {
        return $this->json([
            'received' => $request->query->all(),
            'person' => $person,
            'ageType' => get_debug_type($person->age),
        ]);
    }
}
  • 第 21 行:[#[MapQueryString]] 属性指示 [Symfony] 根据 URL 的参数构造 [$person] 参数。参数解析器(示例 05)分两步完成这项任务。首先,它进行转换:使用 Serializer,它创建一个 [PersonModel] 对象,其中每个属性接收 URL 中同名的参数,并转换为其对应的类型。然后,它对该对象进行验证:检查每个属性的每个约束。如果一切正确,就调用动作。否则,它会抛出异常(一个状态码为 404 的 [HttpException] ,其中包含一个 [ValidationFailedException],而它本身包含所有 错误的列表,而不仅仅是第一个错误),并且永远不会调用动作:因此动作不必担心无效数据;
  • 第 23–27 行:动作原样返回收到的参数,随后是 [PersonModel] 对象和年龄的类型,以说明二者的差别。

谁来处理这个异常?默认情况下,是 [Symfony] 自己,通过 404 错误响应(对于 [#[MapRequestPayload]] 则是 422,示例 11):即它的错误页面,或者对于请求 JSON 的客户端,则是一个详细列出各错误的文档。在这里,我们希望在所有情况下都返回 JSON 格式的错误响应,状态码为 400,并采用我们自己的格式。这就是监听器的作用。

3.2.3. 错误处理:src/EventListener/ValidationErrors.php

<?php
// src/EventListener/ValidationErrors.php:对于整个
// 应用程序,无效的模型都会产生一个详述错误的 400 响应

namespace App\EventListener;

use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpKernel\Event\ExceptionEvent;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\Validator\Exception\ValidationFailedException;

// [kernel.exception] 事件的监听器,当异常
// 从操作(或其参数的准备过程)中抛出时触发
#[AsEventListener(event: KernelEvents::EXCEPTION)]
class ValidationErrors
{
    public function __invoke(ExceptionEvent $event): void
    {
        // #[MapQueryString] 引发的 HTTP 异常包含验证的异常,
        // 而后者包含错误列表(“violations”)
        $validation = $event->getThrowable()->getPrevious();
        if (! $validation instanceof ValidationFailedException) {
            return;    // 另一个异常:Symfony 照常处理
        }
        $errors = [];
        foreach ($validation->getViolations() as $violation) {
            $errors[] = ['field' => $violation->getPropertyPath(), 'message' => $violation->getMessage()];
        }
        // 事件的响应会取代 Symfony 的错误页面
        $event->setResponse(new JsonResponse(['status' => 400, 'errors' => $errors], 400));
    }
}
  • 第 15 行:[kernel.exception] 事件的监听器(常量 [KernelEvents::EXCEPTION])。[Symfony] 会在动作执行期间或准备其参数时发生异常的情况下触发这个事件,时间在动作生成自己的错误响应之前。以这种方式声明后,监听器适用于应用中的所有 动作:每个验证模型的动作都能受益于它,而无需编写任何一行错误处理代码;
  • 第 22 行:事件是一个 [ExceptionEvent] 对象,它携带异常([getThrowable()])。由 [#[MapQueryString]] 抛出的异常是一个 HTTP 异常;[getPrevious()] 返回导致它的异常——即验证异常;
  • 第 23–25 行:如果不是验证错误,监听器什么也不做:[Symfony] 会照常处理该异常。运算符 [!] (非)用于反转条件;
  • 第 26–29 行:[getViolations()] 返回错误列表,这些错误被称为(约束)违规。每个违规都有一个路径([getPropertyPath()],即出错属性的名称)和一条消息。[$errors[] = ...] 向数组 [$errors] 的末尾添加一个元素;
  • 第 31 行:[setResponse] 向事件返回一个响应:一个状态码为 400 的 JSON 响应。[Symfony] 会发送它来取代自己的错误页面(并且和任何响应一样,它会经过监听器 [ReadableJson])。

3.2.4. 执行

一个有效的模型:

curl -i "http://localhost:8000/persons/action01?name=martin&age=42&title=Mr"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "received": {
        "name": "martin",
        "age": "42",
        "title": "Mr"
    },
    "person": {
        "name": "martin",
        "age": 42,
        "title": "Mr",
        "email": null
    },
    "ageType": "int"
}

收到的参数是字符串;[PersonModel] 对象则把年龄作为整数包含(在 JSON 中没有引号),而缺失的地址是 [null]。一个两侧带有空格的姓名([%20])和一个存在的地址:

curl "http://localhost:8000/persons/action01?name=%20%20martin%20&age=42&title=Mme&email=martin@example.com"
{
    "received": {
        "name": "  martin ",
        "age": "42",
        "title": "Mme",
        "email": "martin@example.com"
    },
    "person": {
        "name": "  martin ",
        "age": 42,
        "title": "Mme",
        "email": "martin@example.com"
    },
    "ageType": "int"
}

姓名两侧的空格被保留了下来:[Symfony] 不会转换收到的数据。约束可以在验证时忽略这些空格([new Assert\Length(min: 2, normalizer: 'trim')]),但值仍然是发送过来的那个值。在下一章中,Form 组件将去除这些空格。此时没有任何参数:三个必填字段缺失。

curl -i http://localhost:8000/persons/action01
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "status": 400,
    "errors": [
        {
            "field": "name",
            "message": "This value should not be blank."
        },
        {
            "field": "age",
            "message": "This value should not be null."
        },
        {
            "field": "title",
            "message": "This value should not be blank."
        }
    ]
}

同时有四个无效字段:

curl "http://localhost:8000/persons/action01?name=m&age=200&title=Mlle&email=xx"
{
    "status": 400,
    "errors": [
        {
            "field": "name",
            "message": "This value is too short. It should have 2 characters or more."
        },
        {
            "field": "age",
            "message": "This value should be between 0 and 150."
        },
        {
            "field": "title",
            "message": "The value you selected is not a valid choice."
        },
        {
            "field": "email",
            "message": "This value is not a valid email address."
        }
    ]
}

所有错误会一次性全部报告,使用户可以一次改正所有问题。最后是一个不是数字的年龄:

curl "http://localhost:8000/persons/action01?name=m&age=abc&title=Mlle&email=xx"
1
2
3
4
5
6
7
8
9
{
    "status": 400,
    "errors": [
        {
            "field": "age",
            "message": "This value should be of type int."
        }
    ]
}

这一次只报告了一个错误,尽管姓名、称谓和地址仍然无效。这是 [#[MapQueryString]] 所执行的两步过程的结果:转换 失败了([abc] 无法转换为整数),因此无法构造对象,而检查对象的验证也就没有进行。消息是英文的,这是 [Symfony] 的默认语言。下一个示例会定制其中的一部分消息。

3.3. 示例 09:由动作执行的验证

在示例 08 中,无效的模型会中断动作,由应用的监听器作出响应。这对于 API 很方便,因为它的客户端是期望标准化错误响应的程序。但网页通常更倾向于重新显示带有错误消息的表单:在这种情况下,动作必须自己决定如何处理无效的模型。它自己调用验证器。

09-action-validation/
├── config/
│   └── packages/
│       └── framework.yaml
├── src/
│   ├── Controller/
│   │   └── PersonsController.php
│   ├── Model/
│   │   └── PersonInput.php
│   └── Kernel.php
├── translations/
│   └── validators.en.yaml
└── ...

3.3.1. 模型:src/Model/PersonInput.php

<?php
// src/Model/PersonInput.php:一个人员的输入,保持其到达时的形式
// (字符串),以及它必须遵守的约束

namespace App\Model;

use Symfony\Component\Validator\Constraints as Assert;

class PersonInput
{
    #[Assert\Sequentially([
        new Assert\NotBlank(),
        new Assert\Length(min: 2, max: 20),
    ])]
    public ?string $name = null;

    // 一个由数字组成的字符串(digit),其值介于 0 和 150 之间;
    // message:专用于该约束的消息
    #[Assert\Sequentially([
        new Assert\NotBlank(),
        new Assert\Type('digit', message: 'an integer is expected'),
        new Assert\Range(min: 0, max: 150),
    ])]
    public ?string $age = null;

    #[Assert\NotBlank]
    #[Assert\Choice(choices: ['Mr', 'Mme', 'Melle'])]
    public ?string $title = null;

    #[Assert\Email]
    public ?string $email = null;
}

这一次,模型完全按收到的样子描述输入 :即字符串,由动作自己把它们复制到对象中。因此它的属性是普通属性(既不是提升的,也不是 [readonly]),并且全部是 [?string] 类型,包括年龄:

  • 第 19–24 行:年龄是一个字符串,它必须存在([NotBlank]),只包含数字([Type('digit')],用于验证字符串只包含数字),并且其值必须在 0 到 150 之间([Range] 接受表示数字的字符串)。多亏了 [Sequentially],年龄 [abc] 只会被报告一次。参数 [message] 用我们自己的消息替换约束的消息:每个约束都有这个参数(当约束有多种错误类型时则有多个,例如 [minMessage] 和 [maxMessage] ,用于 [Length]);
  • 其他属性使用示例 08 中的约束。

3.3.2. 自定义消息

验证器的错误消息在其代码中是用英语写的,但它们会经过 [Symfony] 翻译器 (Translation 组件),由它把消息翻译成请求所用的语言。[Symfony] 自带约六十种语言的消息翻译:只需选择应用的语言,并在 [config/packages/framework.yaml] 中启用翻译器:

1
2
3
4
5
6
7
8
# config/packages/framework.yaml:FrameworkBundle 的配置
framework:
    secret: '%env(APP_SECRET)%'
    # 应用程序的语言:验证消息将使用英语
    default_locale: en
    # 翻译服务;其字典位于 translations/ 文件夹中
    translator:
        default_path: '%kernel.project_dir%/translations'
  • 第 5 行:应用的默认语言(区域设置)。除非应用更改它(见国际化一章),否则这也是每个请求所用的语言;
  • 第 7–8 行:翻译器,其应用专属的字典位于 [translations] 文件夹中。[%kernel.project_dir%] 是容器参数:项目文件夹(示例 01)。

由 [Symfony] 翻译的消息并不总是合适。应用可以提供自己的翻译,它们具有更高的优先级。验证消息存放在 [validators] 域中;该域的英文翻译存放在 [translations/validators.en.yaml] 文件中(字典的名称由域、语言和格式组成):

1
2
3
4
5
# translations/validators.en.yaml:我们自己对验证
# 消息的翻译(域 [validators]),其优先级高于 Symfony 自带的翻译。
# 键是原始的英文消息
'This value should not be blank.': 'the field is required'
'The value you selected is not a valid choice.': 'unknown value'

字典把每个键与其翻译关联起来。对于验证器消息,键是原始的英文消息:['This value should not be blank.'] 将显示为“该字段为必填项。”键用单引号括起,因为它们包含在 [YAML] 中具有特殊含义的字符(句点、空格)。没有被这个文件翻译的消息保留来自 [Symfony] 的翻译([vendor/symfony/validator/Resources/translations/validators.en.xlf] 文件),而任何字典都不认识的消息则按原样显示:我们的消息“an integer is expected.”就是这种情况。

3.3.3. 动作:src/Controller/PersonsController.php

<?php
// src/Controller/PersonsController.php:由该操作决定如何处理无效的输入

namespace App\Controller;

use App\Model\PersonInput;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Validator\Validator\ValidatorInterface;

class PersonsController extends AbstractController
{
    // 验证器(VALIDATOR)是 Symfony 的一个服务,被注入到操作中(见示例 06)
    #[Route('/persons/action01', name: 'persons_action01', methods: ['GET'])]
    public function action01(Request $request, ValidatorInterface $validator): Response
    {
        // 输入:URL 的参数,被复制到对象中
        $input = new PersonInput();
        $input->name = $request->query->get('name');
        $input->age = $request->query->get('age');
        $input->title = $request->query->get('title');
        $input->email = $request->query->get('email');
        // validate 检查对象的约束,并返回错误列表
        $errors = $validator->validate($input);
        if (count($errors) > 0) {
            $items = '';
            foreach ($errors as $error) {
                $items .= "<li>{$error->getPropertyPath()}: {$error->getMessage()}</li>";
            }
            return new Response("<p>The form contains errors:</p><ul>$items</ul>");
        }
        // htmlspecialchars:输入的姓名会被插入到 HTML 中;其中的字符
        // < > & " ' 会被替换为 &lt; &gt;...(否则,输入可能会注入 HTML)
        return new Response("<p>Welcome $input->title ".htmlspecialchars($input->name)
            ." ($input->age years old)</p>");
    }
}
  • 第 17 行:验证器是来自 [Symfony] 的服务(类型为 [ValidatorInterface]),它作为应用服务被注入到动作中(示例 06);
  • 第 20–24 行:动作创建对象,并把 URL 中的参数复制到其中。我们本可以像示例 08 那样,让 [#[MapQueryString]] 来构造对象;但是,[#[MapQueryString]] 会立即验证它,并在出错时终止动作——这正是我们在这里想要避免的;
  • 第 26 行:[validate] 检查对象的约束,并返回违规列表(一个 [ConstraintViolationList] 对象,可以像数组一样迭代,其大小由 [count] 返回)。验证不会抛出任何异常:接下来做什么由动作自己决定;
  • 第 27–33 行:按字段逐个列出错误,每个错误都包含在一个 [<li>] 标签中。在用双引号括起的字符串中,[{$error->getMessage()}] 会插入方法调用的结果(花括号界定该表达式)。运算符 [.=] 把一个字符串追加到另一个字符串的末尾;
  • 第 36–37 行:如果成功,则显示一条欢迎消息。姓名要经过 [htmlspecialchars] 函数(来自 [PHP])处理,它会把在 HTML 中具有特殊含义的字符([<]、[>]、[&]、["]、['])替换为它们的实体 ([&lt;]、[&gt;]……):这些字符将按原样显示,而不会被解释。如果没有这一预防措施,用户可以输入包含 HTML 甚至 [JavaScript] 的“姓名”,它会在任何查看该页面的人的浏览器中执行。这是 Web 上最常见的安全漏洞:脚本注入 (XSS,跨站脚本)。称谓和年龄字段不需要这种保护:它们的值已经由约束验证过(三个允许值之一,全是数字)。在下一章中,[Twig] 视图引擎会对插入页面的任何值自动执行这种转义。

一个有效的输入,接着是一个包含四个错误的输入:

Image

Image

这些消息是英文的:有来自 [Symfony] 的(姓名、地址)、我们自己的(年龄),以及来自我们字典的(称谓)。对第二个请求——姓名中包含 HTML 的那个——的原始响应,以及对没有姓名且年龄过大的请求的响应:

1
2
3
curl "http://localhost:8000/persons/action01?name=m&age=abc&title=Mx&email=xx"
curl "http://localhost:8000/persons/action01?name=%3Cb%3Emartin%3C/b%3E&age=42&title=Mr"
curl "http://localhost:8000/persons/action01?age=200&title=Mr"
1
2
3
<p>The form contains errors:</p><ul><li>name: This value is too short. It should have 2 characters or more.</li><li>age: an integer is expected</li><li>title: unknown value</li><li>email: This value is not a valid email address.</li></ul>
<p>Welcome Mr &lt;b&gt;martin&lt;/b&gt; (42 years old)</p>
<p>The form contains errors:</p><ul><li>name: the field is required</li><li>age: This value should be between 0 and 150.</li></ul>

姓名 [<b>martin</b>] (在 URL 中编码为 [%3Cb%3E...] )按原样显示,没有被加粗:它的标签已被中和。请注意,这一次的响应状态码是 200:是动作选择返回包含这些错误的正常页面。

3.4. 示例 10:多个参数

同一个参数可以在 URL 中出现多次:[?color=red&color=green]。这就是浏览器为一组同名复选框或多选列表所发送的内容(见下一章)。[PHP] 以自己的方式处理这种情况。[ArraysController] 控制器:

<?php
// src/Controller/ArraysController.php:在 URL 中多次出现的参数

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Validator\Constraints as Assert;
use Symfony\Component\Validator\Validator\ValidatorInterface;

#[Route('/arrays', name: 'arrays_', methods: ['GET'])]
class ArraysController extends AbstractController
{
    // /arrays/action01?color=red&color=green:对于 PHP,第二个参数
    // 会替换第一个:只保留最后一个值
    #[Route('/action01', name: 'action01')]
    public function action01(Request $request): JsonResponse
    {
        return $this->json(['color' => $request->query->get('color'),
            'raw' => $request->server->get('QUERY_STRING')]);
    }

    // /arrays/action02?color[]=red&color[]=green:方括号要求
    // PHP 将所有值存储在一个数组中
    #[Route('/action02', name: 'action02')]
    public function action02(Request $request): JsonResponse
    {
        // all('color'):以数组形式表示的参数(缺失时为空)
        $colors = $request->query->all('color');
        return $this->json(['color' => $colors, 'count' => count($colors)]);
    }

    // /arrays/action03?color[]=red:一个数组,逐项验证
    #[Route('/action03', name: 'action03')]
    public function action03(Request $request, ValidatorInterface $validator): JsonResponse
    {
        $colors = $request->query->all('color');
        // 我们可以验证任何值(此处是数组),只需给出
        // 要验证的约束
        $violations = $validator->validate($colors, [
            // 至少包含一项的列表
            new Assert\Count(min: 1),
            // All:约束应用于每一项
            new Assert\All([new Assert\Choice(choices: ['red', 'green', 'blue'])]),
        ]);
        $errors = [];
        foreach ($violations as $violation) {
            $errors[] = "color{$violation->getPropertyPath()}: {$violation->getMessage()}";
        }
        return $this->json(['colors' => $colors, 'valid' => ! $errors, 'errors' => $errors]);
    }
}
  • 第 21–22 行:对 [PHP] 来说,URL 的参数构成一个关联数组,其中每个键只有一个值:重复的参数会替换前一个,只保留最后一个值。为了比较,该动作还返回浏览器所发送的原始参数字符串:请求的 [server] 属性包含 Web 服务器传递给 [PHP] 的变量,其中包括 [QUERY_STRING];
  • 第 28–33 行:要取回所有值,参数名称 必须以方括号结尾:[?color[]=red&color[]=green]。[PHP] 随后把这些值存放在一个数组中,该数组就是参数 [color] 的值。当给定参数名称时,方法 [all] 以数组形式返回该参数——如果参数不存在则返回空数组;
  • 第 37–53 行:对数组进行验证。验证器的 [validate] 方法接受任何值,只要指定了它的约束:这里是 [Count(min: 1)] (至少有一个元素的数组)和 [All],后者把它所包含的约束应用于数组的每个元素 :每个元素都必须是三种颜色之一;
  • 第 50 行:违规路径标识出出错的元素:[[1]] 表示第二个元素(索引从 0 开始),空字符串则表示数组本身。它会被附加到参数名称之后;
  • 第 52 行:运算符 [!] 对空数组求值为 [true] ,因为空数组在条件中被视为“false”。

示例中的 [translations/validators.en.yaml] 文件翻译了 [Choice] 约束的消息(示例 09)。结果如下:

1
2
3
curl "http://localhost:8000/arrays/action01?color=red&color=green"
curl -g "http://localhost:8000/arrays/action02?color[]=red&color[]=green"
curl http://localhost:8000/arrays/action02
{
    "color": "green",
    "raw": "color=red&color=green"
}
{
    "color": [
        "red",
        "green"
    ],
    "count": 2
}
{
    "color": [],
    "count": 0
}

[-g] 选项(来自 [curl] )可防止它自行解释 URL 中的方括号。另一方面,浏览器会对它们进行编码([color%5B%5D=red]),[PHP] 同样能理解这种编码。至于 HTML,只需把一组复选框命名为 [color[]] ([Symfony] 的 Form 组件会替我们完成这件事;见示例 18)。这条规则专属于 [PHP]:其他语言的框架([Flask]、[Spring MVC]、[ASP.NET Core])会保留重复参数的所有值,而不需要方括号。

[Symfony] 确保这两种形式不会被混淆:[get] 会拒绝数组类型的参数,而 [all] 会拒绝非数组类型的参数。两种情况下都会返回 400 错误:

curl -i -g "http://localhost:8000/arrays/action01?color[]=red"
curl -i "http://localhost:8000/arrays/action02?color=red"
1
2
3
4
5
6
HTTP/1.1 400 Bad Request
X-Debug-Exception: Input%20value%20%22color%22%20contains%20a%20non-scalar%20value.
...
HTTP/1.1 400 Bad Request
X-Debug-Exception: Unexpected%20value%20for%20parameter%20%22color%22%3A%20expecting%20%22array%22%2C%20got%20%22string%22.
...

验证先是成功,然后因未知颜色而失败,再因空列表而失败:

1
2
3
curl -g "http://localhost:8000/arrays/action03?color[]=red&color[]=blue"
curl -g "http://localhost:8000/arrays/action03?color[]=red&color[]=yellow"
curl http://localhost:8000/arrays/action03
{
    "colors": [
        "red",
        "blue"
    ],
    "valid": true,
    "errors": []
}
{
    "colors": [
        "red",
        "yellow"
    ],
    "valid": false,
    "errors": [
        "color[1]: unknown value"
    ]
}
{
    "colors": [],
    "valid": false,
    "errors": [
        "color: This collection should contain 1 element or more."
    ]
}

关于未知颜色的错误指向 [color[1]]:即参数以及数组中有问题元素的索引 。

3.5. 示例 11:POST 请求的参数

前面的示例使用的是 GET 请求,其参数包含在 URL 中。POST 请求把数据放在它的正文中,主要有两种形式:

  • HTML 表单的字段:正文的语法与查询字符串相同([name=martin&age=42]),其类型(头部 [Content-Type])为 [application/x-www-form-urlencoded];
  • 由程序发送的 JSON 文档(页面上的 [JavaScript] 、API 的客户端等):其类型为 [application/json]。

[PostController] 控制器:

<?php
// src/Controller/PostController.php:POST 请求的参数

namespace App\Controller;

use App\Model\PersonModel;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Exception\JsonException;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\MapRequestPayload;
use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
use Symfony\Component\HttpKernel\Exception\UnsupportedMediaTypeHttpException;
use Symfony\Component\Routing\Attribute\Route;

#[Route('/post', name: 'post_', methods: ['POST'])]
class PostController extends AbstractController
{
    // HTML 表单的字段(application/x-www-form-urlencoded 主体):
    // $request->request 包含请求主体的参数
    #[Route('/action01', name: 'action01')]
    public function action01(Request $request): JsonResponse
    {
        return $this->json([
            'receivedType' => $request->headers->get('Content-Type'),
            'fields' => $request->request->all(),
        ]);
    }

    // JSON 主体:toArray() 对其进行反序列化
    #[Route('/action02', name: 'action02')]
    public function action02(Request $request): JsonResponse
    {
        // 主体的格式,根据 Content-Type 头部推断:'json'、'form'...
        if ($request->getContentTypeFormat() !== 'json') {
            throw new UnsupportedMediaTypeHttpException('the body of the request must be JSON');
        }
        try {
            $body = $request->toArray();
        } catch (JsonException $e) {
            throw new BadRequestHttpException('Malformed JSON: '.$e->getMessage());
        }
        return $this->json(['receivedType' => $request->headers->get('Content-Type'), 'body' => $body,
            'name' => $request->getPayload()->get('name')]);
    }

    // 单个字段;getPayload():主体的参数,无论它是
    // 表单还是 JSON 文档
    #[Route('/action03', name: 'action03')]
    public function action03(Request $request): Response
    {
        $name = $request->getPayload()->get('name');
        return new Response("name = [$name]");
    }

    // 主体(表单或 JSON)绑定到一个 PersonModel 对象并经过验证(见
    // 示例 08):#[MapRequestPayload] 与 #[MapQueryString] 相对应
    #[Route('/action04', name: 'action04')]
    public function action04(#[MapRequestPayload] PersonModel $person): JsonResponse
    {
        return $this->json(['person' => $person, 'valid' => true]);
    }
}
  • 第 17 行:控制器中的所有路由都只接受 POST 方法;
  • 第 26 行:请求头 [Content-Type];
  • 第 27 行:请求的 [request] 属性(这个名称“history”有误导性)包含正文参数(对于表单正文),存放在一个类似 [query] (示例 07)的参数包中:[get]、[getInt]、[all]……表单中的字段遵循示例 10 中的规则:重复的字段,其名称必须以 [[]] 结尾;
  • 第 36–38 行:[getContentTypeFormat()] 指明正文的格式,它由头部 [Content-Type] 推导而来:[json]、[form]、[xml]……没有声明为 JSON 的正文会被以 415 错误拒绝(Unsupported Media Type);
  • 第 39–43 行:[toArray()] 对 JSON 正文进行反序列化:JSON 文本变成一个 [PHP] 数组。格式错误的 JSON 会引发 [JsonException] 异常(来自 HttpFoundation 组件,在第 7 行导入),由 [try] / [catch] 捕获,以返回包含我们的消息的 400 错误。没有这个代码块,[Symfony] 自己也会返回 400 错误:这个异常是它认定为客户端错误的异常之一;
  • 第 44–45 行:[getPayload()] 方法在一个参数包中返回正文参数——无论它是表单还是 JSON 文档。这是最常用的方法,因为它不依赖于请求的形式;
  • 第 53 行:一个表单字段,由 [getPayload()] 读取;
  • 第 59–63 行:[#[MapRequestPayload]] 属性是针对请求正文的、与 [#[MapQueryString]] (示例 08)对应的属性:它根据表单中的字段或 JSON 文档构造一个 [PersonModel] 对象(示例 08 中的类),并对其进行验证。无效的模型会抛出异常(在这里状态码为 422,Unprocessable Content),示例 08 中的 [ValidationErrors] 监听器会把它转换为 400 响应。该示例还使用了示例 09 中的配置和字典:消息将是英文的,并带有我们自己的翻译。

[Symfony] 不需要其他任何东西就能接受 POST 请求:它没有适用于所有请求的防 CSRF 保护(示例 02)。使用 [curl] 时,选项 [-d] (data)发送正文;此时请求会变成 POST 请求,类型为 [application/x-www-form-urlencoded],除非选项 [-H] (header)指定了另一种类型。选项 [-X POST] 显式设置方法(这里它是可选的)。表单的字段,包括一个重复的字段:

curl -i -g -X POST -d "name=martin&age=42&hobby[]=tennis&hobby[]=piano" http://localhost:8000/post/action01
HTTP/1.1 200 OK
Content-Type: application/json

{
    "receivedType": "application/x-www-form-urlencoded",
    "fields": {
        "name": "martin",
        "age": "42",
        "hobby": [
            "tennis",
            "piano"
        ]
    }
}

一个 JSON 正文,其中包含一个整数和一个数组:

curl -i -H "Content-Type: application/json" -d "{\"name\": \"martin\", \"age\": 42, \"children\": [\"léa\", \"tom\"]}" http://localhost:8000/post/action02
HTTP/1.1 200 OK
Content-Type: application/json

{
    "receivedType": "application/json",
    "body": {
        "name": "martin",
        "age": 42,
        "children": [
            "léa",
            "tom"
        ]
    },
    "name": "martin"
}

JSON 中的引号前面加上 [\] ,以防止命令字符串提前结束;在 [Linux] 和 [macOS] 下,你也可以用单引号把 JSON 括起来:[-d '{"name": "martin"}']。与表单字段不同,JSON 携带数据类型:年龄已经是整数。一个不是 JSON 的正文,接着是一个格式错误的 JSON(请求 JSON 响应以查看消息):

curl -i -H "Accept: application/json" -d "name=martin" http://localhost:8000/post/action02
curl -i -H "Accept: application/json" -H "Content-Type: application/json" -d "{\"name\": " http://localhost:8000/post/action02
1
2
3
4
5
6
7
8
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json

{"type":"https:\/\/tools.ietf.org\/html\/rfc2616#section-10","title":"An error occurred","status":415,"detail":"the body of the request must be JSON",...}
HTTP/1.1 400 Bad Request
Content-Type: application/json

{"type":"https:\/\/tools.ietf.org\/html\/rfc2616#section-10","title":"An error occurred","status":400,"detail":"Malformed JSON: Could not decode request body.",...}

一个单独的字段,然后用 GET 请求同一个 URL:

curl -d "name=jean%20dupont" http://localhost:8000/post/action03
curl -i "http://localhost:8000/post/action03?name=martin"
1
2
3
4
5
name = [jean dupont]
HTTP/1.1 405 Method Not Allowed
Content-Type: text/html; charset=UTF-8
Allow: POST
...

URL 存在,但不适用于 GET 方法:[Symfony] 返回 405(Method Not Allowed)响应,其头部 [Allow] 列出了接受的方法(示例 02)。最后是与请求正文绑定的模型——先是一个有效的表单,然后是一个无效的表单,最后是一个 JSON 文档:

1
2
3
curl -d "name=martin&age=42&title=Mr" http://localhost:8000/post/action04
curl -i -d "name=m&age=200" http://localhost:8000/post/action04
curl -H "Content-Type: application/json" -d "{\"name\": \"martin\", \"age\": \"42\", \"title\": \"Mr\"}" http://localhost:8000/post/action04
{
    "person": {
        "name": "martin",
        "age": 42,
        "title": "Mr",
        "email": null
    },
    "valid": true
}
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "status": 400,
    "errors": [
        {
            "field": "name",
            "message": "This value is too short. It should have 2 characters or more."
        },
        {
            "field": "age",
            "message": "This value should be between 0 and 150."
        },
        {
            "field": "title",
            "message": "the field is required"
        }
    ]
}
{
    "status": 400,
    "errors": [
        {
            "field": "age",
            "message": "This value should be of type int|null."
        }
    ]
}

最后一个请求显示了两种正文格式之间的差异。表单字段始终是字符串:因此 [Symfony] 会把字符串 ["42"] 转换为整数。而 JSON 文档则有数据类型:如果客户端在类要求整数的地方发送了字符串(["42"],用引号括起),这就是类型错误,[Symfony] 会直接报告该错误而不尝试转换([int|null] 是该属性的 [?int] 类型的另一种写法)。

3.6. 示例 12:自定义绑定与验证

标准类型、属性和约束并不总是足够。本示例展示了三种扩展绑定与验证的方式:

  • 一个“自定义”参数解析器:位于 URL 路径中的法语格式日期 [23-09-2026],以对象的形式提供给动作;
  • 一个监听器 ,它为动作提供一个并非来自 URL、而是来自 HTTP 头部的参数;
  • 一个自定义验证约束 (不含空格),以及转换 格式为 [dd/mm/yyyy] 的日期。
12-custom-binding/
├── src/
│   ├── Controller/
│   │   └── ExamplesController.php
│   ├── EventListener/
│   │   └── ErrorAsText.php
│   ├── Binding/
│   │   ├── DetectLanguage.php
│   │   ├── DayFr.php
│   │   ├── DayFrResolver.php
│   │   ├── NoSpace.php
│   │   └── NoSpaceValidator.php
│   ├── Model/
│   │   └── SearchModel.php
│   └── Kernel.php
└── ...

3.6.1. 绑定到路由参数的对象:DayFr.php 和 DayFrResolver.php

我们已经看到,动作的参数由参数解析器 提供(示例 05):一个提供路由参数(示例 02),另一个提供请求(示例 05),再一个提供服务(示例 06),还有一些提供 URL 的参数([#[MapQueryParameter]])或模型([#[MapQueryString]])。[Symfony] 大约有十五个解析器,其中包括一个用于日期([#[MapDateTime]])的解析器和一个用于枚举的解析器。应用可以编写自己的解析器。我们将为法语格式的日期编写一个,该日期由类 [DayFr] 表示:

<?php
// src/Binding/DayFr.php:URL 路径中的法式日期“23-09-2026”

namespace App\Binding;

use DateTimeImmutable;
use Stringable;

readonly class DayFr implements Stringable
{
    public function __construct(public DateTimeImmutable $date)
    {
    }

    // 路径文本 -> DayFr 对象;null:该文本不表示日期
    public static function fromUrl(string $text): ?self
    {
        // "!d-m-Y" 中的 ! 将时间重置为零(否则将是当前时间)
        $date = DateTimeImmutable::createFromFormat('!d-m-Y', $text);
        // createFromFormat 接受 "31-02-2026"(并将其变成 3 月 3 日):我们检查
        // 重新格式化后的日期是否与收到的文本一致
        if ($date === false || $date->format('d-m-Y') !== $text) {
            return null;
        }
        return new self($date);
    }

    // DayFr 对象 -> 路径文本(在构建路由的 URL 时使用)
    public function __toString(): string
    {
        return $this->date->format('d-m-Y');
    }
}
  • 第 9 行:一个不可变类,它实现了 [Stringable] 接口(来自 [PHP]):它的对象可以通过其 [__toString] 方法转换为字符串;
  • 第 11 行:日期,一个 [DateTimeImmutable] 对象(来自 [PHP] 的日期类;其 [Immutable] 版本在每次修改时都会创建一个新对象——[$date->modify('+1 day')] 返回一个新日期——而不是修改原对象);
  • 第 16–26 行:一个静态方法,它根据路径文本创建一个 [DayFr] 对象,如果文本无效则返回 [null] ([?self]:当前类的一个对象,或 [null])。[DateTimeImmutable::createFromFormat] 按特定格式解析字符串:[d] 表示日,[m] 表示月,[Y] 表示四位数的年份;开头的 [!] 把小时设为零。[createFromFormat] 很宽容:它接受 [31-02-2026] 并把它解释为 3 月 3 日。第 22 行的验证会拒绝这种情况:经 [format] 重新格式化后的日期,必须与收到的文本完全一致;
  • 第 29–32 行:反向操作:对象变成路径文本。[Symfony] 将用它来根据 [DayFr] 对象创建 URL。

解析器:

<?php
// src/Binding/DayFrResolver.php:一个参数解析器(ARGUMENT RESOLVER),为操作提供
// DayFr 类型的参数

namespace App\Binding;

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpKernel\Controller\ValueResolverInterface;
use Symfony\Component\HttpKernel\ControllerMetadata\ArgumentMetadata;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

class DayFrResolver implements ValueResolverInterface
{
    // 对于每个请求此解析器的操作参数都会调用它(见
    // 控制器):返回参数的值,放在一个数组中
    public function resolve(Request $request, ArgumentMetadata $argument): iterable
    {
        // 与操作参数($day)同名的路由参数
        $text = $request->attributes->get($argument->getName());
        if (! is_string($text)) {
            return [];    // 没有可提供的内容:由另一个解析器处理
        }
        // 不存在的日期:该 URL 不指向任何内容,404 错误
        return [DayFr::fromUrl($text) ?? throw new NotFoundHttpException("[$text] is not a date")];
    }
}
  • 第 12 行:参数解析器实现 [ValueResolverInterface] 接口,该接口只有一个方法 [resolve];
  • 第 16 行:[resolve] 接收请求和动作参数的描述(一个 [ArgumentMetadata] 对象:其名称、类型、默认值和属性)。它在一个数组([iterable])中返回参数值,如果没有可返回的内容则返回空数组;
  • 第 19 行:路由参数存放在请求的属性 ([$request->attributes])中,这是一个参数集,其中还包含由 [Symfony] 计算出的信息(例如路由名称 [_route])。我们查找与动作参数同名的那个参数;
  • 第 24 行:对象 [DayFr],或者,如果文本并不表示日期,则返回 404 错误:URL 不指向任何内容。运算符 [??] 在左操作数不是 [null] 时返回左操作数,否则返回右操作数;它的右侧可以是一个 [throw] 表达式。

该类是一个服务,与 [src] 文件夹中的所有类一样(示例 02):[Symfony] 凭借其接口([autoconfigure])把它识别为参数解析器。控制器将指定它必须提供哪个参数。

3.6.2. 由监听器提供的参数:src/Binding/DetectLanguage.php

要为动作提供根据请求计算出的信息,你也可以让监听器来计算它(示例 03),监听器随后在动作之前把它放入请求中:

<?php
// src/Binding/DetectLanguage.php:一个为操作计算一条信息的监听器

namespace App\Binding;

use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpKernel\Event\RequestEvent;
use Symfony\Component\HttpKernel\KernelEvents;

// [kernel.request] 事件:请求到达,操作尚未被调用
#[AsEventListener(event: KernelEvents::REQUEST)]
class DetectLanguage
{
    public function __invoke(RequestEvent $event): void
    {
        $request = $event->getRequest();
        // 头部 "Accept-Language: fr-FR,fr;q=0.9,en;q=0.8" -> "fr":浏览器在所提供的语言中
        // 偏好的语言(默认为第一个)
        $language = $request->getPreferredLanguage(['fr', 'en']);
        // 请求的属性(ATTRIBUTES):应用程序存储在那里的信息,
        // 供之后处理该请求的函数使用
        $request->attributes->set('language', $language);
    }
}
  • 第 11 行:[kernel.request] 事件的监听器,在请求到达时、调用动作之前触发(路由本身就是这个事件的一个监听器:生命周期一章将讨论它们的顺序);
  • 第 19 行:请求的 [Accept-Language] 头部按偏好顺序指明用户的语言:[fr-FR,fr;q=0.9,en;q=0.8] ([q] 系数以 0 到 1 的刻度衡量偏好程度)。[getPreferredLanguage] 从应用所提供的语言中选出用户偏好的语言;如果没有头部,则默认取列表中的第一种语言;
  • 第 22 行:语言存放在请求的属性 中,名称为 [language],与路由参数放在一起。

监听器会对所有请求运行。[Symfony] 没有其他框架中那种路由中间件的等价物:只应对某些路由起作用的监听器要自己检查路由名称([$request->attributes->get('_route')])。至于动作,它无需做任何特殊处理就会收到这条信息(见控制器)。

3.6.3. “自定义”约束与转换:NoSpace.php 和 SearchModel.php

“自定义”约束由两个类编写而成:约束本身,它描述约束(其选项、其消息);以及它的验证器,由它来执行检查。

<?php
// src/Binding/NoSpace.php:一个“自制的”验证约束

namespace App\Binding;

use Attribute;
use Symfony\Component\Validator\Constraint;

// #[Attribute]:该类可以用作属性(#[NoSpace]);
// 检查本身交给 NoSpaceValidator 类完成
#[Attribute(Attribute::TARGET_PROPERTY)]
class NoSpace extends Constraint
{
    public string $message = 'the field must not contain a space';
}
  • 第 11 行:[#[Attribute]] 属性(来自 [PHP] )允许该类用作属性,这里用在属性成员上([TARGET_PROPERTY]);
  • 第 12 行:约束继承自类 [Constraint];
  • 第 14 行:它的错误消息,位于一个公共属性中:它可以在运行时更改([#[NoSpace(message: '...')]])。
<?php
// src/Binding/NoSpaceValidator.php:NoSpace 约束的检查

namespace App\Binding;

use Symfony\Component\Validator\Constraint;
use Symfony\Component\Validator\ConstraintValidator;

class NoSpaceValidator extends ConstraintValidator
{
    public function validate(mixed $value, Constraint $constraint): void
    {
        if ($value !== null && str_contains((string) $value, ' ')) {
            // 该值不合适:我们报告一个“violation”,附带
            // 约束的消息
            $this->context->buildViolation($constraint->message)->addViolation();
        }
    }
}
  • 第 9 行:约束的验证器以其类名命名,后面加上 [Validator]:[Symfony] 就是这样找到它的。它继承自 [ConstraintValidator];
  • 第 11–18 行:它的 [validate] 方法接收要验证的值和约束。[str_contains] 检查字符串中是否存在某段文本;[(string)] 把值转换为字符串。如果值无效,就会报告一个违规给验证上下文 ([$this->context]),并附带约束消息。类型 [mixed] 指任意类型。与 [Symfony] 的约束一样,这个约束接受 [null]:值的缺失由 [NotBlank] 处理。

该约束由搜索模型使用:

<?php
// src/Model/SearchModel.php:搜索的模型

namespace App\Model;

use App\Binding\NoSpace;
use DateTimeImmutable;
use Symfony\Component\Validator\Constraints as Assert;

readonly class SearchModel
{
    public function __construct(
        // 一个“自制的”约束
        #[NoSpace]
        public ?string $keyword = null,
        // DateTime:格式为 dd/mm/yyyy 且存在的日期;{{ value }}:收到的值
        #[Assert\DateTime(format: 'd/m/Y', message: '{{ value }} is not a valid dd/mm/yyyy date')]
        public ?string $since = null,
    ) {
    }

    // 日期,转换为日期对象(缺失时为 null)
    public function since(): ?DateTimeImmutable
    {
        return $this->since === null ? null
            : DateTimeImmutable::createFromFormat('!d/m/Y', $this->since);
    }
}
  • 第 14–15 行:我们的约束,其用法与任何其他约束完全相同;
  • 第 17–18 行:约束 [DateTime] 验证该值是否为指定格式的日期([d/m/Y]:日/月/年),并且该日期确实存在。它的消息被我们的消息替换;[{{ value }}] 标记将被替换为接收到的值(带引号)。日期在模型中仍然是字符串:如果属性类型为 [DateTimeImmutable] ,则会由 Serializer 转换,但无效日期会因此引发转换错误(示例 08),且错误消息相当含糊;
  • 第 23–27 行:日期 转换,位于模型的一个方法中:返回对应的 [DateTimeImmutable] 对象,如果日期缺失则返回 [null] 。动作只在验证之后才调用此方法:因此日期必然有效。

最后是验证失败时的响应。我们希望它与示例 08 中的不同:以纯文本返回第一条错误消息,状态码为 400:

<?php
// src/EventListener/ErrorAsText.php:无效的模型会产生 400 响应,
// 其中以纯文本形式包含第一个错误的消息

namespace App\EventListener;

use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Event\ExceptionEvent;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\Validator\Exception\ValidationFailedException;

#[AsEventListener(event: KernelEvents::EXCEPTION)]
class ErrorAsText
{
    public function __invoke(ExceptionEvent $event): void
    {
        $validation = $event->getThrowable()->getPrevious();
        if ($validation instanceof ValidationFailedException) {
            $event->setResponse(new Response($validation->getViolations()[0]->getMessage(),
                Response::HTTP_BAD_REQUEST, ['Content-Type' => 'text/plain; charset=utf-8']));
        }
    }
}

这是示例 08 中的监听器,精简到只剩要点:[getViolations()[0]] 是第一个违规项。这样的监听器作用于整个应用程序。若要根据动作提供不同的响应,它需要检查路由名称(见上文)。

3.6.4. 控制器:src/Controller/ExamplesController.php

<?php
// src/Controller/ExamplesController.php:自定义绑定和验证

namespace App\Controller;

use App\Binding\DayFr;
use App\Binding\DayFrResolver;
use App\Model\SearchModel;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\MapQueryString;
use Symfony\Component\HttpKernel\Attribute\ValueResolver;
use Symfony\Component\Routing\Attribute\Route;

#[Route('/examples', name: 'examples_', methods: ['GET'])]
class ExamplesController extends AbstractController
{
    // /examples/schedule/23-09-2026:#[ValueResolver] 将 $day 参数交给
    // DayFrResolver 解析器,由它将其绑定到 {day} 路由参数
    #[Route('/schedule/{day}', name: 'schedule', requirements: ['day' => '[0-9]{2}-[0-9]{2}-[0-9]{4}'])]
    public function schedule(#[ValueResolver(DayFrResolver::class)] DayFr $day): Response
    {
        // generateUrl 构建路由的 URL;DayFr 对象通过其 __toString 方法
        // 变成路径文本:"23-09-2026"
        return new Response("schedule for the day [{$day->date->format('Y-m-d')}], of type "
            .get_debug_type($day->date).', URL: '.$this->generateUrl('examples_schedule', ['day' => $day]));
    }

    // /examples/hello:一个并非来自 URL、而是来自头部的参数,
    // 由 DetectLanguage 监听器计算并存储在请求的属性中
    #[Route('/hello', name: 'hello')]
    public function hello(string $language): Response
    {
        return new Response($language === 'en' ? 'Hello!' : 'Bonjour !');
    }

    // /examples/search?keyword=symfony&since=01/09/2026
    #[Route('/search', name: 'search')]
    public function search(#[MapQueryString] SearchModel $search): Response
    {
        $since = $search->since()?->format('Y-m-d');
        return new Response("search for [$search->keyword] since [$since]");
    }
}
  • 第 20 行:日历路由,其参数 [{day}] 受正则表达式约束:[[0-9]] 表示一个数字,[{2}] 表示重复前面的模式:两位数字、连字符、两位数字、连字符、四位数字。格式不同的路径段不会匹配该路由(404),我们的解析器根本不会被调用;
  • 第 21 行:属性 [#[ValueResolver]] 将参数 [$day] 分配给一个解析器(通过其类标识):只有它才会提供该参数。如果没有这个属性,[Symfony] 会按优先级顺序尝试各个解析器,而路由参数解析器——其优先级高于我们的——会把字符串 ["23-09-2026"] 提供给类型为 [DayFr]的参数:这会导致错误;
  • 第 25–26 行:日期以国际格式显示([Y-m-d]:[2026-09-23])。[generateUrl] 方法(来自 [AbstractController] )为命名路由及其参数创建 URL(这就是 [redirectToRoute] 在示例 04 中所做的)。传给它的是 [DayFr] 对象本身:[Symfony] 通过其 [__toString] 方法将其转换为字符串。URL 相对于站点([/examples/...]);若传入第三个参数,则需要绝对 URL;
  • 第 31–35 行:参数 [$language] 与任何路由参数都不对应。不过,路由参数解析器通常会查找与参数同名的请求属性:因此它找到了监听器 [DetectLanguage] 存放在那里的值。仅此而已:参数上不需要任何属性;
  • 第 38–43 行:搜索模型,与 URL 参数绑定并经过验证(示例 08)。动作只接受有效的模型;它调用日期转换方法。[?->] 运算符(nullsafe)在对象不是 [null] 时调用方法,否则返回 [null] 。

3.6.5. 执行

与路由参数关联的对象:

curl "http://localhost:8000/examples/schedule/23-09-2026"
curl -i "http://localhost:8000/examples/schedule/31-02-2026"
1
2
3
4
5
schedule for the day [2026-09-23], of type DateTimeImmutable, URL: /examples/schedule/23-09-2026
HTTP/1.1 404 Not Found
Content-Type: text/html; charset=UTF-8
X-Debug-Exception: %5B31-02-2026%5D%20is%20not%20a%20date
...

日期以国际格式显示,但 [generateUrl] 生成的 URL 又恢复为法语格式。2 月 31 日不存在:返回 404,并带有我们解析器给出的消息。国际格式的日期 [2026-09-23]与正则表达式描述的模式不匹配:同样是 404,但这次是因为没有任何路由匹配。

监听器。[-H] 选项(属于 [curl] )用于设置请求头 [Accept-Language]:

1
2
3
curl -H "Accept-Language: en-US,en;q=0.9,fr;q=0.8" http://localhost:8000/examples/hello
curl -H "Accept-Language: fr-FR,fr;q=0.9" http://localhost:8000/examples/hello
curl http://localhost:8000/examples/hello
1
2
3
Hello!
Bonjour !
Bonjour !

没有请求头 [Accept-Language] 时([curl] 不会发送该请求头),使用列表中的第一种语言。关于国际化的章节将重新讨论这个问题,由用户选择语言。

“自定义”约束与日期转换:

1
2
3
4
5
curl "http://localhost:8000/examples/search?keyword=symfony&since=01/09/2026"
curl "http://localhost:8000/examples/search"
curl -i "http://localhost:8000/examples/search?keyword=symfony%20mvc"
curl "http://localhost:8000/examples/search?since=2026-09-01"
curl "http://localhost:8000/examples/search?since=31/02/2026"
1
2
3
4
5
6
7
8
search for [symfony] since [2026-09-01]
search for [] since []
HTTP/1.1 400 Bad Request
Content-Type: text/plain; charset=utf-8

the field must not contain a space
"2026-09-01" is not a valid dd/mm/yyyy date
"31/02/2026" is not a valid dd/mm/yyyy date

没有任何参数时,[#[MapQueryString]] 会构造一个空模型,它是有效的:其两个属性都是可选的。

3.6.6. 结论

让我们总结动作获取其模型的各种方式:

路由参数
动作的参数,名称相同;按其类型转换([int $id]),由 [requirements]约束;通过参数解析器与对象关联([ValueResolverInterface]、[#[ValueResolver]])
URL 参数
[$request->query->get(...)]、[getInt]、[all]……;[#[MapQueryParameter]];重复的参数写作 [name[]]
POST 表单中的字段
[$request->request->get(...)],或 [$request->getPayload()->get(...)],后者也可以读取 JSON
JSON 请求体
[$request->toArray()]、[$request->getPayload()]
由类描述的模型
[#[MapQueryString]] (URL)、[#[MapRequestPayload]] (请求体):先转换,再验证
请求头
[$request->headers->get(...)],以及解析请求头的方法,例如 [getPreferredLanguage]
验证
约束([#[Assert\...]]),在动作之前检查([#[MapQueryString]]……)或在动作中检查([ValidatorInterface]);“自定义”约束([Constraint] 和 [ConstraintValidator])
消息
[default_locale] 语言、翻译器,以及 [translations/validators.xx.yaml] 字典
常见错误
[kernel.exception] 的事件监听器
计算得出的参数
[kernel.request] 事件监听器,它把信息存放在请求属性中

另一方面,HTML 表单需要的不仅仅是验证:它们必须被显示出来,带着用户的输入和错误重新显示,并且要防范伪造请求。[Symfony] 把这一切都委托给它的 Form 组件。这是下一章的主题,届时视图已经介绍过了。