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
|
| 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] 进行转换——成功、失败,然后是没有参数的情况:
| curl "http://localhost:8000/parameters/action02?age=42"
curl -i "http://localhost:8000/parameters/action02?age=abc"
curl http://localhost:8000/parameters/action02
|
| 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"
|
| 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] 错误页面,并带有消息:

默认值和重命名的参数:
| curl http://localhost:8000/parameters/action04
curl "http://localhost:8000/parameters/action04?page=3"
curl "http://localhost:8000/parameters/action05?q=symfony"
|
| page = [1]
page = [3]
search = [symfony]
|
同时给出所有参数。参数 [name] 出现了两次:
| curl "http://localhost:8000/parameters/action06?name=martin&age=42&name=durand"
|
| {
"name": "durand",
"age": "42"
}
|
参数 [name] 只保留它的最后一个值:这是 [PHP] 的规则,我们会在示例 10 中再次看到。年龄仍然是字符串(["42"],在 JSON 中用引号括起):因为没有请求转换。在浏览器中(这里是 [Chromium]),JSON 按服务器格式化的样子原样显示;如果它尚未缩进,“Pretty-print”复选框可以为它添加缩进。地址栏还显示了 URL 中带重音字符的编码([é] 变成 [%C3%A9],其两个字节采用 [UTF-8]):

最后是通过 [#[MapQueryParameter]] 进行的绑定,分别带有和不带可选参数,然后是无效年龄的情况:
| 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"
|
| 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"
|
| {
"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
└── ...
|
| <?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] 中启用翻译器:
| # 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] 文件中(字典的名称由域、语言和格式组成):
| # 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 中;其中的字符
// < > & " ' 会被替换为 < >...(否则,输入可能会注入 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 中具有特殊含义的字符([<]、[>]、[&]、["]、['])替换为它们的实体 ([<]、[>]……):这些字符将按原样显示,而不会被解释。如果没有这一预防措施,用户可以输入包含 HTML 甚至 [JavaScript] 的“姓名”,它会在任何查看该页面的人的浏览器中执行。这是 Web 上最常见的安全漏洞:脚本注入 (XSS,跨站脚本)。称谓和年龄字段不需要这种保护:它们的值已经由约束验证过(三个允许值之一,全是数字)。在下一章中,[Twig] 视图引擎会对插入页面的任何值自动执行这种转义。
一个有效的输入,接着是一个包含四个错误的输入:


这些消息是英文的:有来自 [Symfony] 的(姓名、地址)、我们自己的(年龄),以及来自我们字典的(称谓)。对第二个请求——姓名中包含 HTML 的那个——的原始响应,以及对没有姓名且年龄过大的请求的响应:
| 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"
|
| <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 <b>martin</b> (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)。结果如下:
| 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"
|
| 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.
...
|
验证先是成功,然后因未知颜色而失败,再因空列表而失败:
| 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
|
| 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"
|
| 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 文档:
| 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"
|
| 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]:
| 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
|
| Hello!
Bonjour !
Bonjour !
|
没有请求头 [Accept-Language] 时([curl] 不会发送该请求头),使用列表中的第一种语言。关于国际化的章节将重新讨论这个问题,由用户选择语言。
“自定义”约束与日期转换:
| 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"
|
| 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 组件。这是下一章的主题,届时视图已经介绍过了。