2. 动作、路由、响应
本章考察请求所经过的路径,从浏览器到处理它的动作,再到该动作返回的响应。视图要到第 4 章才会讲到:这里的动作直接返回文本或 JSON。
2.1. 示例 01:Symfony 应用的结构
第一个示例是可能存在的最小的 [Symfony] 应用。由 [composer create-project symfony/skeleton] 创建的项目包含大约二十个文件和文件夹,而由 [symfony new --webapp] 创建的项目则包含多得多的内容(见简介);在这里,我们只保留应用绝对不可缺少的那些:
| 01-structure/
├── bin/
│ └── console
├── config/
│ ├── packages/
│ │ └── framework.yaml
│ └── bundles.php
├── public/
│ └── index.php
├── src/
│ └── Kernel.php
├── var/
├── .env
└── composer.json
|
- [public/index.php]:应用的入口点。所有 HTTP 请求,无论其 URL 是什么,都由这个文件处理。[public] 文件夹是 Web 服务器提供服务的唯一文件夹:其中还包含静态文件(样式表、图片、脚本),而且仅包含这些文件;
- [src/Kernel.php]:应用的内核 ,负责组装应用并处理请求。[src] 文件夹包含应用的所有类;
- [config]:应用的配置:其 Bundle 列表([bundles.php])以及每个 Bundle 的配置([packages] 文件夹);
- [var]:应用在运行期间写入的文件:缓存 ([var/cache] 文件夹),[Symfony] 在其中存放编译后的配置,以后还有会话。该文件夹由 [Symfony] 在第一个请求时创建;
- [.env]:应用的设置,采用 [NAME=value] 键值对的形式;
- [bin/console]:[Symfony] 的命令行工具;
- [composer.json]:[Composer] 的项目描述文件。
2.1.1. 入口点:public/index.php
| <?php
// public/index.php:所有 HTTP 请求的入口点
use App\Kernel;
use Symfony\Component\Dotenv\Dotenv;
use Symfony\Component\ErrorHandler\Debug;
use Symfony\Component\HttpFoundation\Request;
// Composer 的类加载器(examples/vendor 文件夹,共享)
// 本示例的类(App\ 命名空间)位于其 src/ 文件夹中
$loader = require dirname(__DIR__, 2).'/vendor/autoload.php';
$loader->addPsr4('App\\', dirname(__DIR__).'/src/');
// 配置:.env 文件中的变量
(new Dotenv())->bootEnv(dirname(__DIR__).'/.env');
// 在调试模式下,任何 PHP 错误都会变成异常,并显示详细信息
if ($_SERVER['APP_DEBUG']) {
Debug::enable();
}
// 应用程序的内核处理当前请求,并返回响应
$kernel = new Kernel($_SERVER['APP_ENV'], (bool) $_SERVER['APP_DEBUG']);
$request = Request::createFromGlobals();
$response = $kernel->handle($request);
$response->send();
$kernel->terminate($request, $response);
|
- 第 1 行:[PHP] 文件以 [<?php] 标签开头。其后的一切都是 [PHP] 代码;只包含代码的文件不会关闭这个标签;
- 第 2 行:注释,从 [//] 到行尾([/* ... */] 界定多行注释);
- 第 4–7 行:语句 [use] 导入一个类名。[PHP] 中类的完整名称包含其命名空间 (namespace),它相当于 [Java] 中的包:[Symfony\Component\HttpFoundation\Request] 是命名空间 [Request] 中的类 [Symfony\Component\HttpFoundation]。在 [use] 之后,文件中可以直接写 [Request]。[Symfony] 中类的名称说明了它们的来源:[Component\HttpFoundation],表示请求的组件;HTTP,表示响应的组件;[Component\Dotenv],读取文件 [.env] 的组件;[Component\ErrorHandler],处理错误的组件。[App\Kernel] 是应用自身的一个类;
- 第 11 行:[require] 执行另一个文件,[PHP]。[__DIR__] 是当前文件所在的目录(这里是 [public]);[dirname(__DIR__, 2)] 向上两级到达 [examples] 文件夹;[.] 运算符 连接 两个字符串。文件 [vendor/autoload.php] 由 [Composer] 写入,它安装类加载器:第一次使用某个类时,它会找到并加载定义该类的文件。多亏了这一点,你无需再为类编写 [require] 。[vendor] 文件夹属于 [examples] 文件夹,由所有示例共享(见简介)。[require] 会返回被执行文件的值:[vendor/autoload.php] 返回加载器,存放在变量 [$loader] 中。在 [PHP] 中,变量名总是以 [$] 开头;
- 第 12 行:[Composer] 的类加载器知道位于 [vendor] 文件夹中各个库的类。它还必须知道应用中的类,按惯例这些类存放在应用的 [src] 文件夹中,位于 [App] 命名空间下。在标准项目中,[Composer] 从项目的 [composer.json] 文件获取这一信息。我们的示例共享同一个名为 [vendor] 的文件夹,但每个示例都有自己的 [src] 文件夹:因此每个示例都通过加载器的 [addPsr4] 方法自行向它声明([PSR-4] 标准把命名空间映射到文件夹:[App\Controller\FirstController] 类位于 [src/Controller/FirstController.php] 文件中)。运算符 [->] 表示访问对象的成员。在用单引号括起的字符串中,[\\] 表示单个字符 [\];
- 第 15 行:[new Dotenv()] 创建一个 [Dotenv] 类的对象,其方法 [bootEnv] 读取文件 [.env](下文介绍),并把其中的变量存入 [$_SERVER] 和 [$_ENV] 这两个 [PHP] 数组中,应用将在那里找到它们;
- 第 18–20 行:调试模式 (文件 [.env] 根据环境推断出它;见下文)。[Debug::enable()] 会把任何 [PHP] 错误——即使只是一个简单的警告——转换为异常,并显示在详细的错误页面上(示例 03)。[::] 表示访问类的成员:[enable] 是一个静态方法,可以不通过对象而直接在类上调用;
- 第 23 行:创建应用的内核,即 [App\Kernel] 类的一个对象,带有两个参数:环境([dev])和调试模式([true])。[(bool)] 把值转换为布尔值;
- 第 24 行:[Request::createFromGlobals()] 创建一个 [Request] 对象,内容取自 [PHP] 收到的 HTTP 请求([PHP] 把它存放在它的“超全局”数组 [$_GET]、[$_POST]、[$_COOKIE]、[$_SERVER] 等中);
- 第 25 行:内核处理请求([handle])并返回一个 [Response] 对象。一切都发生在这里:内核启动(组装其 Bundle 并构建其服务),找到负责该请求的动作,执行它,并取回它产生的响应;
- 第 26 行:响应被发送给浏览器:先是状态码、头部,然后是正文;
- 第 27 行:内核结束请求:它执行那些可以等到响应发送之后再处理的任务(见生命周期一章)。
这四行概括了 [Symfony]:请求进,响应出。整个应用就是一个把 [Request] 对象转换为 [Response] 对象的函数。这个文件对所有示例都是相同的。它还突出了 [PHP] 的一个独特之处:应用在每个请求时都会重新构建。Web 服务器对它收到的每个请求都会从头到尾执行 [public/index.php] :加载类、构建内核、处理请求、发送响应,然后忘掉一切。没有任何对象会从一个请求存活到下一个请求。在数据作用域一章中,我们会看到这种行为的后果,它与 [Java]、[C#] 或 [Python] 恰恰相反,后者的应用在请求之间一直驻留在内存中。
如果每次都必须重新读取并解释全部配置,那么为每个请求都构建内核的代价会很高。[Symfony] 只做一次这件事:它把配置编译成 [PHP] 代码,存放在 [var/cache/dev] 文件夹中(针对 [dev] 环境),然后重复使用。在调试模式下,它会在每个请求时检查配置文件是否已更改,必要时重新编译。
典型的 [Symfony] 项目有一个更短的 [public/index.php] 文件,它把这项任务委托给 [Runtime] 组件(来自 [Symfony] ,案例研究就使用它):我们选择完整地写出来,以便看清发生了什么。
2.1.2. 内核:src/Kernel.php
| <?php
// src/Kernel.php:应用程序的内核,最小的 Symfony 应用程序
namespace App;
use Symfony\Bundle\FrameworkBundle\Kernel\MicroKernelTrait;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Kernel as BaseKernel;
use Symfony\Component\Routing\Attribute\Route;
class Kernel extends BaseKernel
{
// 内核的标准行为:config/bundles.php 中的 Bundle、
// config/packages 的配置、路由
use MicroKernelTrait;
// 一个操作(ACTION):处理 GET / 请求时调用的方法。#[Route] 属性
// 将它与 / 路径关联起来
#[Route('/')]
public function home(): Response
{
// 发送给浏览器的响应
return new Response('Hello from Symfony!');
}
}
|
- 第 4 行:类的命名空间。因此它的完整名称是 [App\Kernel];
- 第 11 行:应用的 [Kernel] 类继承([extends])自 [Kernel] 类,该类来自 [Symfony],并以名称 [BaseKernel] 导入(第 8 行的关键字 [as] 用于重命名导入,因为这两个类同名)。这个类负责处理请求([handle]);
- 第 15 行:语句 [use] 在类内部并不导入名称;而是引入trait,即一个可复用的类片段。[MicroKernelTrait] 为内核提供其标准行为:它读取 [config/bundles.php] 中的 Bundle 列表、[config/packages] 文件夹中的 Bundle 配置、[config/services.yaml] 中的服务(示例 06),以及 [config/routes.yaml] 中的路由(示例 02)。它还会在 [Kernel] 类自身中查找路由:这使得第一个示例可以只由它构成;
- 第 19–24 行:一个动作,即处理请求的 public 方法。属性 [#[Route('/')]] 把它与路径 [/] 关联起来:这就是路由。[PHP] 属性写作 [#[...]],是附加在代码(类、方法、参数)上的信息,[PHP] 会忽略它,但库会读取它:相当于 [Java] 的注解或 [Python] 的装饰器。[Symfony] 大量使用它们;
- 第 20 行:[: Response] 声明返回值的类型。在 [PHP] 中类型是可选的,但一旦指定了类型,[PHP] 就会在运行时检查它们;
- 第 23 行:动作返回一个 [Response] 对象,其第一个参数是响应的正文。这遵循 [Symfony] 的规则:动作总是返回一个 [Response] 对象(示例 03)。
2.1.3. 配置:config/bundles.php、config/packages/framework.yaml 和 .env
[Symfony] 由Bundle组成:即把功能集成到应用中的包([Twig] 视图、安全、数据库访问等)。应用的 Bundle 列表位于文件 [config/bundles.php] 中:
| <?php
// config/bundles.php:构成应用程序的 Bundle(构建块),
// 以及每个 Bundle 处于活动状态的环境
return [
Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
];
|
该文件返回一个关联数组:对每个以类名标识的 Bundle([FrameworkBundle::class] 是字符串形式的完整类名),它列出了该 Bundle 在哪些环境中处于激活状态(这里是所有环境)。我们的应用只有一个 Bundle,即 FrameworkBundle,它是框架的核心,负责组装基本组件:请求和响应、内核、路由、服务容器、控制台等。后续示例会添加更多 Bundle。每个 Bundle 都有自己的配置,位于 [config/packages] 文件夹中,每个 Bundle 一个文件,用 [YAML] 编写:
| # config/packages/framework.yaml:FrameworkBundle 的配置,它是 Symfony 的核心
framework:
# 应用程序的密钥,从 .env 文件中读取
secret: '%env(APP_SECRET)%'
|
[YAML] 是一种用缩进来描述数据的文本格式:[framework] (FrameworkBundle 的键)包含键 [secret]。以 [#] 开头的行是注释。值 [%env(APP_SECRET)%] 是对变量 [APP_SECRET] 的引用,它从进程的环境 中读取,如果没有,则从文件 [.env] 中读取:
| # .env:应用程序的配置,每次安装各不相同
# dev:开发环境;prod:生产环境
APP_ENV=dev
# 应用程序的密钥(32 个随机十六进制字符)
APP_SECRET=6f1c0b2e9a8d4f37b5e2c1d0a9f8e7d6
|
- 第 3 行:应用的环境:[dev] 用于开发,[prod] 用于生产([test] 用于自动化测试)。环境决定配置:[config/packages/prod/xxx.yaml] 文件只会在生产环境中读取。它还决定调试模式,除生产环境外默认启用(变量 [APP_DEBUG] 可让你另行设置):此时未处理的异常会显示一个详细页面(示例 03),并且 [Symfony] 在配置一发生变化时就重新编译它。该模式仅用于开发,也只应在开发中使用:错误页面会泄露应用的源代码和配置;
- 第 5 行:应用的密钥:一个随机字符串,[Symfony] 用它对某些数据(登录链接、防 CSRF 令牌等)进行签名。每个示例都有自己的密钥。
与其他框架不同,[Symfony] 项目的 [.env] 文件通常会与源代码一起发布:它包含变量的默认值,适合开发使用。特定于某次安装的值(例如密码或生产环境密钥)存放在 [.env.local] 文件中,该文件在主文件之后读取,但绝不会发布;在生产环境中,这些值改由真正的环境变量提供,环境变量的优先级高于这两个文件。配置中未指定的内容保持各个 Bundle 所定义的默认值。[php bin/console config:dump-reference framework] 命令会显示 FrameworkBundle 中所有可能的键及其默认值(几百行)。
2.1.4. bin/console 工具和 composer.json 文件
[bin/console] 文件是一个 [PHP] 脚本,它像 [public/index.php] 一样构建内核,但目的是执行一条命令 而不是处理请求:
| #!/usr/bin/env php
<?php
// bin/console:Symfony 的命令行工具(php bin/console debug:router...)
use App\Kernel;
use Symfony\Bundle\FrameworkBundle\Console\Application;
use Symfony\Component\Console\Input\ArgvInput;
use Symfony\Component\Dotenv\Dotenv;
// 类加载器和配置,与 public/index.php 中相同
$loader = require dirname(__DIR__, 2).'/vendor/autoload.php';
$loader->addPsr4('App\\', dirname(__DIR__).'/src/');
(new Dotenv())->bootEnv(dirname(__DIR__).'/.env');
// 同一个内核,但用于运行命令而不是处理请求
$kernel = new Kernel($_SERVER['APP_ENV'], (bool) $_SERVER['APP_DEBUG']);
(new Application($kernel))->run(new ArgvInput());
|
- 第 1 行:在 [Linux] 和 [macOS] 下,这一行使文件可以被直接执行([./bin/console]);在 [Windows] 下,则始终输入 [php bin/console];
- 第 17 行:FrameworkBundle 的 [Application] 类是构建在内核之上的命令行应用;它了解内核的服务和配置。[ArgvInput] 表示命令行参数;[run] 执行所请求的命令。
[php bin/console list] 显示可用命令的列表:本示例中大约有四十条,随着 Bundle 的加入还会增加。我们会用到其中的若干条,包括 [debug:router]、[debug:container] 和 [cache:clear]。最后,文件 [composer.json] 对示例进行了描述:
| {
"name": "examples/01-structure",
"description": "Example 01: the structure of a Symfony application",
"type": "project",
"autoload": {
"psr-4": {
"App\\": "src/"
}
}
}
|
这是一个 JSON 文档。包含它并不是为了 [Composer] (示例的库由文件 [examples/composer.json] 描述,见简介),而是为了内核:[Symfony] 从文件 [src/Kernel.php] 出发向上回溯,直到第一个包含名为 [composer.json] 的文件的文件夹,以此查找项目文件夹。它正是从这个位置找到所有其他内容([config]、[var]、[templates]……)的。标准项目的 [composer.json] 文件还包含其库的列表以及其类的 PSR-4 规则(第 5–9 行),而我们的示例是自行向加载器声明这些规则的([public/index.php] 的第 12 行)。
2.1.5. 执行
在打开到 [01-structure] 文件夹的终端窗口中,输入 [php -S localhost:8000 -t public]。[PHP] 显示:
| [Sun Sep 27 11:18:43 2026] PHP 8.4.21 Development Server (http://localhost:8000) started
|
[-S] 选项启动 开发服务器 ,它集成在 [PHP] 中。它在本机的 8000 端口上监听([localhost]):只接受来自本机的请求,适合开发使用([-S 0.0.0.0:8000] 则会向网络上的其他机器开放)。选项 [-t public] 把 [public] 目录设为站点根目录:该目录中存在的文件按原样提供;任何其他 URL 都由 [public/index.php] 处理。使用 [Ctrl-C] 停止它。该服务器仅用于开发:在生产环境中,将使用 [Apache] 或 [Nginx] 这样的 Web 服务器,并与 [PHP-FPM] 搭配(见案例研究)。修改代码或配置后无需重启它:由于 [PHP] 在每个请求时都会重新读取文件,更改会在下一个请求时生效。([Symfony] 也提供了自己的工具,即 [symfony] 程序,其 [symfony serve] 命令会启动一个功能更全面的服务器;附录中有介绍。)
让我们用浏览器请求 URL 和 [http://localhost:8000/] :

然后用 [curl]。[-i] 选项还会显示响应中的 HTTP 头部:
| curl -i http://localhost:8000/
|
| HTTP/1.1 200 OK
Host: localhost:8000
Connection: close
X-Powered-By: PHP/8.4.21
Cache-Control: no-cache, private
Date: Sun, 27 Sep 2026 09:18:45 GMT
Content-Type: text/html; charset=UTF-8
X-Robots-Tag: noindex
Hello from Symfony!
|
响应的第一行包含协议版本、状态码(200)及其描述([OK])。接下来是头部:请求的主机、[Connection: close] (开发服务器在每个响应之后都会关闭连接)、[PHP] 的版本、缓存指令(默认情况下,[Symfony] 会阻止中间节点缓存响应)、日期、内容类型,以及 [X-Robots-Tag: noindex],它指示搜索引擎不要索引该页面([Symfony] 在调试模式下会添加它:处于开发中的站点不需要被索引)。一个空行把头部与响应正文隔开。在本文档的其余部分,我们将不再列出头部 [Host]、[Connection]、[X-Powered-By]、[Cache-Control]、[Date] 和 [X-Robots-Tag],因为它们不会变化。
头部 [Content-Type: text/html; charset=UTF-8] 表明响应是 HTML,其字符以 UTF-8 编码。当动作没有指定响应类型时,这是 [Symfony] 的选择:因此浏览器把该字符串解释为 HTML(这里没有标签,所以按原样显示)。示例 03 将展示如何指定其他类型。该响应没有设置任何 Cookie:[Symfony] 只有在应用使用会话时才会创建会话(见作用域一章)。
每收到一个请求,服务器控制台都会显示几行日志输出:建立连接、来自 [Symfony] 的指明所选路由的消息,然后是响应码、方法和路径。
| [Sun Sep 27 11:18:44 2026] 127.0.0.1:49148 Accepted
[Sun Sep 27 11:18:45 2026] [info] Matched route "app_kernel_home".
[Sun Sep 27 11:18:45 2026] 127.0.0.1:49148 [200]: GET /
[Sun Sep 27 11:18:45 2026] 127.0.0.1:49148 Closing
|
消息 [[info] Matched route] 来自 日志 (logger),由 [Symfony] 输出:在没有安装日志库的情况下,[Symfony] 会把消息写到进程的错误输出,由开发服务器显示出来。该路由被分配了一个由 [Symfony] 根据类名和方法名计算出的名称 [app_kernel_home] :下一个示例将自动为其路由命名。在第一个请求之后,[var/cache/dev] 文件夹中包含了编译后的配置:应用容器 ([App_KernelDevDebugContainer.php],示例 06)和路由表([url_matching_routes.php])。
2.2. 示例 02:路由
路由把一个 URL 和一个 HTTP 方法(GET、POST……)与一个动作关联起来。把所有动作直接写在内核里很快就会变得难以阅读;因此要把它们组织到类中——即控制器。示例 02 有两个:
| 02-routing/
├── config/
│ ├── routes.yaml
│ └── services.yaml
├── src/
│ ├── Controller/
│ │ ├── HomeController.php
│ │ └── FirstController.php
│ └── Kernel.php
└── ...
|
文件 [public/index.php]、[bin/console]、[composer.json]、[.env]、[config/bundles.php] 和 [config/packages/framework.yaml] 都来自示例 01:我们不再重复列出(只有示例名称和密钥会变)。[src/Kernel.php] 内核不再有任何功能:它被精简为只剩类及其 trait。每个控制器都是 [App\Controller] 命名空间中的一个类,位于 [src/Controller] 文件夹中:这是 [Symfony] 的约定,标准的 [PSR-4] 把两者对应起来(示例 01)。
2.2.1. HomeController 控制器
| <?php
// src/Controller/HomeController.php:主页
namespace App\Controller;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
class HomeController
{
// GET /:一个包含指向其他操作的链接的 HTML 页面
#[Route('/', name: 'home', methods: ['GET'])]
public function index(): Response
{
return new Response(<<<'HTML'
<h2>Example 02 - routing</h2>
<ul>
<li><a href="/first">/first</a></li>
<li><a href="/first/action01">/first/action01</a></li>
<li><a href="/first/products/17">/first/products/17</a></li>
<li><a href="/first/products/17/reviews/3">/first/products/17/reviews/3</a></li>
<li><a href="/first/files/images/logo.png">/first/files/images/logo.png</a></li>
<li><a href="/first/products/abc">/first/products/abc</a></li>
<li><a href="/unknown">/unknown</a></li>
</ul>
HTML);
}
}
|
- 第 4 行:类的命名空间。因此它的完整名称是 [App\Controller\HomeController];
- 第 9 行:类。按惯例,类名中每个单词的首字母大写([HomeController]),而方法名或变量名以小写字母开头([action01Post])。[Symfony] 控制器 不需要继承任何类(下一个示例将介绍通常使用的父类);
- 第 12 行:动作的 [#[Route]] 属性,带有三个参数,其中两个是具名参数:值通过名称而不是位置与参数关联([name: 'home'])。路径 [/]、路由名称 ([home])(将用于生成其 URL,见示例 04),以及接受的 HTTP 方法:[methods: ['GET']]。在 [PHP] 中,[[a, b]] 是一个数组 (array)。如果没有 [methods] 参数,该路由将接受所有方法;
- 第 13 行:动作 [index],即类的一个 public 方法;
- 第 15–26 行:一个多行字符串。语法 [<<<'HTML'] ... [HTML] (nowdoc)界定按原样书写的文本,位于包含同一个单词(这里是 [HTML])的两行之间;结束行的缩进会从所有行中去掉。该动作返回 HTML,它以类型 [text/html] 发送(见示例 01)。
因此动作 [index] 返回一个 HTML 页面,其中包含指向另一个控制器各动作的链接:

2.2.2. FirstController 控制器
| <?php
// src/Controller/FirstController.php:/first/... URL 的操作
namespace App\Controller;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Routing\Requirement\Requirement;
// 类上的 #[Route] 属性:其各个操作的路由所共享的前缀,
// 既用于路径(/first),也用于名称(first_)
#[Route('/first', name: 'first_')]
class FirstController
{
// GET /first:'' 路径表示前缀本身
#[Route('', name: 'index', methods: ['GET'])]
public function index(): Response
{
return new Response('Action [index] of the [FirstController] controller');
}
// GET /first/action01
#[Route('/action01', name: 'action01', methods: ['GET'])]
public function action01(): Response
{
return new Response('Action [action01] of the [FirstController] controller, GET request');
}
// POST /first/action01:相同的路径,不同的 HTTP 方法,不同的操作
#[Route('/action01', name: 'action01_post', methods: ['POST'])]
public function action01Post(): Response
{
return new Response('Action [action01Post] of the [FirstController] controller, POST request');
}
// GET /first/products/17:{id} 是路由参数,传递给操作的 $id
// 参数;requirement 只接受数字,int 类型
// 将其转换为整数
#[Route('/products/{id}', name: 'product', requirements: ['id' => '\d+'], methods: ['GET'])]
public function product(int $id): Response
{
return new Response("Product no. $id");
}
// GET /first/products/17/reviews/3:两个路由参数;requirement
// 直接写在路径中,位于 < 和 > 之间
#[Route('/products/{id<\d+>}/reviews/{number<\d+>}', name: 'review', methods: ['GET'])]
public function review(int $id, int $number): Response
{
return new Response("Review no. $number of product no. $id");
}
// GET /first/files/images/logo.png:Requirement::CATCH_ALL(.+
// 表达式)接受任何路径结尾,包括斜杠
#[Route('/files/{path}', name: 'file', requirements: ['path' => Requirement::CATCH_ALL],
methods: ['GET'])]
public function file(string $path): Response
{
return new Response("Requested file: $path");
}
}
|
- 第 10–13 行:应用于[#[Route]] 类的 属性 为其所有动作的路由提供了前缀 :[/first] 用于路径,[first_] 用于名称。动作的 URL 是该前缀与其路由路径的拼接;
- 第 16–20 行:路径 [''] 指的是前缀本身:[GET /first];
- 第 23–34 行:同一路径,对应两种 HTTP 方法:[GET] 和 [POST],由两个不同的动作处理。动作的名称可以自由选择:把它与 URL 和 HTTP 方法关联起来的是属性 [#[Route]] 。[methods: ['GET', 'POST']] 则会把两种方法关联到同一个动作;
- 第 39–43 行:[{id}] 是一个路由参数:URL 的这一段可以取多个值。动作的 [$id] 参数会接收它的值:对于 URL [/first/products/17],它是 17。默认情况下,路由参数接受任何不含斜杠的文本;[requirements] 参数对它进行限制:正则表达式 [\d+] (一个或多个数字,其中 [\d] 表示一个数字,[+] 表示重复)只接受数字。否则,路由不匹配。动作参数的类型 [int] 指示 [Symfony] 把该值(从 URL 中提取的字符串)转换为整数。这就是数据绑定 ,下一章会详细讲解。在用双引号括起的字符串 ["Product no. $id"]中,变量 [$id] 会被替换为它的值:这就是插值 (相反,用单引号括起的字符串则按原样书写);
- 第 47–51 行:两个路由参数被传递给两个动作参数。[Symfony] 按名称映射它们;动作参数的顺序无关紧要。这一次,约束直接写在路径本身中,位于 [<] 和 [>] 之间:这样更简短;
- 第 55–60 行:一个包含 [/] 的路由参数。[Requirement] 类(来自 [Symfony] )以常量的形式汇集了最常用的正则表达式:[Requirement::CATCH_ALL] ([.+]:任意字符,包括斜杠)、[Requirement::DIGITS] ([[0-9]+])、[Requirement::UUID]、[Requirement::DATE_YMD]……
2.2.3. 配置:config/routes.yaml 和 config/services.yaml
剩下的就是告诉 [Symfony] 路由在哪里:
| # config/routes.yaml:应用程序的路由由
# 控制器的 #[Route] 属性来描述(src/ 文件夹中带有该属性的类)
controllers:
resource: routing.controllers
|
文件 [config/routes.yaml] 描述应用的路由,或者像这里一样,指明到哪里去找到它们。键 [controllers] 是一个任意名称。资源 [routing.controllers] 指的是由应用所识别的控制器中 [#[Route]] 属性所声明的路由。而让应用知道这些控制器的,是文件 [config/services.yaml] :
| # config/services.yaml:应用程序的服务(见示例 06)。src/ 文件夹中
# 的所有类都被声明给容器:它们可以接收
# 自己所需的对象(autowire),并且 Symfony 会根据它们的
# 属性对其进行配置(autoconfigure:#[Route] 使它们成为控制器)
services:
_defaults:
autowire: true
autoconfigure: true
App\:
resource: '../src/'
|
该文件声明了应用的服务:即 [Symfony] 知道如何自行创建的对象(示例 06)。第 10–11 行把 [src] 文件夹中的每个类都变成一个服务。多亏了第 8 行([autoconfigure]),[Symfony] 会检查其中每一个:带有 [#[Route]] 属性的方法的类会成为控制器,其路由会被添加到路由表中。我们几乎不会再编写这两个文件了:它们在所有示例中都是一样的。
2.2.4. 执行
下面是对几个请求的响应:
| curl -i http://localhost:8000/first
|
| HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8
Action [index] of the [FirstController] controller
|
| curl -i http://localhost:8000/first/products/17/reviews/3
|
| HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8
Review no. 3 of product no. 17
|
| curl -i http://localhost:8000/first/files/images/logo.png
|
| HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8
Requested file: images/logo.png
|
要发送 POST 请求,请使用 [-X POST] 选项,它属于 [curl]:
| curl -i -X POST http://localhost:8000/first/action01
|
| HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8
Action [action01Post] of the [FirstController] controller, POST request
|
POST 请求被原样接受:[Symfony] 没有适用于所有请求的 CSRF 保护。它通过其 Form 组件逐个保护表单 (示例 18)。如果某个 HTTP 方法没有被该路径上的任何动作处理,就会产生 405 错误([Method Not Allowed])。[Allow] 头部列出了接受的方法:
| curl -i -X PUT http://localhost:8000/first/action01
|
| HTTP/1.1 405 Method Not Allowed
Content-Type: text/html; charset=UTF-8
X-Debug-Exception: No%20route%20found%20for%20%22PUT%20http%3A%2F%2Flocalhost%3A8000%2Ffirst%2Faction01%22%3A%20Method%20Not%20Allowed%20%28Allow%3A%20GET%2C%20POST%29
X-Debug-Exception-File: %2Fcourse%2Fsymfony-sept-2026%2Fexamples%2Fvendor%2Fsymfony%2Fhttp-kernel%2FEventListener%2FRouterListener.php:160
Allow: GET, POST
<!-- No route found for "PUT http://localhost:8000/first/action01": Method Not Allowed (Allow: GET, POST) (405 Method Not Allowed) -->
<!DOCTYPE html>
<html lang="en">
...
|
在调试模式下,响应正文是 [Symfony] 的详细错误页面——我们将在示例 03 中看到——其前面有一条概述该错误的(HTML)注释。两个 [X-Debug-Exception] 头部同样提供了错误消息和位置,采用与 URL 相同的编码([%20] 表示空格……):它们供开发工具使用。[GET] 路由 也接受方法 [HEAD] (与 GET 相同的请求,只是没有响应正文),这由 [Symfony] 自行处理。
没有任何路由处理的 URL 会产生 404 错误。标识符不是数字时也是如此:约束 [\d+] 使路由无法匹配 [/first/products/abc]。
| curl -i http://localhost:8000/first/products/abc
|
| HTTP/1.1 404 Not Found
Content-Type: text/html; charset=UTF-8
X-Debug-Exception: No%20route%20found%20for%20%22GET%20http%3A%2F%2Flocalhost%3A8000%2Ffirst%2Fproducts%2Fabc%22
...
<!-- No route found for "GET http://localhost:8000/first/products/abc" (404 Not Found) -->
<!DOCTYPE html>
...
|
在浏览器中,调试模式下:

[Symfony] 的错误页面说明没有找到路由(“No route found”),并显示路由器抛出的异常 [NotFoundHttpException]。第 7 章将展示如何用应用自定义的页面来替换它。还要注意,[Symfony] 区分 [/first] 和 [/first/]:第二个 URL 没有路由,但 [Symfony] 并不返回 404 错误,而是把浏览器重定向(示例 04)到第一个:
| curl -i http://localhost:8000/first/
|
| HTTP/1.1 301 Moved Permanently
Location: http://localhost:8000/first
...
|
在示例文件夹中运行的命令 [php bin/console debug:router] 会列出应用中的所有路由:
| php bin/console debug:router
|
| --------------------- -------- ---------------------------------------
Name Method Path
--------------------- -------- ---------------------------------------
first_index GET /first
first_action01 GET /first/action01
first_action01_post POST /first/action01
first_product GET /first/products/{id}
first_review GET /first/products/{id}/reviews/{number}
first_file GET /first/files/{path}
home GET /
--------------------- -------- ---------------------------------------
|
每一行列出路由名称、HTTP 方法和路径。[FirstController] 中的路由名称确实都加上了前缀 [first_]。[php bin/console debug:router first_product] 会详细显示某个路由(它的约束、它的控制器);[php bin/console router:match /first/products/17] 则指出与某个路径对应的是哪个路由。
2.3. 示例 03:动作的响应
动作返回的内容决定了 HTTP 响应。示例 03 回顾了主要的几种情形:
| 03-responses/
├── src/
│ ├── Controller/
│ │ └── ResponsesController.php
│ ├── EventListener/
│ │ └── ReadableJson.php
│ ├── Model/
│ │ └── Person.php
│ └── Kernel.php
└── ...
|
控制器 [ResponsesController] 把每个 URL 和 [/responses/xxx] 与一个动作关联起来:
| <?php
// src/Controller/ResponsesController.php:操作的各种响应
namespace App\Controller;
use App\Model\Person;
use RuntimeException;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
// AbstractController:控制器的父类,为它们提供
// 快捷方法($this->json、$this->redirectToRoute、$this->render...)
#[Route('/responses', name: 'responses_', methods: ['GET'])]
class ResponsesController extends AbstractController
{
// 一个字符串,声明为纯文本:浏览器按原样显示
#[Route('/text', name: 'text')]
public function text(): Response
{
return new Response('<h1>Action [text]</h1>', Response::HTTP_OK,
['Content-Type' => 'text/plain; charset=utf-8']);
}
// 未声明类型时,Symfony 以 text/html 类型发送响应
#[Route('/html', name: 'html')]
public function html(): Response
{
return new Response('<h1>Action [html]</h1>');
}
// 一个对象:$this->json 将其序列化为 JSON,类型为 [application/json]。
// 该操作不能命名为 json:那样会重新定义继承的方法
#[Route('/json', name: 'json')]
public function asJson(): JsonResponse
{
return $this->json(new Person('Martin', 'Jean', 42));
}
// 一个关联数组:它会变成 JSON 对象
#[Route('/array', name: 'array')]
public function array(): JsonResponse
{
return $this->json(['lastName' => 'Martin', 'firstName' => 'Jean', 'age' => 42]);
}
// 一个索引数组:它会变成 JSON 数组
#[Route('/list', name: 'list')]
public function list(): JsonResponse
{
return $this->json(['Mme', 'Melle', 'Mr']);
}
// 一个计算得到的数组:先排序,然后逐项转换
#[Route('/calc', name: 'calc')]
public function calc(): JsonResponse
{
$numbers = [3, 1, 2];
sort($numbers);
return $this->json(array_map(fn (int $n) => $n * 10, $numbers));
}
// 使用 201 状态码(Created)而不是 200(OK)
#[Route('/created', name: 'created')]
public function created(): JsonResponse
{
return $this->json(['message' => 'resource created'], Response::HTTP_CREATED);
}
// 没有响应:204 状态码(No Content)表示“没有内容可显示”
#[Route('/empty', name: 'empty')]
public function empty(): Response
{
return new Response(null, Response::HTTP_NO_CONTENT);
}
// 一个“预期的”错误:带有 404 状态码的 JSON 响应
#[Route('/not-found', name: 'not_found')]
public function notFound(): JsonResponse
{
return $this->json(['message' => 'This resource does not exist'], Response::HTTP_NOT_FOUND);
}
// 同样的效果,通过 HTTP 异常实现,Symfony 会将其转换为 404 响应
#[Route('/abort', name: 'abort')]
public function abort(): never
{
throw $this->createNotFoundException('This resource does not exist either');
}
// 一个“意外的”错误:未处理的异常会产生 500 响应
#[Route('/error', name: 'error')]
public function unexpectedError(): never
{
throw new RuntimeException('An unexpected error');
}
// 疏忽:操作必须返回 Response 对象;数组会被拒绝
#[Route('/oversight', name: 'oversight')]
public function oversight(): array
{
return ['lastName' => 'Martin'];
}
}
|
让我们来分析这段代码:
- 第 13–16 行:该控制器继承自 FrameworkBundle 的 [AbstractController] 类。这是通常分配给控制器的父类:它为控制器提供了快捷方法——只用一行就能完成最常见任务的方法:[json]、[redirect]、[redirectToRoute]、[render]、[createNotFoundException]、[addFlash]……我们会在各个示例中不断遇到它们;
- 第 15 行:类上的属性为所有路由指定了路径前缀、名称前缀和 GET 方法;现在每个动作只需指定自己的路径和名称;
- 第 19–24 行:[new Response(...)] 构造一个完整的 HTTP 响应:正文、状态码,然后是用关联数组表示的头部(关联数组中的每个元素都有一个键,这里是 ['Content-Type'],写在箭头 [=>] 之前)。[Response] 类为每个状态码定义了一个常量:[Response::HTTP_OK] 等于 200。头部 [Content-Type] 在这里声明为纯文本([text/plain]):浏览器不会解释其中的标签;
- 第 27–31 行:同样的字符串,但不声明类型:[Symfony] 以类型 [text/html] 发送它,浏览器会对其进行解释;
- 第 35–39 行:[AbstractController] 的 [json] 方法把它的参数转换为 JSON,并生成类型为 [application/json] 的响应(一个 [JsonResponse] 对象,是 [Response] 的子类)。转换由 Serializer 组件完成,它来自 [Symfony],随示例一起安装:对象会变成一个 JSON 对象,其字段是它的公共属性(以及其方法 [getXxx]、[isXxx] 和 [hasXxx] 返回的结果)。[Person] 类在下面描述。该动作命名为 [asJson]:如果把它命名为 [json],它就会重新定义那个[json] 方法(继承自 [AbstractController]),而 [PHP] 会因类检查失败而报错,因为这两个方法的参数不相同;
- 第 42–46 行:一个关联数组[PHP] 变成一个 JSON 对象。[PHP] 数组是一种万能的结构:它既是列表,又是字典;
- 第 49–53 行:带有隐式键(0、1、2)的数组是一个列表;它变成一个 JSON 数组;
- 第 56–62 行:一个计算得到的数组。函数 [sort] 对数组排序(它会修改数组本身);[array_map] 对每个元素应用一个函数并返回结果数组。[fn (int $n) => $n * 10] 是一个箭头函数:精简为一个表达式的匿名函数,它返回该表达式的值;
- 第 65–69 行:[json] 的第二个参数是状态码:201([Created])取代 200。可选的第三个参数用于提供头部:[['X-Example' => '03']];
- 第 72–76 行:代码 204([No Content])表示“没有可显示的内容”:响应没有正文([null]);
- 第 79–83 行:一个“预期之内”的错误:404 响应([Not Found]),正文(JSON)由动作选择。文本用双引号括起,因为其中含有撇号;
- 第 86–90 行:同样的错误,由异常引起。[createNotFoundException] 抛出异常 [NotFoundHttpException] (一个HTTP 异常,携带 404 代码);[throw] 语句引发它,从而中断动作。[Symfony] 会把它转换为错误响应。类型 [never] 表示该方法永远不会正常结束。这是因出错而终止动作最常见的方式,即使是在由动作调用的函数深处也可以这样做;
- 第 93–97 行:一个“意外”的错误——即无人处理的异常——会产生 500 响应([Internal Server Error])。[RuntimeException] 是 [PHP] 标准库中的一个异常类,像其他任何类一样通过 [use] (第 7 行)导入;
- 第 100–104 行:应当避免的错误。[Symfony] 动作必须返回一个 [Response] 对象;这个动作返回的是数组,[Symfony] 会拒绝它(我们将在下面查看响应)。这与其他框架不同,例如 [Laravel],它们自己会把数组转换为 JSON:[Symfony] 更希望动作明确指定它想要的响应。
[Person] 类:
| <?php
// src/Model/Person.php:一个人员
namespace App\Model;
// 一个类,其属性在构造函数中声明(提升);
// readonly:构造之后属性不能再更改
readonly class Person
{
public function __construct(
public string $lastName,
public string $firstName,
public int $age,
) {
}
}
|
- 第 8 行:[readonly] 使类的所有属性在初始化之后不可修改:[Person] 对象是不可变的;
- 第 10–14 行:[__construct] 是类的构造函数,由 [new Person('Martin', 'Jean', 42)] 调用。它的参数前面带有 [public],被提升:每个参数都声明一个同名的属性,并由该参数初始化。这种语法避免了先声明属性、再在构造函数体中逐个赋值的麻烦(这里构造函数体是空的)。这些属性是公共的:Serializer 可以看到它们。并没有要求必须把这个类放在名为 [Model] 的文件夹中;这是本文档所做的选择。
还剩下文件 [src/EventListener/ReadableJson.php]:
| <?php
// src/EventListener/ReadableJson.php:便于人类阅读的 JSON
namespace App\EventListener;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpKernel\Event\ResponseEvent;
use Symfony\Component\HttpKernel\KernelEvents;
// 一个事件监听器(EVENT LISTENER):每次触发 [kernel.response] 事件时,Symfony 都会调用它,
// 该事件在操作生成响应之后、响应发送之前触发
#[AsEventListener(event: KernelEvents::RESPONSE)]
class ReadableJson
{
public function __invoke(ResponseEvent $event): void
{
$response = $event->getResponse();
if ($response instanceof JsonResponse) {
// 使用 "é" 而不是 "é",使用 "/" 而不是 "\/",并且采用
// 缩进的布局,分成多行
$response->setEncodingOptions(JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES
| JSON_PRETTY_PRINT);
}
}
}
|
默认情况下,[JsonResponse] 响应包含紧凑的单行 JSON,其中非 ASCII 字符被写成转义序列:[é] becomes [é],这是有效的 JSON,但可读性不佳。本课程的示例需要可读的 JSON。我们不在每个动作中逐一请求,而是修改应用中的所有 JSON 响应,办法是借助 [Symfony] 的核心机制:事件。
为了处理一个请求,[Symfony] 内核要经过一系列步骤,并在每一步触发一个事件:请求到达时触发 [kernel.request] ,动作被选定时触发 [kernel.controller] ,响应生成时触发 [kernel.response] ,依此类推。(生命周期一章会全面介绍它们。)监听器 (listener)是一个类,[Symfony] 会为给定类型的每个事件调用它;它可以查看和修改事件携带的数据。[Symfony] 本身就是这样构造的:路由、安全和会话都是监听器。
- 第 13 行:属性 [#[AsEventListener]] 使该类成为事件 [kernel.response] (常量 [KernelEvents::RESPONSE])的监听器。无需再声明其他任何东西:该类是一个服务(示例 02),并且 [Symfony] 会读取它的属性([autoconfigure]);
- 第 16 行:声明在类上的监听器通过其方法 [__invoke] 被调用。它接收事件,即一个 [ResponseEvent] 对象,其中带有请求和响应;
- 第 18–24 行:如果响应是 JSON 响应(运算符 [instanceof] 用于检查对象的类),监听器就会修改其编码选项:非 ASCII 字符和斜杠按原样写出,并采用缩进格式。运算符 [|] 把这三个选项组合起来,它们是 [PHP] 的常量;[setEncodingOptions] 会重新编码响应数据。
示例 05 至 12 复用了这个监听器。命令 [php bin/console debug:event-dispatcher kernel.response] 会列出事件监听器:我们的监听器就在 [Symfony] 自带的那些之中。
在浏览器中,[text/plain] 和 [text/html] 的差别清晰可见:


下面是其他动作的结果:
| curl -i http://localhost:8000/responses/json
|
| HTTP/1.1 200 OK
Content-Type: application/json
{
"lastName": "Martin",
"firstName": "Jean",
"age": 42
}
|
对象被转换成了 JSON 对象,每个公共属性对应一个字段。[/responses/array] 动作产生完全相同的响应。
| curl -i http://localhost:8000/responses/list
curl http://localhost:8000/responses/calc
|
| HTTP/1.1 200 OK
Content-Type: application/json
[
"Mme",
"Melle",
"Mr"
]
[
10,
20,
30
]
|
| curl -i http://localhost:8000/responses/created
|
| HTTP/1.1 201 Created
Content-Type: application/json
{
"message": "resource created"
}
|
| curl -i http://localhost:8000/responses/empty
|
| curl -i http://localhost:8000/responses/not-found
|
| HTTP/1.1 404 Not Found
Content-Type: application/json
{
"message": "This resource does not exist"
}
|
| curl -i http://localhost:8000/responses/abort
|
| HTTP/1.1 404 Not Found
Content-Type: text/html; charset=UTF-8
X-Debug-Exception: This%20resource%20does%20not%20exist%20either
...
<!-- This resource does not exist either (404 Not Found) -->
<!DOCTYPE html>
...
|
异常响应是 [Symfony] 的详细错误页面,即示例 02 中的那个,带有我们的消息。当客户端通过 [Accept: application/json] 头部([-H] 选项,来自 [curl])请求 JSON 响应时,[Symfony] 会调整其错误响应,使之成为一个 JSON 文档(使用 Serializer):
| curl -i -H "Accept: application/json" http://localhost:8000/responses/abort
|
| HTTP/1.1 404 Not Found
Vary: Accept
Content-Type: application/json
...
{"type":"https:\/\/tools.ietf.org\/html\/rfc2616#section-10","title":"An error occurred","status":404,"detail":"This resource does not exist either","class":"Symfony\\Component\\HttpKernel\\Exception\\NotFoundHttpException","trace":[...]}
|
该文档遵循“问题详情”标准(RFC 7807):类型、标题、代码和详情(我们的消息)。在调试模式下,它还包含异常名称和调用栈 ([trace],即出错时正在执行的函数列表)。这个文档不是由动作生成的 [JsonResponse] ;因此,我们的监听器没有对它进行格式化。[Vary: Accept] 头部告知缓存:响应取决于请求中的 [Accept] 头部。
接下来是未处理的异常。在调试模式下,浏览器显示 [Symfony] 的错误页面:异常的类型和消息、抛出异常的文件和行号及其周围的代码,然后是调用栈,从最近的调用到最早的调用:

栈中的第一个函数是我们的动作 [unexpectedError],位于文件 [ResponsesController.php] 的第 96 行。接下来是调用它的内核方法([HttpKernel::handleRaw]、[HttpKernel::handle]、[Kernel::handle]……),一直到 [public/index.php]。Logs 选项卡显示请求期间生成的日志消息。这就是为什么调试模式 绝不 应在他人可以访问的服务器上启用。错误还会写入应用日志——这里就是服务器控制台:
| [Sun Sep 27 11:10:31 2026] [critical] Uncaught PHP Exception RuntimeException: "An unexpected error" at ResponsesController.php line 96
|
在没有调试模式的情况下(文件 [APP_ENV=prod] 位于 [.env] 中),同样的请求会产生一个简短的错误页面,不会泄露任何关于代码的信息:
| HTTP/1.1 500 Internal Server Error
Content-Type: text/html; charset=UTF-8
...
<div class="container">
<h1>Oops! An Error Occurred</h1>
<h2>The server returned a "500 Internal Server Error".</h2>
...
|
而 JSON 文档现在只包含代码及其标签(["detail":"Not Found"]),没有我们的消息,也没有调用栈。第 7 章将展示如何显示应用专属的错误页面。(部署到生产环境后,必须删除 [var/cache/prod] 文件夹或运行 [php bin/console cache:clear]:在生产环境中,[Symfony] 不再检查其配置是否已更改。)
最后是没有返回 [Response] 对象的动作:
| curl -i http://localhost:8000/responses/oversight
|
| HTTP/1.1 500 Internal Server Error
Content-Type: text/html; charset=UTF-8
...
<!-- The controller must return a "Symfony\Component\HttpFoundation\Response" object but it returned an array ([lastName => ...]). (500 Internal Server Error) -->
...
|
消息很明确:“The controller must return a Response object, but it returned an array.”(控制器必须返回 Response 对象,但它返回了一个数组。)我们会在生命周期一章中看到,这并不完全正确:[kernel.view] 事件的监听器可以自己把数组转换为响应。
2.4. 示例 04:重定向
重定向 是一种指示浏览器去获取另一个 URL 的响应:一个 3xx 状态码以及 [Location] 头部,其中包含新的地址。浏览器会立即向该地址发送第二个请求。控制器 [RedirectsController]:
| <?php
// src/Controller/RedirectsController.php:重定向
namespace App\Controller;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
#[Route(methods: ['GET'])]
class RedirectsController extends AbstractController
{
// 永久重定向(301):页面的地址已永久更改
#[Route('/old', name: 'old')]
public function oldPage(): RedirectResponse
{
return $this->redirect('/new', Response::HTTP_MOVED_PERMANENTLY);
}
#[Route('/new', name: 'new')]
public function newPage(): Response
{
return new Response('You are on the [new] page');
}
// 临时重定向(302,默认代码),指向通过
// 拼接文本片段计算出的地址
#[Route('/go/{destination}', name: 'go')]
public function go(string $destination): RedirectResponse
{
return $this->redirect('/page/'.$destination);
}
// redirectToRoute 构建由名称指定的路由的地址:
// [name] 参数会针对 URL 被正确编码
#[Route('/to-route/{destination}', name: 'to_route')]
public function toRoute(string $destination): RedirectResponse
{
return $this->redirectToRoute('page', ['name' => $destination]);
}
// name:路由的名称,可用于构建其 URL
#[Route('/page/{name}', name: 'page')]
public function page(string $name): Response
{
return new Response("You are on the [$name] page");
}
// 重定向到另一个站点
#[Route('/documentation', name: 'documentation')]
public function documentation(): RedirectResponse
{
return $this->redirect('https://symfony.com/doc');
}
}
|
- 第 11 行:一个没有路径的 [#[Route]] 类属性:它只为所有路由指定 GET 方法;
- 第 15–19 行:[redirect] 方法(来自 [AbstractController] )生成一个指向指定地址的重定向响应(一个 [RedirectResponse] 对象)。代码 301([Moved Permanently])表示该页面的地址已永久 更改:浏览器(以及搜索引擎)可以记住新地址;
- 第 29–33 行:没有第二个参数时,[redirect] 会生成状态码为 302(临时 重定向)的响应([Found])。URL 是通过拼接文本片段([.] 运算符)构造的,这会带来一个问题,我们稍后会看到;
- 第 37–41 行:[redirectToRoute] 创建一个重定向,指向由其名称 而不是路径来标识的路由 (['page'])。关联数组提供路由参数(这里是 [name]),并为 URL 正确地编码 。如果路由 [page] 的路径日后发生更改,指向它的重定向会自动更新;
- 第 44 行:路由名称 [page],由属性提供;
- 第 51–55 行:重定向到另一个站点;地址按原样使用。
使用 [curl] 查看响应(它在没有任何选项时不会跟随重定向):
| curl -i http://localhost:8000/old
|
| HTTP/1.1 301 Moved Permanently
Location: /new
Content-Type: text/html; charset=utf-8
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8" />
<meta http-equiv="refresh" content="0;url='/new'" />
<title>Redirecting to /new</title>
</head>
<body>
Redirecting to <a href="/new">/new</a>.
</body>
</html>
|
头部 [Location] 包含动作所提供的地址,相对于站点:浏览器会补上当前页面的协议、主机和端口。响应中还包含一个简短的 HTML 正文,供不跟随重定向的客户端使用。[-L] 选项(来自 [curl] )会像浏览器一样跟随重定向:
| curl -L http://localhost:8000/old
|
| You are on the [new] page
|
现在来比较这两个计算得到的重定向,其目标中含有一个问号,在 URL 中编码为 [%3F] (未编码的 [?] 会开启 URL 的参数部分):
| curl -i http://localhost:8000/go/a%3Fb
curl -i http://localhost:8000/to-route/a%3Fb
|
| HTTP/1.1 302 Found
Location: /page/a?b
...
HTTP/1.1 302 Found
Location: /page/a%3Fb
...
|
[Symfony] 先解码了路由参数再处理它:[$destination] 等于 [a?b]。第一个动作把它原样粘贴回地址中:[/page/a?b],浏览器把它解释为路径 [/page/a] 后跟参数 [b]。第二个动作遵循命名路由,其参数会被重新编码:[/page/a%3Fb]。跟随重定向:
| curl -L http://localhost:8000/go/a%3Fb
curl -L http://localhost:8000/to-route/a%3Fb
|
| You are on the [a] page
You are on the [a?b] page
|
只有第二个会通向正确的页面。因此有这样一条规则:包含变量值的地址要根据其路由名称来构造([redirectToRoute],在视图中则是函数 [path]),绝不要通过拼接字符串来构造。在浏览器中,你只会看到最终页面;地址栏显示新的 URL:

还存在另外两个重定向代码:303([See Other])和 307([Temporary Redirect]),它们通过 [$this->redirect($url, 303)] 获得。在 POST 请求之后,代码 302 和 303 会使浏览器向新地址发送 GET 请求,而 307(以及 308,即永久版本)则会使它重复 POST 请求。示例 20 将使用 POST 之后的重定向。
2.5. 示例 05:Request 和 Response 对象
到目前为止,动作只接收路由参数并返回单行响应。动作还可以访问当前的请求 并逐步构建其响应 。[HttpController] 控制器:
| <?php
// src/Controller/HttpController.php:请求和响应对象
namespace App\Controller;
use RuntimeException;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\StreamedResponse;
use Symfony\Component\Routing\Attribute\Route;
#[Route('/http', name: 'http_', methods: ['GET'])]
class HttpController extends AbstractController
{
// 请求:方法、路径、参数、头部……
// Symfony 会将当前请求的 Request 对象传递给带类型的 $request 参数
#[Route('/request', name: 'request')]
public function requestInfo(Request $request): JsonResponse
{
return $this->json([
'method' => $request->getMethod(),
'path' => $request->getPathInfo(),
'url' => $request->getUri(),
'parameters' => $request->getQueryString(),
'browser' => $request->headers->get('User-Agent'),
'ip' => $request->getClientIp(),
]);
}
// 响应:我们为它添加一个头部
#[Route('/header', name: 'header')]
public function header(): Response
{
$response = new Response('Response with an added header');
$response->headers->set('X-Example', '05-request-response');
return $response;
}
// 一次性构建的响应:主体、状态码、头部
#[Route('/response', name: 'response')]
public function response(): Response
{
return new Response('Response built by [new Response(...)]', Response::HTTP_OK,
['Content-Type' => 'text/plain; charset=utf-8']);
}
// 以分块方式发送的响应:状态码和头部随
// 第一个块一起发出,此后不能再更改
#[Route('/stream', name: 'stream')]
public function streamed(): StreamedResponse
{
return new StreamedResponse(function () {
echo 'Start of the response... ';
// 该块会立即发送给浏览器
flush();
sleep(1);
// 此时再宣告错误已经太晚:200 状态码已经发出
throw new RuntimeException('error in the middle of the response');
}, Response::HTTP_OK, ['Content-Type' => 'text/plain; charset=utf-8']);
}
}
|
- 第 20 行:该动作有一个类型为 [Request] 的参数。这个参数并非来自 URL:[Symfony] 检测到它的类型 ,并向它提供当前请求的 [Request] 对象——即由 [public/index.php] 创建的那个(示例 01)。准备动作参数的任务由参数值解析器完成:每个解析器都知道如何提供某一种特定类型的参数(路由参数、请求、服务、表单数据等)。参数的顺序无关紧要:动作可以同时接收请求和路由参数;
- 第 22–29 行:请求的一些方法:HTTP 方法、路径、完整 URL、原始参数(URL 中跟在 [?] 之后的部分)、[User-Agent] 头部(浏览器)以及客户端的 IP 地址。头部存放在请求的 [headers] 属性中,这是一个头部“包”,其 [get] 方法按名称返回某个头部。参数将在下一章中逐个讲解;
- 第 34–39 行:先创建响应,再填充它:其属性 [headers] 同样是一个头部包,其中 [set] 添加头部 [X-Example](按惯例,应用专属的头部常常以 [X-] 开头);
- 第 43–47 行:一次性构造的响应:正文、状态码和头部;
- 第 52–62 行:分块 发送的响应(streaming)。[StreamedResponse] 对象接收一个函数,由该函数自己写出响应的正文,写出时使用 [echo] (来自 [PHP] 的、向响应写入内容的指令);[flush()] 会立即把已写出的内容发送给浏览器。响应的长度事先并不知道:服务器先发送状态码和头部,然后每个数据块一生成就发送出去。这对于一点一点生成的超长响应很有用。但是一旦第一个数据块发出,状态码就无法再改变:这里的函数在第一个数据块之后抛出了异常。这是必须避免的错误:已经开始的响应无法转换为错误响应。
监听器 [ReadableJson] 就是示例 03 中的那个。响应如下:
| curl -i "http://localhost:8000/http/request?name=martin&age=42"
|
| HTTP/1.1 200 OK
Content-Type: application/json
{
"method": "GET",
"path": "/http/request",
"url": "http://localhost:8000/http/request?age=42&name=martin",
"parameters": "age=42&name=martin",
"browser": "curl/8.5.0",
"ip": "127.0.0.1"
}
|
URL 两边的引号可以防止终端解释字符 [&]。请注意,参数已按字母顺序排序:[getQueryString] 和 [getUri] 生成参数字符串的规范化形式,这使得可以比较两个 URL 值(例如,这对缓存很有用)。在浏览器中,头部 [User-Agent] 就是该浏览器的头部。
| curl -i http://localhost:8000/http/header
|
| HTTP/1.1 200 OK
X-Example: 05-request-response
Content-Type: text/html; charset=UTF-8
Response with an added header
|
| curl -i http://localhost:8000/http/response
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Response built by [new Response(...)]
|
| curl -i http://localhost:8000/http/stream
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Start of the response... <!-- Warning: Cannot modify header information - headers already sent (500 Internal Server Error) -->
<!DOCTYPE html>
<html lang="en">
...
|
一秒钟后,[curl] 收到下一个响应:一个错误页面。在调试模式下,[Symfony] 试图用其错误页面(状态码 500)来处理该异常;但头部已经连同 状态码 200 发送出去了。它别无选择,只能把其错误页面追加到已发送正文的末尾。客户端收到的是 200 状态码和一个不连贯的正文;如果没有调试模式,它收到的只是一个被截断的正文,而无从得知发生了错误。只有应用日志会指出这一点:
| [Sun Sep 27 11:10:31 2026] [critical] Uncaught PHP Exception RuntimeException: "error in the middle of the response" at HttpController.php line 60
[Sun Sep 27 11:10:31 2026] 127.0.0.1:37644 [200]: GET /http/stream
|
请注意第二行中的 200 响应码。
2.6. 示例 06:共享服务与依赖注入
动作不应包含应用逻辑本身;它把逻辑委托给服务——即知道如何执行某项特定任务(读取商品、计算购物车等)的对象。多个动作常常使用同一个服务。[Symfony] 和 [Spring] 或 [ASP.NET Core] 一样,有一个服务容器:一个创建服务并自动把它们提供给需要者的对象。这就是依赖注入。容器是 [Symfony] 的核心:框架中的一切都是服务(路由器、日志、会话、视图引擎等),应用的控制器本身也是服务(示例 02)。示例 06 按领域(商品、客户)而不是按类型(控制器、模型)来组织代码:
| 06-services/
├── config/
│ └── services.yaml
├── src/
│ ├── Clients/
│ │ └── ClientsController.php
│ ├── EventListener/
│ │ └── ReadableJson.php
│ ├── Products/
│ │ ├── Product.php
│ │ ├── ProductsController.php
│ │ ├── ProductsService.php
│ │ └── InMemoryProductsService.php
│ └── Kernel.php
└── ...
|
并没有要求必须把控制器放在 [src/Controller] 中:[src] 文件夹中的任何类都是服务(文件 [config/services.yaml]),如果带有 [#[Route]] 属性,它就会成为控制器(示例 02)。
2.6.1. 商品
| <?php
// src/Products/Product.php:一个产品
namespace App\Products;
// readonly:该对象是不可变的(其属性由构造函数设置)
readonly class Product
{
public function __construct(
public int $id,
public string $name,
// 价格以分为单位:整数,以便精确计算
public int $priceCents,
) {
}
}
|
- 第 7 行:一个不可变类(见示例 03)。不可变对象可以在代码的多个部分之间安全地共享;
- 第 9–15 行:属性及其类型,如制造商所宣称的那样。价格是整数;以分 为单位的价格(150 表示 1.50 欧元)。这是在 [PHP] 中处理金额的标准方式:[PHP] 没有十进制类型;类型为 [float] 的浮点数以二进制表示,无法精确表示 0.1 或 3.2(在二进制中,这些数有无限多位):对 [float] 价格求和可能得到 5.500000000000001。而整数之和则始终是精确的。
2.6.2. 服务契约:ProductsService.php
| <?php
// src/Products/ProductsService.php:服务的契约,说明它能做什么,而不说明如何做
namespace App\Products;
interface ProductsService
{
/** @return list<Product> */
public function findAll(): array;
// ?Product:一个产品,如果不存在则为 null
public function findById(int $id): ?Product;
}
|
- 第 6 行:服务契约:它能做什么,而不规定怎么做。在 [PHP] 中,和在 [Java] 或 [C#] 中一样,契约由接口定义:一组没有方法体的方法列表,必须由实现 该接口的类实现其中的全部方法;
- 第 8 行:文档注释([/** ... */])。类型 [array] 没有说明数组包含什么;注解 [@return list<Product>]——[PHP] 会忽略它——是为代码编辑器说明这一点:一个商品列表;
- 第 12 行:[?Product]:一个商品,如果不存在则为 [null] 。
2.6.3. 实现:InMemoryProductsService.php
| <?php
// src/Products/InMemoryProductsService.php:该契约的一个实现,使用内存中的数据
namespace App\Products;
class InMemoryProductsService implements ProductsService
{
/** @var list<Product> */
private array $products;
public function __construct()
{
$this->products = [
new Product(1, 'pen', 150),
new Product(2, 'notebook', 320),
new Product(3, 'eraser', 80),
];
}
public function findAll(): array
{
// PHP 数组在传递时会被复制:调用方收到的是一个副本
return $this->products;
}
public function findById(int $id): ?Product
{
// array_find:函数返回 true 的第一个元素,或者 null
return array_find($this->products, fn (Product $p) => $p->id === $id);
}
}
|
- 第 6 行:该类实现契约并定义它的两个方法;
- 第 9 行:一个 private 属性——只有类自己的代码可以使用它;
- 第 11–18 行:构造函数把商品存放在属性中,该属性写作 [$this->products] ([$this] 是当前对象);
- 第 20–24 行:该方法返回商品数组。在 [PHP] 中,数组是一种值 ,传递时会被复制:调用方收到的是一份副本,可以随意修改而不影响服务的数据(不过 [Product] 对象并没有被复制,但它们是不可变的);
- 第 26–30 行:函数 [array_find] ([PHP] 8.4)返回数组中第一个使给定函数返回 [true] 的元素,如果没有则返回 [null] 。[===] 表示严格相等:值相同且类型相同。
2.6.4. 商品控制器:ProductsController.php
| <?php
// src/Products/ProductsController.php:/products 的操作
namespace App\Products;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
#[Route('/products', name: 'products_', methods: ['GET'])]
class ProductsController extends AbstractController
{
// 服务由 Symfony 注入到构造函数中:控制器只
// 知道契约(接口),而不知道其实现
public function __construct(private ProductsService $service)
{
}
#[Route('', name: 'list')]
public function listAll(): JsonResponse
{
return $this->json($this->service->findAll());
}
#[Route('/{id<\d+>}', name: 'one')]
public function oneProduct(int $id): JsonResponse
{
$product = $this->service->findById($id);
if ($product === null) {
return $this->json(['message' => "Product no. $id not found"], Response::HTTP_NOT_FOUND);
}
return $this->json($product);
}
}
|
- 第 14–18 行:控制器需要该服务;它把服务声明为其构造函数的一个参数。当 [Symfony] 创建控制器(以处理请求)时,它会检查构造函数各参数的类型,并把该类型的服务传给每个参数:这就是构造函数注入,它由 [autowire] 设置启用,该设置位于 [config/services.yaml] 文件中(稍后介绍)。带有 [private] 前缀的参数被提升为私有属性(见示例 03):动作通过 [$this->service] 使用它。控制器只知道服务的契约 (即接口),而不知道其实现:它并不知道商品存放在内存中;
- 第 20–24 行:动作把工作委托给服务。返回的商品数组变成 JSON 数组(示例 03):每个 [Product] 变成一个 JSON 对象;
- 第 26–34 行:未知的商品返回 404 响应,并带有 JSON 格式的消息。路径约束 [<\d+>] (示例 02)确保 [$id] 是整数。
2.6.5. 客户控制器:ClientsController.php
| <?php
// src/Clients/ClientsController.php:第二个控制器,使用同一个服务
namespace App\Clients;
use App\Products\Product;
use App\Products\ProductsService;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\Routing\Attribute\Route;
class ClientsController extends AbstractController
{
// 这一次,服务被注入到操作的参数中
#[Route('/clients/cart', name: 'clients_cart', methods: ['GET'])]
public function cart(ProductsService $service): JsonResponse
{
$products = $service->findAll();
// 价格之和,以分为单位:整数,因此计算是精确的
$total = array_reduce($products, fn (int $sum, Product $p) => $sum + $p->priceCents, 0);
return $this->json(['client' => 'Jean Martin', 'items' => count($products),
'totalCents' => $total, 'total' => '€'.number_format($total / 100, 2, '.', ',')]);
}
}
|
- 第 15–16 行:该控制器使用与商品控制器相同的服务。这一次,它把服务作为动作的参数来接收:[Symfony] 也会把服务注入到动作参数中,就像示例 05 中的请求那样。通过构造函数注入适用于所有动作都需要的服务;通过动作注入适用于只有某一个动作需要的服务;
- 第 20 行:[array_reduce] 把一个数组归约为单个值:函数接收累加值([$sum])和当前元素,并返回新的累加值;第三个参数是起始值 0;
- 第 21–22 行:[count] 返回数组中的元素个数。总额以分为单位返回,并格式化为欧元:[number_format] 把数字写成带两位小数的形式,使用句点作为小数分隔符,使用逗号作为千位分隔符(示例 16 将展示更好的金额格式化方式)。除法 [$total / 100] 产生一个 [float],但仅用于显示:实际的计算是用整数完成的。
2.6.6. 服务声明:config/services.yaml
| # config/services.yaml:应用程序的服务,Symfony 的
# 容器知道如何创建它们并提供给需要它们的对象
services:
# 此文件中声明的服务的默认设置
_defaults:
# autowire:构造函数的参数根据其类型提供
autowire: true
# autoconfigure:Symfony 根据类的属性和
# 接口来配置该类(#[Route] 使其成为控制器,#[AsEventListener] 使其成为监听器)
autoconfigure: true
# src/ 文件夹中的所有类都成为服务,以
# 其类名来标识
App\:
resource: '../src/'
# 实现的选择:当某个类请求 ProductsService 时,
# 容器会为它提供 InMemoryProductsService 服务
App\Products\ProductsService: '@App\Products\InMemoryProductsService'
|
- 第 4–10 行:该文件中服务的默认设置:[autowire] (自动装配)使容器根据构造函数参数的类型为其提供参数;[autoconfigure] 根据每个服务的属性和接口来配置它(示例 02);
- 第 12–15 行:[src] 文件夹中的每个类都变成一个服务,以其类的完整名称命名:[App\Products\InMemoryProductsService], [App\Products\ProductsController]……;
- 第 17–19 行:服务实现正是在这里,而且只在这里被选定。这一行把被请求的类型(接口)与提供它的服务关联起来([@] 按名称引用服务):这是一个别名。当某个类请求 [ProductsService] 时,容器会向它提供服务 [InMemoryProductsService]。要切换到从数据库读取的实现,只需修改这一行:只了解契约的控制器则保持不变。这就是依赖注入的全部意义:应用的每个部分都依赖于契约,而由唯一的一个位置来决定具体实现。
实际上,这一行在这里是可选的:当 [src] 文件夹中只有一个类实现某个接口时,[Symfony] 会自己创建别名。但是,一旦有两个实现,它就不知道该选哪一个,并拒绝构建容器:这时就需要别名,或者在所选类上添加 [#[AsAlias]] 属性。我们在这里写上它,是为了让选择清晰可见。而具体类则不需要任何特殊声明:容器就是这样创建控制器的。
默认情况下,服务是共享的 (shared):容器在第一次请求时只创建一个 [InMemoryProductsService] 对象,之后任何请求 [ProductsService] 的人都会收到同一个对象。这就是其他地方所说的单例。服务还是懒加载的:在一次请求期间无人请求的服务永远不会被创建。命令 [php bin/console debug:container] 会列出容器中的服务(几百个,包括 [Symfony] 自带的服务),而 [debug:autowiring] 会列出可以通过注入请求的类型:
| php bin/console debug:autowiring Products
|
| Autowirable Types
=================
Use the following classes & interfaces as type-hints in constructor arguments to autowire services.
Add #[Target('name')] to the argument to select a specific variant.
(only showing classes/interfaces matching Products)
App\Products\ProductsService → App\Products\InMemoryProductsService
|
最后说一说这个共享服务的生存期。正如我们在示例 01 中看到的:在 [PHP] 中,应用连同其容器会在每个请求时重新创建。因此服务只在单个请求内唯一:在处理一个请求期间请求它的所有类都会收到同一个对象,但下一个请求会收到一个新对象。对于像这个服务一样只读取静态数据的服务,这没有区别。对于数据会变化的服务(示例 20 中的任务列表),这些数据必须存放在对象之外的地方:文件、数据库或 [Symfony] 的缓存中。另一方面,[PHP] 服务不会被两个请求同时使用:每个请求都有自己的服务。在 [Java]、[C#] 或 [Python] 中,多个并发请求共享服务时所需的预防措施(尤其是锁)在这里是不必要的。
2.6.7. 执行
[php bin/console debug:router] 命令显示这三个路由,它们声明在两个不同的文件夹中:
| --------------- -------- ----------------
Name Method Path
--------------- -------- ----------------
clients_cart GET /clients/cart
products_list GET /products
products_one GET /products/{id}
--------------- -------- ----------------
|
| curl -i http://localhost:8000/products
|
| HTTP/1.1 200 OK
Content-Type: application/json
[
{
"id": 1,
"name": "pen",
"priceCents": 150
},
{
"id": 2,
"name": "notebook",
"priceCents": 320
},
{
"id": 3,
"name": "eraser",
"priceCents": 80
}
]
|
| curl -i http://localhost:8000/products/9
|
| HTTP/1.1 404 Not Found
Content-Type: application/json
{
"message": "Product no. 9 not found"
}
|
| curl -i http://localhost:8000/clients/cart
|
| HTTP/1.1 200 OK
Content-Type: application/json
{
"client": "Jean Martin",
"items": 3,
"totalCents": 550,
"total": "€5.50"
}
|