23. 实践练习 – 版本 12
在本章中,我们将编写一个遵循 MVC 架构(模型–视图–控制器)的 Web 应用程序。该应用程序能够以三种格式返回响应:JSON、XML 和 HTML。我们接下来要做的工作,比之前做过的复杂度显著提高。我们将复用迄今为止介绍的大部分概念,并详细讲解通向最终应用程序的所有步骤。
23.1. MVC 架构
我们将按如下方式实现称为 MVC(模型–视图–控制器)的架构模型:

客户端请求的处理过程如下:
- 1 - 请求:所请求的 URL 参数将采用如下形式 [http://machine:port/context/main.php?action=anAction¶m1=v1¶m2=v2&…]。[Main controller] 将使用 URL 中的 [action] 参数,把请求“路由”到负责处理该动作的次级控制器。URL 的其余部分以及 [param1=v1¶m2=v2&…] 是传递给该动作的可选参数。MVC 中的 C 就是字符串 [Main controller, Controller / Action]。如果没有任何控制器能够处理所请求的动作,服务器将响应所请求的动作无效;
- 2 - 处理:
- 所选的动作 [2a] 可以使用 [Main controller] 传给它的参数。这些参数可能来自多个来源:URL 中的 [/param1/param2/…] 路径、URL 中的 [param1=v1¶m2=v2] 参数,或由浏览器随请求提交的参数;
- 在处理用户请求时,动作可能需要 [business] 层和 [2b] 层。客户端请求处理完毕后,可能触发不同的响应。一个典型的例子是:如果请求未能被正确处理,则返回错误响应,否则返回确认响应;
- [Controller / Action] 会把它的响应 [2c] 连同状态码一起返回给主控制器。这些状态码将唯一地表示应用程序的当前状态,它们要么是成功码,要么是错误码;
- 3 - 响应:
- 根据客户端请求的是 JSON、XML 还是 HTML 响应,[Main controller] 将实例化相应类型的响应([3a])并指示它把响应发送给客户端。[Main controller] 会把已执行的 [Controller / Action] 所提供的响应和状态码传给它;
- 如果所需的响应是 JSON 或 XML 类型,所选的响应对象将对 [Controller / Action] 提供给它的响应进行格式化,并通过 [3c] 发送。能够处理该响应的客户端可以是 PHP 控制台脚本,也可以是嵌入在 HTML 页面中的 JavaScript 脚本;
- 如果所需的响应是 HTML 类型,所选的响应对象将根据提供给它的状态码选择其中一个 HTML 视图 [3b]([View1]、[View2]……) 。这就是 MVC 中的 V。每个状态码对应唯一的一个视图。该视图 V 将显示已执行的 [Controller / Action] 的响应。它使用 HTML、CSS 和 JavaScript 对该响应中的数据进行格式化。这些数据称为视图模型,它就是 MVC 中的“M”。客户端通常是 Web 浏览器。
现在来澄清 MVC Web 架构与分层架构之间的关系。根据模型的定义方式,这两个概念可能相关,也可能不相关。我们先来看一个单层的 MVC Web 应用程序:

在上面的示例中,每个 [Controller / Action] 组件都包含了 [business] 层和 [dao] 层的一部分。[web] 层确实具有 MVC 架构,但整个应用程序并不具有分层架构。这里只有一个层,什么都由它来做。
现在来看一个多层 Web 架构:

[web] 层可以不遵循 MVC 模型来实现。这样我们得到的是多层架构,但 Web 层并未实现 MVC 模型。
例如,在 .NET 世界中,[web] 层可以使用 ASP.NET Core MVC 来实现,从而得到 [web] 层为 MVC 类型的分层架构。完成之后,我们可以把这个 ASP.NET Core MVC 层替换为 ASP.NET Core [Razor Pages] 层,而其余部分(业务逻辑、DAO、驱动程序)保持不变。这样我们得到的分层架构中,[web] 层就不再是 MVC 类型。
在 MVC 中,我们说过模型 M 就是视图 V 的模型,即视图 V 所显示的数据集合。对于 MVC 的模型 M,还有另一种定义:

许多作者认为,位于 [web] 层右侧的部分构成了 MVC 的 M 模型。为避免歧义,我们可以这样称呼:
- 领域模型:指位于 [web] 层右侧的全部内容;
- 视图模型:指视图 V 所显示的数据。
23.2. 项目结构
对于这个项目,我们使用与 MVC 模型相对应的目录结构。在 [VS Code] 中,[scripts-web/tax/version-12] 文件夹包含以下内容:
| scripts-web/tax/version-12
├── Controllers
│ ├── AuthenticateUserController.php
│ ├── CalculateTaxController.php
│ ├── DeleteSimulationController.php
│ ├── DisplayTaxCalculationController.php
│ ├── EndSessionController.php
│ ├── InitSessionController.php
│ ├── InterfaceController.php
│ └── ListSimulationsController.php
├── Data
│ ├── .htaccess
│ ├── config.json
│ └── logs.txt
├── Entities
│ ├── Action.php
│ ├── ControllerResult.php
│ ├── ResponseType.php
│ └── Simulation.php
├── Responses
│ ├── HtmlResponse.php
│ ├── InterfaceResponse.php
│ ├── JsonResponse.php
│ ├── ParentResponse.php
│ └── XmlResponse.php
├── Tests
│ ├── view-authentication.php
│ ├── view-errors.php
│ ├── view-simulations-list.php
│ └── view-tax-calculation.php
├── Views
│ ├── logo.jpg
│ ├── v-authentication.php
│ ├── v-banner.php
│ ├── v-errors.php
│ ├── v-menu.php
│ ├── v-simulations-list.php
│ ├── v-tax-calculation.php
│ ├── view-authentication.php
│ ├── view-errors.php
│ ├── view-simulations-list.php
│ └── view-tax-calculation.php
├── index.php
└── main.php
|
- [main.php] 是我们这个 MVC 模型的主控制器,即 MVC 中的 C;
- [Controllers] 文件夹包含次级控制器。每个控制器处理一个特定的动作。该动作在 URL 中指定,例如 […/main.php?action=authenticate-user]。根据该动作,主控制器 [main.php] 将选择一个次级控制器(此处为 [AuthenticateUserController])来处理所请求的动作。这些控制器同样属于 MVC 中的 C;
- [Responses] 文件夹包含负责向客户端发送响应的类。每种所需的响应类型对应一个类:
- [JsonResponse]:用于 JSON 响应;
- [XmlResponse]:用于 XML 类型的响应;
- [HtmlResponse]:用于 HTML 响应;
- [Views] 文件夹包含需要 HTML 响应时使用的 HTML 视图,即 MVC 中的 V。它们由类 [HtmlResponse] 激活,该类把要显示的数据传给它们。这些数据就是视图模型。根据我们对 M 所采用的术语,这些数据可以是 MVC 中的 M;
- [Tests] 文件夹包含视图的测试版本,可用来调整视图的视觉外观;
- 文件夹 [Entities] 包含各个控制器所使用的类和枚举;
- [Data] 文件夹包含配置文件 [config.json] 和日志文件 [logs.txt]。与之前的版本一样,版本 8 中的 [.htaccess] 文件会阻止 [Apache] 提供这些文件:因为配置中包含密码。
PHP 7 课程复制了 [business] 层和 [dao] 层的类(文件夹 [Model])以及工具类(文件夹 [Utilities])。我们不复制它们:与之前的版本一样,这些类从版本 5、8、9 和 11 的文件夹中加载,它们最初就是在那里编写的。
借助这种目录结构,我们可以描述客户端所请求动作的处理流程:
- [main.php] 接收请求;
- 在执行一些初步检查(该动作是否属于被接受的动作之一?)之后,它把请求转发给负责处理该动作的次级控制器;
- 次级控制器执行其任务。在执行任务的过程中,它可能需要 [business] 层和 [dao] 层,以及文件夹 [Entities] 中的实体。它把响应返回给激活它的主控制器 [main.php];
- 根据客户端所请求的响应类型 [JSON, XML, HTML] ,主控制器 [main.php] 会激活文件夹 [Responses] 中的某一个响应类;
- 响应类 [JsonResponse, XmlResponse] 分别向客户端发送 JSON 或 XML 响应;
- 响应类 [HtmlResponse] 使用文件夹 [Views] 中的某个视图向客户端发送 HTML 响应;
- 各个组件访问版本 9 中的 [Logger] 类,把日志写入 [Data/logs.txt] 文件。记录的内容包括:
- 所请求的动作;
- 其控制器的响应。无论所请求的类型是 [JSON, XML, HTML] 中的哪一种,都以 JSON 格式记录;
- 发生致命错误(HTTP 状态 500 Internal Server Error)时,主控制器 [main.php] 使用版本 9 中的 [SendAdminMail] 类向管理员发送电子邮件。
23.3. 应用程序的动作
客户端把要执行的动作作为 URL [action] 中的参数 [/main.php?action=xxx] 发送给 Web 服务器。PHP 7 课程在配置文件中列出允许的动作,每个动作关联其控制器类的名称。我们改用枚举(PHP 8.1),即 [Entities] 文件夹中的 [Action] 枚举:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// 应用程序接受的操作:case 的值是 URL 中的操作名称
enum Action: string
{
case InitSession = "init-session";
case AuthenticateUser = "authenticate-user";
case CalculateTax = "calculate-tax";
case ListSimulations = "list-simulations";
case DeleteSimulation = "delete-simulation";
case EndSession = "end-session";
case DisplayTaxCalculation = "display-tax-calculation";
// 该操作是否要求已知会话类型(json、xml、html)?
public function requiresSessionType(): bool
{
return $this !== self::InitSession;
}
// 该操作是否要求用户已通过身份验证?
public function requiresAuthentication(): bool
{
return match ($this) {
self::InitSession, self::AuthenticateUser => false,
default => true,
};
}
}
|
说明
- 第 9 行:枚举 [Action] 是一个“带值”枚举:它的每个枚举项都有一个值,这里是 [string] 类型。我们在“类”一章中接触过枚举;
- 第 11 行:[init-session] 启动一个税务计算模拟会话。该动作指定所需的响应类型:[JSON, XML, HTML];
- 第 12 行:会话类型确定之后,客户端必须使用动作 [authenticate-user] 进行身份验证。在客户端通过身份验证之前,除 [init-session] 之外的所有其他动作都被禁止;
- 第 13 行:通过身份验证后,客户端可以使用动作 [calculate-tax] 进行一系列税务计算;
- 第 14 行:客户随时可以使用动作 [list-simulations] 请求查看自己已执行的模拟列表;
- 第 15 行:客户可以使用动作 [delete-simulation] 删除其中一部分;
- 第 16 行:客户使用动作 [end-session] 结束其模拟会话。此后,如果想继续使用该应用程序,就需要重新登录;
- 第 17 行:在 HTML 应用程序中,动作 [display-tax-calculation] 显示用于计算税额的表单;
- 第 20–23 行:枚举可以有方法。在方法内部,[$this] 指代正在为其调用该方法的枚举项。方法 [requiresSessionType] 指明该动作 是否只能在已知会话类型时才可执行:除 [init-session] 之外的所有动作都是如此。枚举的各个枚举项都是唯一的对象:使用 [===] 运算符对它们进行比较;
- 第 26–32 行:方法 [requiresAuthentication] 判断该动作是否只能由已通过身份验证的用户执行:除 [init-session] 和 [authenticate-user] 之外的所有动作都是如此。表达式 [match] 允许在同一个分支中使用以逗号分隔的多个值。
这些规则在 PHP 7 课程中写在主控制器里,现在则与动作定义放在一起。
23.4. Web 应用程序的配置
应用程序由如下 JSON 文件 [Data/config.json] 进行配置:
| {
"databaseFilename": "../version-08/Data/database-mysql.json",
"dependencies": [
"../../../scripts-console/tax/version-05/Entities/TaxException.php",
"../../../scripts-console/tax/version-05/Entities/TaxAdminData.php",
"../../../scripts-console/tax/version-05/Entities/Database.php",
"../../../scripts-console/tax/version-05/Utilities/Utilities.php",
"../version-08/Dao/InterfaceServerDao.php",
"../version-08/Dao/ServerDao.php",
"../version-09/Dao/ServerDaoWithSession.php",
"../version-08/Business/InterfaceServerBusiness.php",
"../version-08/Business/ServerBusiness.php",
"../version-09/Utilities/Logger.php",
"../version-09/Utilities/SendAdminMail.php",
"../version-11/Utilities/XmlUtilities.php",
"Entities/Simulation.php",
"Entities/ControllerResult.php",
"Entities/Action.php",
"Entities/ResponseType.php",
"Responses/InterfaceResponse.php",
"Responses/ParentResponse.php",
"Responses/JsonResponse.php",
"Responses/XmlResponse.php",
"Responses/HtmlResponse.php",
"Controllers/InterfaceController.php",
"Controllers/InitSessionController.php",
"Controllers/AuthenticateUserController.php",
"Controllers/CalculateTaxController.php",
"Controllers/ListSimulationsController.php",
"Controllers/DeleteSimulationController.php",
"Controllers/EndSessionController.php",
"Controllers/DisplayTaxCalculationController.php"
],
"users": [
{
"login": "admin",
"passwd": "admin"
}
],
"adminMail": {
"smtp-server": "localhost",
"smtp-port": 1025,
"from": "guest@localhost",
"to": "guest@localhost",
"subject": "tax calculation server crash",
"tls": false,
"attachments": []
},
"logsFilename": "Data/logs.txt",
"redis": {
"scheme": "tcp",
"host": "127.0.0.1",
"port": 6379
},
"views": {
"view-authentication.php": [700, 221, 400],
"view-tax-calculation.php": [200, 300, 341, 350, 800],
"view-simulations-list.php": [500, 600]
},
"view-errors": "view-errors.php"
}
|
说明
- 第 2 行:描述 MySQL 数据库 [dbtaxes-2019] 的 JSON 文件,它来自版本 8。路径相对于文件夹 [version-12];
- 第 3–33 行:应用程序的 PHP 文件。首先是已经编写好的类:
- 来自版本 5 的 [TaxException, TaxAdminData, Database] 实体和 [Utilities] 类;
- 来自版本 8 和 9 的 [dao] 层和 [business] 层;
- 来自版本 9 的工具类 [Logger] 和 [SendAdminMail] ,以及来自版本 11 的 [XmlUtilities] ;
- 以及版本 12 中的类,我们现在就来介绍。PHP 7 文件中还包含第三方库的绝对路径([C:/myprograms/laragon-lite/www/vendor/autoload.php]):现在 [Composer] 的类加载器由 [main.php] 使用相对路径直接加载;
- 第 34–39 行:获准使用该应用程序的用户;
- 第 40–48 行:应用程序管理员的电子邮件联系信息。邮件发送到 [Mailpit] 服务器,该服务器监听端口 1025(见版本 9);
- 第 49 行:日志文件的路径;
- 第 50–54 行:[Redis] 服务器的详细信息,该服务器用作 [application] 作用域的内存(见版本 10);
- 第 55–59 行:[HTML view => array of the status codes leading to this view] 的对应关系。稍后会对它们进行说明;
- 第 60 行:每当发生异常错误时,就会在 HTML 会话中显示 [view-errors.php] 视图:
- 像 JSON 或 XML 这样的应用程序,通常由编写好的客户端程序来查询。客户端向服务器传递参数,这些参数可能缺失或不正确。控制器处理这些情况,并向客户端返回错误码。所有可能的错误情形都必须得到处理;
- HTML 应用程序则略有不同。在正常使用下,Web 应用程序只用到 JSON 和 XML 客户端所有可能用例中的一个子集。举个例子:动作 [calculate-tax] 期望三个通过 POST 提交的参数:[married, children, salary]。使用允许手动输入 URL 的 JSON 客户端,你可以用 GET 而不是 POST 来请求动作 [calculate-tax] ,或者在需要三个参数时用不带任何提交参数的 POST 来请求,等等。JSON 服务器必须处理所有这些情况。而对于 Web 应用程序,动作 [calculate-tax] 将通过 Web 表单来请求,前面两种情况在表单中都不可能出现:动作 [calculate-tax] 将通过 POST 调用,并带有全部三个参数 [married, children, salary]。然而,用户可以在浏览器中手动输入 URL 值来重现某些错误。出于安全原因,必须处理这种情形;
- 视图 [view-errors.php] 将在次级控制器返回与 Web 应用程序不兼容的状态码时显示,即该状态码不在配置文件的 [views] 键中。出于教学目的,我们选择这种方案。另一种可能的做法是重新显示客户端浏览器中当前显示的视图,让用户觉得服务器没有响应他手工构造的 URL 请求。
与 PHP 7 课程的配置文件相比,键 [rootDirectory] (根目录现在称为 [main.php])、[actions] (由枚举 [Action] 取代)和 [types] (由下文介绍的枚举 [ResponseType] 取代)已被移除。
23.5. 工具和库
23.5.1. [curl] 工具
PHP 7 课程使用图形工具 [Postman] 来查询 Web 应用程序的各个 URL 组件。我们使用命令行工具 [curl],它已在 Web 服务一章中介绍过。它允许我们:
- 使用任意 URL:这些 URL 都是手工构造的;
- 使用 GET、POST、PUT、OPTIONS 等方法查询 Web 服务器(选项 [-X] 和 [-d]);
- 指定 GET(在 URL 中)或 POST 的参数(选项 [-d] 和 [--data-urlencode]);
- 设置请求的 HTTP 头(选项 [-H]);
- 接收 JSON、XML 或 HTML 格式的响应;
- 访问响应的 HTTP 头(选项 [-i]);
- 像浏览器一样处理会话 Cookie:[-c cookies.txt] 选项把服务器发送的 Cookie 保存到 [cookies.txt] 文件中,而 [-b cookies.txt] 选项则把它们发回给服务器。
由于我们手工生成所请求的 URL,因此能够测试所有可能的错误场景,并观察服务器如何响应。请记住,在 [PowerShell] 终端中,必须输入 [curl.exe] 而不是 [curl]。本章中的所有命令都在任意工作目录下打开的终端中输入,[curl] 会在该目录中创建文件 [cookies.txt]。
要提交参数 [married],我们使用选项 [--data-urlencode "married=yes"],必要时它会对参数名和值进行 URL 编码。参数名([married]、[number]……)不含带重音符号的字符,所以在 URL 中可以原样书写。
23.5.2. Symfony / Serializer 库
PHP 7 课程使用 [Symfony / Serializer] 库把服务器响应序列化为 JSON 和 XML,其中可能包含 [Simulation] 对象。它有两个优点:JSON 和 XML 使用同一套 API;可以序列化带有私有属性、通过 getter 公开的对象。
本版本中我们不使用它,尽管课程已把它安装在 [vendor] 文件夹中:
- 我们的类 [Simulation] 是一个带有公共属性的 [readonly] 类(见下一段)。函数 [json_encode] 直接序列化对象的公共属性:JSON 序列化不再需要库;
- 对于 XML,我们有版本 11 中的 [XmlUtilities] 类,它生成的 XML 文档与版本 11 的格式相同,XML 客户端已经知道如何处理。只需在把 [Simulation] 对象转换为关联数组之后,把数组提供给它即可;
- 服务器从不需要把 JSON 或 XML 反序列化为对象,而这正是 PHP 7 课程所强调的另一个优点。
因此,[Symfony / Serializer] 库在这里只会多增加一个依赖。当你需要把文档反序列化为带类型的对象,或需要处理多种不同格式时,它仍然是个不错的选择。
23.6. 应用程序实体
[Entities] 文件夹包含两个枚举,[Action] (已介绍)和 [ResponseType] (与服务器响应一起介绍),以及两个类。[Simulation] 类封装了一次税务计算模拟的各个要素:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// 一次税款计算模拟:一个不可变对象
final readonly class Simulation
{
// 这些属性是公共的:它们不能被修改 (readonly),但
// 可以不经 getter 直接读取,并由 [json_encode] 序列化
public function __construct(
// 计算参数
public string $married,
public int $children,
public int $salary,
// 计算结果
public int $tax,
public int $surcharge,
public int $discount,
public int $reduction,
public float $rate,
) {
}
}
|
说明
- 第 9 行:该类是 [readonly] 的(PHP 8.2):其所有属性都是只读的。模拟是一个不可变对象:一经构造就不再改变;
- 第 13–24 行:属性通过构造函数的参数声明并初始化(PHP 8.0)。它们都有类型:婚姻状况为 [string] ,其他参数和金额为 [int] ,税率为 [float] ;
- 属性是公共的:由于它们是只读的,不再需要用 getter 来保护它们。PHP 7 的类 [Simulation] 派生自类 [BaseEntity],有八个无类型的 [protected] 属性,以及八个 getter。
第二个类 [ControllerResult] 表示次级控制器返回给主控制器的结果:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// 次级控制器返回给主控制器的结果
final readonly class ControllerResult
{
public function __construct(
// 响应的 HTTP 状态码
public int $statusCode,
// 操作执行之后应用程序的状态
public int $status,
// 响应本身:一条消息、一个消息列表、一次模拟……
public mixed $response,
// 要添加到响应中的 HTTP 头
public array $headers = [],
) {
}
}
|
- 第 13 行:要发送给客户端的响应的 HTTP 状态码;
- 第 15 行:动作执行之后应用程序的状态;
- 第 17 行:响应本身。其类型取决于动作:一条消息、一个错误消息列表、一次模拟或一个模拟列表。类型 [mixed] (PHP 8.0)接受任意值;
- 第 19 行:要添加到响应中的 HTTP 头。这是一个可选参数。
在 PHP 7 课程中,控制器返回数组 [[$statusCode, $status, $content, $headers]]。带有具名且有类型的属性的对象更安全:你不会弄错元素的顺序。
23.7. 应用程序的工具类
该应用程序使用三个已经介绍过的工具类:
- 版本 9 中的 [Logger] 类可用于把事件记录到文本文件中;
- 版本 9 中的 [SendAdminMail] 类可用于向应用程序管理员发送电子邮件;
- 版本 11 中的 [XmlUtilities] 类可根据数组得到 XML 文档。
23.8. [business] 层和 [dao] 层

[business] 层和 [dao] 层的类和接口在之前的版本中都已定义并使用过:
类 | 作用 |
TaxException | 由 [dao] 层抛出的异常类。版本 5,文件夹 [Entities] |
InterfaceServerDao | 由服务器的 [dao] 层实现的接口。版本 8,文件夹 [Dao] |
ServerDao | [InterfaceServerDao] 接口的实现:税务数据从数据库中读取。版本 8 |
ServerDaoWithSession | 派生自 [ServerDao] 的类:税务数据可以提供给构造函数。版本 9,文件夹 [Dao] |
InterfaceServerBusiness | 由服务器的 [business] 层实现的接口。版本 8,文件夹 [Business] |
ServerBusiness | [InterfaceServerBusiness] 接口的实现:税额计算。版本 8 |
因此,当前正在开发的应用程序大量使用了已经介绍并使用过的元素:
- [business] 层和 [dao] 层;
- 工具类 [Logger]、[SendAdminMail]、和 [XmlUtilities];
- 实体 [TaxException, TaxAdminData, Database]。
我们将重点关注应用程序的 [web] 层:

23.9. 主控制器 [main.php]
23.9.1. 简介
主控制器 [main.php] 由文件 [Data/config.json] 配置。我们来回顾一下它在 MVC 架构中的位置:

主控制器 [main.php] 是 MVC 架构中第一个处理客户端请求的元素。它承担多种职责:
- 首先,它执行基本检查:
- 它的配置文件是否存在且有效?
- 它加载项目的所有依赖项。这包括加载 MVC 架构的所有组成部分;
- 是否指定了所请求的动作?如果指定了,它是否有效?
- 如果所请求的动作有效,它就选择 [2a]——即将处理该动作的次级控制器——并把所需的信息传给它:应用程序配置、HTTP 请求和会话;
- 它从次级控制器获取 [2c] 响应。根据客户端所请求的响应类型(JSON、XML、HTML),它选择 [3a] 负责向客户端发送响应的响应类(JsonResponse、XmlResponse、HtmlResponse),并把它所需的全部信息(HTTP 请求、会话、应用程序配置以及次级控制器的响应)传给它。
23.9.2. [main.php] - 1
主控制器 [main.php] 的开头如下:
| <?php
// 严格遵守所声明的函数参数和结果的类型
declare(strict_types=1);
// 命名空间
namespace Application;
// Symfony 依赖
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\Session\Session;
// PHP 错误不会发送给客户端(它们进入 Web 服务器的日志)
ini_set("display_errors", "0");
// 应用程序的根文件夹:配置文件的路径相对于此文件夹
const ROOT_DIRECTORY = __DIR__;
// 配置文件的路径
const CONFIG_FILENAME = ROOT_DIRECTORY . "/Data/config.json";
// Composer 的自动加载器(Symfony、Predis)
require_once ROOT_DIRECTORY . "/../../../vendor/autoload.php";
// 获取配置
$fileContents = is_readable(CONFIG_FILENAME) ? file_get_contents(CONFIG_FILENAME) : false;
if ($fileContents === false) {
sendConfigError(131, "The configuration file [config.json] does not exist");
}
try {
$config = json_decode($fileContents, true, flags: JSON_THROW_ON_ERROR);
} catch (\JsonException) {
sendConfigError(132, "The configuration file [config.json] could not be processed correctly");
}
|
说明
- 第 10–12 行:主控制器使用 Symfony 库 [HttpFoundation] 中的如下类:
- [Request]:当前正在处理的 HTTP 请求;
- [Response]:发给客户端的 HTTP 响应;
- [Session]:Web 应用程序的会话;
- 第 15 行:PHP 检测到的错误不会包含在发送给客户端的文档中:它们会破坏 JSON 或 XML 响应。这些错误仍会记录在 Web 服务器的错误日志中(Apache 的 [error.log] 文件)。在开发期间,可以把这一行注释掉:这样 PHP 错误就会出现在 [curl] 或浏览器收到的响应中,有助于调试。PHP 7 脚本还使用 [error_reporting(E_ALL && !E_WARNING && !E_NOTICE)] 修改了错误报告级别,顺带一提,这个表达式是不正确的(它需要使用按位运算符 [&] 和 [~]):恰恰相反,我们希望不忽略任何错误;
- 第 18 行:应用程序的根目录,即 [main.php] 脚本所在的目录。配置文件中的路径相对于该目录。该常量定义在 [Application] 命名空间中:因此该命名空间中的类可以看到它,尤其是将要计算税额的控制器;
- 第 20 行:配置文件的路径;
- 第 23 行:加载 [Composer] 的类加载器,使 Symfony 和 Predis 的类可用。它在读取配置之前加载:配置失败时发送的错误响应要用到 Symfony 的 [Response] 类。PHP 7 脚本在这里使用的是绝对路径;
- 第 26–29 行:读取配置文件。如果它不存在或无法读取,就通过 [131] 状态的错误响应,借助 [sendConfigError] 函数发送给客户端;
- 第 30–34 行:解码配置文件中的 JSON。使用 [JSON_THROW_ON_ERROR] 选项时,如果 JSON 无效,[json_decode] 函数会抛出 [JsonException] 异常。随后发送状态为 [132] 的错误响应。从 PHP 8.0 开始,不使用异常变量时,[catch] 子句可以省略它:[catch (\JsonException)];
这里我们假设配置文件存在且语法正确。还需要验证该文件中是否确实存在所期望的键。我们把这视为开发人员正常调试工作的一部分。
函数 [sendConfigError] 定义在脚本末尾:
| // --------------------------------------------------------------------------
// 配置文件出错:返回 JSON 500 响应,然后脚本结束
// 应用程序的类尚未加载:我们直接使用 [Response]
function sendConfigError(int $status, string $message): never
{
$json = json_encode(["action" => "", "status" => $status, "response" => $message], JSON_UNESCAPED_UNICODE);
$response = new Response($json, Response::HTTP_INTERNAL_SERVER_ERROR);
$response->headers->set("Content-Type", "application/json; charset=utf-8");
$response->send();
exit;
}
|
- 第 124 行:返回类型 [never] (PHP 8.1)表示该函数永远不会把控制权交还给调用者;它总是以 [exit] 或异常结束。诸如 [PHP Intelephense] 这样的 [VS Code] 扩展中的代码分析器就会知道,调用 [sendConfigError] 之后的代码只有在配置能够读取时才会执行;
- 第 126 行:Web 应用程序生成的所有响应都将包含三个键:
- [action]:客户端所请求的动作(此处未知);
- [status]:执行该动作之后应用程序的状态;
- [response]:Web 服务器的响应;
- 第 127 行:由于应用程序的类尚未加载,因此直接构造一个 Symfony 响应,状态为 [500 Internal Server Error];
- 第 128 行:响应是以 UTF-8 编码的 JSON 文档;
- 第 129 行:把响应发送给客户端。
23.9.3. [curl] 测试 - 1
我们来验证配置文件缺失或不正确时服务器的行为。把 [Data/config.json] 重命名为 [Data/config2.json],然后请求主控制器的 URL:
| > curl -i "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php"
HTTP/1.0 500 Internal Server Error
Date: Thu, 01 Oct 2026 16:51:52 GMT
Server: Apache/2.4.58
X-Powered-By: PHP/8.5.11
Cache-Control: no-cache, private
Connection: close
Content-Type: application/json; charset=utf-8
{"action":"","status":131,"response":"The configuration file [config.json] does not exist"}
|
- 第 1 行:选项 [-i] 指示 [curl] 显示响应中的 HTTP 头;
- 第 2 行:服务器返回状态码 [500 Internal Server Error];
- 第 8 行:响应是一个 JSON 文档;
- 第 10 行:响应中的 JSON 文档。这确实是我们所期望的文档。
我们把文件重命名回 [config.json],然后让它的语法出错——例如,删除第二行之后的所有内容。我们不再显示 HTTP 头:
| > curl "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php"
{"action":"","status":132,"response":"The configuration file [config.json] could not be processed correctly"}
|
第一个测试向我们表明,可以向被测服务器发送任何类型的请求,并且能收到完整的响应:HTTP 头以及紧随其后的文档。别忘了恢复 [config.json] 文件的内容。
23.9.4. [main.php] – 2
现在继续分析主控制器 [main.php]:
| // 我们引入应用程序的依赖
foreach ($config["dependencies"] as $dependency) {
require_once ROOT_DIRECTORY . "/$dependency";
}
// 当前请求
$request = Request::createFromGlobals();
// 会话 - 在加载类之后启动:它包含 [Simulation] 对象
$session = new Session();
$session->start();
// 创建日志文件
try {
$logger = new Logger(ROOT_DIRECTORY . "/" . $config["logsFilename"]);
} catch (TaxException) {
// 500 错误 - 没有日志的 JSON 响应
$content = [
"action" => "",
"status" => 133,
"response" => "The log file [{$config["logsFilename"]}] could not be created",
];
(new JsonResponse())->send($request, $session, $config, Response::HTTP_INTERNAL_SERVER_ERROR, $content);
exit;
}
|
说明
- 第 37–39 行:引入应用程序的所有依赖项。我们已经多次见过这段代码;
- 第 42 行:客户端请求中的所有信息都封装在 Symfony 的 [Request] 对象中;
- 第 44–45 行:启动一个新会话;如果客户端发送了会话 Cookie,则取回现有会话。会话在应用程序的类加载之后启动:它将包含 [Simulation] 对象,而 PHP 重建会话对象时,[Simulation] 类必须已经定义;
- 第 48–59 行:我们尝试创建 [Logger] 对象,它让我们能够把事件记录到 [Data/logs.txt] 文件中。创建可能失败:此时 [Logger] 的构造函数会抛出 [TaxException] 异常;
- 第 52–56 行:状态为 [133] 的错误响应。消息使用配置中指定的日志文件名而不是完整路径:完整路径会向客户端暴露服务器的文件夹结构;
- 第 57 行:响应通过 [JsonResponse] 对象发送,不记录日志,因为无法创建日志。此时应用程序的类已加载:可以使用它们;
- 第 58 行:脚本终止。
发送给客户端的所有响应都实现下面这个来自 [InterfaceResponse] 接口,位于 [Responses] 文件夹:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// Symfony 依赖
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Session\Session;
// 三种响应类型 [JsonResponse, XmlResponse, HtmlResponse] 所实现的接口
interface InterfaceResponse
{
// 向客户端发送响应
// Request $request:正在处理的请求
// Session $session:Web 应用程序的会话
// array $config:应用程序的配置
// int $statusCode:响应的 HTTP 状态码
// array $content:服务器的响应,即数组 [action, status, response]
// array $headers:要添加的 HTTP 头
// ?Logger $logger:应用程序的日志(如果无法创建则为 null)
public function send(
Request $request,
Session $session,
array $config,
int $statusCode,
array $content,
array $headers = [],
?Logger $logger = null
): void;
}
|
- 第 23–31 行:[InterfaceResponse] 接口只有一个方法 [send],用于向客户端发送响应;
- 第 16–22 行:[send] 方法各个参数的含义;
- 第 27–29 行:参数 [$statusCode]、[$content] 和 [$headers] 包含次级控制器的结果以及主控制器添加的键 [action, status] 。不过,响应可能还需要其他信息。因此,除前三个参数外,还会为它提供其他参数,使它能够访问有关请求、会话和配置的所有信息;
- 第 30 行:响应需要 [Logger] ,因为它要记录发送给客户端的响应。类型 [?Logger] 表示该参数可以为 [null]:无法创建日志时就是这种情况。在 PHP 7 的签名中,参数 [Request $request = NULL] 和 [Logger $logger = NULL] 是隐式可空的:这种语法自 PHP 8.4 起已被弃用。此外,把可选参数声明在必选参数之前,自 PHP 8.0 起也已被弃用。
类 [JsonResponse] 按如下方式实现接口 [InterfaceResponse]:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// Symfony 依赖
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Session\Session;
// JSON 响应
final class JsonResponse extends ParentResponse
{
#[\Override]
public function send(
Request $request,
Session $session,
array $config,
int $statusCode,
array $content,
array $headers = [],
?Logger $logger = null
): void {
// JSON 序列化:[json_encode] 也会序列化 [Simulation] 对象的公共属性
$json = json_encode($content, self::JSON_OPTIONS);
// 由父类发送响应
$this->sendResponse($statusCode, $json, "application/json", $headers);
// 日志
$logger?->write("response=$json");
}
}
|
说明
- 第 13 行:该类继承抽象类 [ParentResponse],后者实现了接口 [InterfaceResponse]。所有响应类型都继承这个类。向客户端发送响应的正是这个父类。由于这段代码对所有响应类型都是通用的,因此被提取到了父类中。我们的 [JsonResponse] 类不是 Symfony 的 [JsonResponse] 类:它位于 [Application] 命名空间中,并且我们没有导入 Symfony 的类;
- 第 15 行:属性(注解) [Override] (PHP 8.3)表明方法 [send] 实现的是父类或接口中的方法。如果并非如此(例如名称拼写错误),PHP 会报错;
- 第 26 行:响应 [$content] 被序列化为 JSON。[json_encode] 的选项一次性定义在父类中。函数 [json_encode] 把 [Simulation] 对象序列化为 JSON 对象,其键是该对象公共属性的名称;
- 第 28 行:请求父类把响应发送给客户端,并指定文档类型为 [application/json];
- 第 30 行:记录 JSON 响应。空安全运算符 [?->] 只有在 [$logger] 不是 [null] 时,才会调用方法 [write]。
父类 [ParentResponse] 的代码如下:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// Symfony 依赖
use Symfony\Component\HttpFoundation\Response;
// 三种响应类型的父类:它提取出它们的共同部分
// 它是抽象的:接口的 [send] 方法由子类实现
abstract class ParentResponse implements InterfaceResponse
{
// 所有响应使用的 [json_encode] 选项
protected const int JSON_OPTIONS = JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES
| JSON_PRESERVE_ZERO_FRACTION | JSON_THROW_ON_ERROR;
// 向客户端实际发送响应
// $statusCode:响应的 HTTP 状态码
// $body:响应的正文,视情况为 JSON、XML 或 HTML 字符串
// $contentType:所发送文档的类型 (application/json、application/xml、text/html)
// $headers:要添加的 HTTP 头
protected function sendResponse(int $statusCode, string $body, string $contentType, array $headers): void
{
// Symfony 响应
$response = new Response($body, $statusCode, $headers);
// 所发送文档的类型,采用 UTF-8 编码
$response->headers->set("Content-Type", "$contentType; charset=utf-8");
// 发送 HTTP 头,然后发送响应的正文
$response->send();
}
// 以 JSON 记录响应日志,无论所发送响应的类型是什么
protected function log(?Logger $logger, array $content): void
{
$logger?->write("response=" . json_encode($content, self::JSON_OPTIONS));
}
// 返回数据 [$data],其中的对象(模拟)已被
// 其公共属性的关联数组所替换
protected static function toArray(mixed $data): mixed
{
return match (true) {
is_object($data) => self::toArray(get_object_vars($data)),
is_array($data) => array_map(self::toArray(...), $data),
default => $data,
};
}
}
|
说明
- 第 13 行:该类是抽象类,不能被实例化。它实现了 [InterfaceResponse] 接口,但没有定义 [send] 方法,该方法将由子类定义。在 PHP 7 课程中,[ParentResponse] 是一个普通类,子类在实现接口的同时继承它;
- 第 16 行:所有响应共用的 [json_encode] 选项。自 PHP 8.3 起,类常量可以带类型:
- [JSON_UNESCAPED_UNICODE]:带重音符号的字符按原样书写,而不是写成 [\u00e9] 的形式;
- [JSON_UNESCAPED_SLASHES]:字符 [/] 不会被编码为 [\/];
- [JSON_PRESERVE_ZERO_FRACTION]:实数总是带小数点书写(零税率写作 [0.0]);
- [JSON_THROW_ON_ERROR]:序列化错误会抛出 [JsonException] 异常;
- 第 24 行:[sendResponse] 方法把响应发送给客户端。请注意,响应体 [$body] 的类型是 [string] ,因此可以直接发送;
- 第 27 行:Symfony 的 [Response] 类构造函数接收响应体、状态和头;
- 第 29 行:所发送文档的类型,以 UTF-8 编码;
- 第 31 行:把响应发送给客户端;
- 第 35 行:方法 [log] 以 JSON 形式记录响应。XML 和 HTML 响应类也会用到它;
- 第 42–49 行:静态方法 [toArray] 返回数据 [$data],其中的对象已被替换为其公共属性的关联数组。XML 响应类会用到它:
- 表达式 [match (true)] 选择第一个条件为真的分支;
- 第 45 行:对象被替换为其属性的数组,该数组由函数 [get_object_vars] 返回。从对象所属类的外部调用时,它只返回对象的公共属性。属性本身也可能是对象;因此要调用 [toArray];
- 第 46 行:数组的每个元素都由 [toArray] 转换。语法 [self::toArray(...)] (PHP 8.1)根据方法 [toArray] 创建一个匿名函数([Closure]):这就是一等可调用对象的语法。对于单个数组,函数 [array_map] 会保留数组的键;
- 第 47 行:其他值(字符串、数字)原样返回。
23.9.5. [curl] 测试 – 2
我们把文件 [config.json] 修改如下:["logsFilename": "Data"]。现在日志文件是 [Data],它是一个文件夹。因此创建文件 [Data] 应当会失败:
| > curl -i "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php"
HTTP/1.0 500 Internal Server Error
Date: Thu, 01 Oct 2026 16:51:52 GMT
Server: Apache/2.4.58
X-Powered-By: PHP/8.5.11
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: PHPSESSID=5c2f09b4ca8ff3ceb0601052072f6256; path=/
Cache-Control: no-cache, private
Connection: close
Content-Type: application/json; charset=utf-8
{"action":"","status":133,"response":"The log file [Data] could not be created"}
|
- 第 2 行:状态 [500 Internal Server Error];
- 第 7 行:会话 Cookie:会话在日志创建之前就已启动;
- 第 12 行:预期的 JSON 响应。
我们把值 [Data/logs.txt] 恢复给键 [logsFilename]。
23.9.6. [main.php] – 3
我们继续考察主控制器 [main.php]:
| // 第 1 条日志
$logger->write("---new request");
// 所请求的操作
$actionName = strtolower(trim($request->query->getString("action")));
$logger->write("action [$actionName] requested");
// 该操作是 [Action] 枚举的某个 case 吗?(否则为 null)
$action = Action::tryFrom($actionName);
// 预先检查:错误结果,如果可以执行该操作则为 null
$error = match (true) {
!$request->query->has("action") => [101, "missing parameter [action]"],
$action === null => [102, "invalid action [$actionName]"],
$action->requiresSessionType() && !$session->has("type")
=> [103, "no session in progress. Start with action [init-session]"],
$action->requiresAuthentication() && !$session->has("user")
=> [104, "action requested by unauthenticated user"],
default => null,
};
if ($error !== null) {
// 我们准备错误响应但不发送
[$status, $message] = $error;
$result = new ControllerResult(Response::HTTP_BAD_REQUEST, $status, [$message]);
} else {
// 我们用其次级控制器执行该操作
$controller = match ($action) {
Action::InitSession => new InitSessionController(),
Action::AuthenticateUser => new AuthenticateUserController(),
Action::CalculateTax => new CalculateTaxController(),
Action::ListSimulations => new ListSimulationsController(),
Action::DeleteSimulation => new DeleteSimulationController(),
Action::EndSession => new EndSessionController(),
Action::DisplayTaxCalculation => new DisplayTaxCalculationController(),
};
$logger->write("controller : " . $controller::class);
$result = $controller->execute($config, $request, $session);
}
// 给客户端的响应:先是 [action, status],然后是控制器的响应
$content = ["action" => $actionName, "status" => $result->status, "response" => $result->response];
// 致命错误:我们向管理员发送电子邮件
if ($result->statusCode === Response::HTTP_INTERNAL_SERVER_ERROR) {
// [SendAdminMail] 会捕获所有异常并自行记录
(new SendAdminMail($config["adminMail"], $logger))
->send(json_encode($content, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR));
}
// 响应的类型在会话中 - 如果尚未设置,默认为 JSON
$type = ResponseType::tryFrom($session->get("type", "")) ?? ResponseType::Json;
// 所请求类型的 [InterfaceResponse] 对象向客户端发送响应
$type->response()->send(
$request,
$session,
$config,
$result->statusCode,
$content,
$result->headers,
$logger
);
// 结束
exit;
|
说明
- 第 62 行:我们记录收到新请求这一事实。之前无法这样做,因为当时还无法确定是否有有效的日志文件;
- 第 65 行:参数 [action] 必须以 [main.php?action=anAction] 的形式出现在 URL 中。因此它属于 URL 的 [$request->query] 参数。Symfony 的 [getString] 方法以字符串形式返回参数的值,如果参数缺失则返回空字符串;
- 第 66 行:记录所请求的动作;
- 第 68 行:带值枚举的静态方法 [tryFrom] 返回值为 [$actionName] 的枚举项,如果没有枚举项具有该值,则返回 [null] 。方法 [from] 作用相同,但在第二种情况下会抛出 [ValueError] 异常;
- 第 70–78 行:初步检查。它们的结果 [$error] 要么是描述所遇到的第一个错误的数组 [status, message] ,要么在动作可以执行时为 [null] 。各条件按以下顺序求值:
- 第 71 行:URL 中缺少参数 [action] :状态 [101];
- 第 72 行:动作未知:状态 [102];
- 第 73 行:应用程序提供三种响应类型(JSON、XML、HTML)。该类型由动作 [init-session] 设置,并存入会话,关联到键 [type]。除动作 [init-session] 外,所有动作都必须在会话中存在键 [type] 时才能执行;否则状态为 [103];
- 第 75 行:除动作 [init-session] 和 [authenticate-user] 外,所有动作都必须在身份验证之后执行。身份验证通过 [authenticate-user] 动作完成,如果验证成功,该动作会在会话中设置键 [user];否则状态为 [104];
- 第 77 行:没有错误;
- 第 79–82 行:如果所请求的动作或其执行环境不正确,则准备好错误响应但暂不发送:状态 [400 Bad Request]、状态、错误列表(此处只有一个错误)。解构赋值 [[$status, $message] = $error] 在一条语句中给 [$error] 数组的两个元素赋值。
- 第 85–93 行:这是一个有效的操作。我们实例化将处理它的次级控制器。PHP 7 课程根据配置构造控制器类名([__NAMESPACE__ . $config["actions"][$action]]),然后用 [new $controller()] 进行实例化。表达式 [match] 作用于枚举 [Action] 的各枚举项更安全:[VS Code] 的代码分析器会检查类名,如果枚举中新增了枚举项却没有在这里添加,[match] 就会抛出 [UnhandledMatchError] 异常,而不是实例化一个随意的类;
- 第 94 行:记录次级控制器的名称,以便在开发期间进行验证。从 PHP 8.0 开始,[$object::class] 返回对象的完整类名;
- 第 95 行:执行次级控制器。它返回一个 [ControllerResult] 对象。稍后我们会再回到次级控制器;
- 不论是因为发生了错误,还是在某个控制器执行之后,我们都会到达第 99 行。无论哪种情况,对象 [$result] 都包含生成客户端响应所需的全部内容;
- 第 99 行:发给客户端的响应是一个包含三个键 [action, status, response] 的数组。键 [action] 有助于更好地跟踪 [logs.txt] 文件中的日志。键 [status] 将起到两个作用:
- 它使 JSON 和 XML 客户端能够确定所执行的动作使 Web 应用程序进入了什么状态;
- 对于 HTML 响应,它使系统能够选择要发送给客户端浏览器的 HTML 视图;
- 第 101–104 行:状态码 [500 Internal Server Error] 的特殊情形。如果控制器设置了这个状态码,就意味着应用程序无法工作。例如在税额计算中,如果 DBMS 或 [Redis] 服务器没有启动或不再响应,就属于这种情况。随后会使用版本 9 中的 [SendAdminMail] 类向应用程序管理员发送电子邮件通知;
- 第 107 行:确定响应类型 [JSON, XML, HTML]。如果动作 [init-session] 已成功执行,则该类型存在于会话中,关联到键 [type]。如果不是这样,会话的 [get] 方法就返回默认值 [""],[tryFrom] 返回 [null],然后运算符 [??] 选择 JSON 类型;
- 第 109–117 行:稍后介绍的枚举 [response] 的方法 [ResponseType] 返回与会话类型相应的对象 [JsonResponse]、[XmlResponse] 或 [HtmlResponse]。它的方法 [send] 把响应发送给客户端。由于这三个类实现的是同一个 [InterfaceResponse] 接口,它们的 [send] 方法都具有相同的签名;
- 第 119 行:主控制器已完成其工作。PHP 7 脚本在这里关闭日志文件;我们的 [Logger] 类不再有 [close] 方法。
23.9.7. [curl] 测试 – 3
我们来测试 URL 中 [action] 参数的各种错误场景:
| > curl "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php"
{"action":"","status":101,"response":["missing parameter [action]"]}
> curl "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=x"
{"action":"x","status":102,"response":["invalid action [x]"]}
> curl "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=list-simulations"
{"action":"list-simulations","status":103,"response":["no session in progress. Start with action [init-session]"]}
|
- 第 1–2 行:URL 中没有 [action] 参数的请求:状态 [101];
- 第 4–5 行:带有无效 [action] 参数的请求:状态 [102];
- 第 7–8 行:动作已被识别,但尚未指定会话类型(json、xml、html):状态 [103]。
在这三种情况下,键 [response] 都是一个错误列表,此处只包含一个错误。
23.10. 次级控制器
每个动作都由 [Controllers] 文件夹中的某个控制器执行:

在上面的应用程序整体架构中,次级控制器位于 [2a]。每个控制器都实现下面的 [InterfaceController] 接口:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// Symfony 依赖
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Session\Session;
// 所有次级控制器实现的接口
interface InterfaceController
{
// 处理所请求的操作
// array $config:应用程序的配置
// Request $request:正在处理的请求
// Session $session:Web 应用程序的会话,控制器可以修改它
// 返回 [ControllerResult] 对象:HTTP 状态、应用程序状态、响应、HTTP 头
public function execute(array $config, Request $request, Session $session): ControllerResult;
}
|
说明
- 第 20 行:所有次级控制器都通过 [execute] 方法执行。主控制器已知的信息会传给该方法:
- [array $config]:应用程序配置;
- [Request $request]:当前正在处理的 HTTP 请求;
- [Session $session]:Web 应用程序的当前会话;
- [execute] 方法返回一个 [ControllerResult] 对象:响应的 HTTP 状态码、执行结束时应用程序的状态、要发送给客户端的响应,以及要添加到响应中的 HTTP 头。
PHP 7 的方法有第四个参数 [array $infos = NULL],它是“以防万一”而加入的,却从未使用过:我们已将其删除。每个次级控制器由主控制器中的如下代码调用:
| // 我们用其次级控制器执行该操作
$controller = match ($action) {
Action::InitSession => new InitSessionController(),
Action::AuthenticateUser => new AuthenticateUserController(),
Action::CalculateTax => new CalculateTaxController(),
Action::ListSimulations => new ListSimulationsController(),
Action::DeleteSimulation => new DeleteSimulationController(),
Action::EndSession => new EndSessionController(),
Action::DisplayTaxCalculation => new DisplayTaxCalculationController(),
};
$logger->write("controller : " . $controller::class);
$result = $controller->execute($config, $request, $session);
|
23.11. 动作
现在我们来回顾 Web 服务所有可能的动作:
动作 | 作用 | 执行环境 |
init-session | 用于指定所需响应的类型(json、xml、html) | 请求 GET main.php?action=init-session&type=x 可在任何时候发出 |
authenticate-user | 授权或拒绝用户的登录 | 请求 POST main.php?action=authenticate-user 请求必须包含两个 POST 参数:[user, password] 只有在已知会话类型(json、xml、html)时才能发出 |
calculate-tax | 执行一次税务计算模拟 | 请求:POST main.php?action=calculate-tax 请求必须包含三个 POST 参数:[married, children, salary] 只有在已知会话类型且用户已通过身份验证时才能发出 |
list-simulations | 请求自会话开始以来已执行的模拟列表 | 请求 GET main.php?action=list-simulations 该请求不接受任何其他参数 只有在已知会话类型且用户已通过身份验证时才能发出 |
delete-simulation | 从模拟列表中删除一次模拟 | 请求 GET main.php?action=delete-simulation&number=x 该请求不接受任何其他参数 只有在已知会话类型且用户已通过身份验证时才能发出 |
end-session | 结束模拟会话 | 请求 GET main.php?action=end-session 从技术上讲,旧的 Web 会话被删除,并创建一个新会话 只有在已知会话类型且用户已通过身份验证时才能发出 |
display-tax-calculation | 显示税额计算视图(HTML 应用程序) | 请求 GET main.php?action=display-tax-calculation 只有在已知会话类型且用户已通过身份验证时才能发出 |
所有次级控制器的处理方式都相同:
- 它们检查自己的参数。URL 中的参数位于 [$request->query] 对象中,而通过 POST 提交的参数位于 [$request->request] 对象中(POST 请求);
- 控制器类似于一个检查其参数有效性的函数或方法。但对控制器来说,情况要复杂一些:
- 期望的参数可能缺失;
- 期望的参数都是字符串,而函数可以指定其参数的类型。如果期望的参数是数字,就必须验证该参数的字符串确实表示一个数字;
- 在验证了期望的参数存在且语法正确之后,还必须验证它们在当前执行环境中是否有效。该环境保存在会话中。身份验证就是执行环境的一个例子:某些动作只有在客户端通过身份验证之后才应被处理。会话中的一个键指示这一身份验证是否已经完成;
- 完成上述检查之后,次级控制器才能开始处理。这种参数验证非常重要。我们不能允许客户端在应用程序生命周期的任何时刻向我们发送任意内容。我们必须完全掌控应用程序的生命周期;
- 完成工作后,次级控制器返回调用它的主控制器所期望的 [ControllerResult] 对象。
现在我们来回顾各个控制器——换句话说,就是驱动 Web 应用程序生命周期的各个动作。
23.11.1. [init-session] 动作
动作 [init-session] 由如下控制器 [InitSessionController] 处理:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// Symfony 依赖
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\Session\Session;
// 操作 [init-session]:设置会话响应的类型(json、xml、html)
final class InitSessionController implements InterfaceController
{
#[\Override]
public function execute(array $config, Request $request, Session $session): ControllerResult
{
// 必须是 GET 请求,且 URL 中只有参数 [action, type]
if ($request->getMethod() !== "GET" || $request->query->count() !== 2) {
$message = "GET method required with parameters [action, type] in the URL";
return new ControllerResult(Response::HTTP_BAD_REQUEST, 701, $message);
}
// [type] 参数必须存在
if (!$request->query->has("type")) {
return new ControllerResult(Response::HTTP_BAD_REQUEST, 702, "missing parameter [type]");
}
// 并且有效:如果字符串不是枚举任何 case 的值,[tryFrom] 返回 null
$type = strtolower(trim($request->query->getString("type")));
if (ResponseType::tryFrom($type) === null) {
return new ControllerResult(Response::HTTP_BAD_REQUEST, 703, "invalid type parameter [$type]");
}
// 我们把会话类型放入会话
$session->set("type", $type);
// 成功
return new ControllerResult(Response::HTTP_OK, 700, "session started with type [$type]");
}
}
|
说明
- 期望收到 [GET main.php?action=init-session&type=xxx] 请求;
- 第 14 行:该类实现 [InterfaceController] 接口。它是 [final] 的:不能被继承;
- 第 20–23 行:我们验证请求是带有两个 URL 参数的 GET 请求。如果不是,则向主控制器返回状态为 [701] 的错误结果。Symfony 的 [getMethod] 方法以大写形式返回 HTTP 方法的名称:不再需要像 PHP 7 脚本那样把它转换为小写;
- 第 25–27 行:我们验证 URL 中是否存在参数 [type] 。如果不存在,则返回状态为 [702] 的错误结果;
- 第 29 行:记录会话类型;
- 第 30–32 行:检查会话类型是否为 (json, xml, html) 之一,即该值必须是枚举 [ResponseType] 的某个枚举项。如果不是,则返回状态为 [703] 的错误结果;
- 第 34 行:在 Web 应用程序会话中设置会话类型;
- 第 36 行:控制器已完成其工作。向主控制器返回成功结果,状态为 [700]。
每种错误情形都会立即 [return]。PHP 7 脚本使用一个布尔变量 [$error] ,并在每一步进行检查:现在代码更短,也更易读。我们来回顾主控制器对次级控制器响应所做的处理:它向响应添加键 [action] 和 [status] ,并根据当前会话的类型(json、xml、html)实例化 [JsonResponse, XmlResponse, HtmlResponse] 中的某个类来发送它。
接下来,我们将在 [curl] 测试中使用 [json] 模拟会话。
23.11.2. [curl] 测试
| > curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=init-session"
{"action":"init-session","status":701,"response":"GET method required with parameters [action, type] in the URL"}
> curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=init-session&typ=json"
{"action":"init-session","status":702,"response":"missing parameter [type]"}
> curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=init-session&type=x"
{"action":"init-session","status":703,"response":"invalid type parameter [x]"}
> curl -i -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=init-session&type=json"
HTTP/1.0 200 OK
Date: Thu, 01 Oct 2026 16:51:52 GMT
Server: Apache/2.4.58
X-Powered-By: PHP/8.5.11
Cache-Control: max-age=0, private, must-revalidate
Cache-Control: no-cache, private
Connection: close
Content-Type: application/json; charset=utf-8
{"action":"init-session","status":700,"response":"session started with type [json]"}
|
- 第 1–2 行:不带 [init-session] 参数 [type] 的动作:请求没有两个期望的参数;状态 [701];
- 第 4–5 行:动作 [init-session] 使用参数 [typ] 而不是 [type]:状态 [702];
- 第 7–8 行:动作 [init-session] 带有不正确的参数 [type]:状态 [703];
- 第 10–20 行:动作 [init-session] ,类型为 [json]:状态 [700]。
选项 [-c cookies.txt -b cookies.txt] 使 [curl] 像浏览器一样处理会话 Cookie。该 Cookie 由服务器在对第一个请求的响应中发送(第 1–2 行);[curl] 把它保存到文件 [cookies.txt] 中,并在每次请求时把它发回。服务器不再发送它(第 11–18 行);它只在新会话开始时才发送。文件 [cookies.txt] 现在包含:
| # Netscape HTTP Cookie File
# https://curl.se/docs/http-cookies.html
# This file was generated by libcurl! Edit at your own risk.
localhost FALSE / FALSE 0 PHPSESSID db36f12e4dfdc064484514a065ed0c0d
|
23.11.3. [authenticate-user] 动作
动作 [authenticate-user] 由如下控制器 [AuthenticateUserController] 执行:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// Symfony 依赖
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\Session\Session;
// 操作 [authenticate-user]:用提交的参数 [user, password] 对用户进行身份验证
final class AuthenticateUserController implements InterfaceController
{
#[\Override]
public function execute(array $config, Request $request, Session $session): ControllerResult
{
// 必须是 POST 请求,且 URL 中只有一个参数 [action]
if ($request->getMethod() !== "POST" || $request->query->count() !== 1) {
$message = "POST method required, parameter [action] in the URL, posted parameters [user, password]";
return new ControllerResult(Response::HTTP_BAD_REQUEST, 201, $message);
}
// 我们获取提交的参数
$errors = [];
$status = 210;
// 用户
if (!$request->request->has("user")) {
$status += 2;
$errors[] = "missing parameter [user]";
}
// 密码
if (!$request->request->has("password")) {
$status += 4;
$errors[] = "missing parameter [password]";
}
// 有错误吗?
if ($errors !== []) {
return new ControllerResult(Response::HTTP_BAD_REQUEST, $status, $errors);
}
$user = trim($request->request->getString("user"));
$password = trim($request->request->getString("password"));
// 该用户是授权用户之一吗?
$found = array_any(
$config["users"],
fn(array $u): bool => $u["login"] === $user && hash_equals($u["passwd"], $password)
);
if (!$found) {
// 失败:代码 401 - 密码绝不会发回给客户端
return new ControllerResult(Response::HTTP_UNAUTHORIZED, 221, "Authentication failed [$user]");
}
// 我们在会话中记录已通过身份验证的用户的标识符
$session->set("user", $user);
// 成功
return new ControllerResult(Response::HTTP_OK, 200, "Authentication successful [$user]");
}
}
|
说明
- 我们期望收到带有两个 POST 提交参数 [POST main.php?action=authenticate-user] 的请求,即 [user, password];
- 第 20–23 行:系统检查是否为带有一个 URL 参数的 POST 请求。如果不是,则返回状态为 [201] 的错误结果;
- 第 26 行:针对 POST 提交参数的错误状态从值 210 开始;
- 第 28–31 行:我们检查 POST 提交的值中是否存在参数 [user] 。如果不存在,就记录错误并把状态加 2;
- 第 33–36 行:我们检查是否存在参数 [password]。如果不存在,就记录错误并把状态加 4。因此,如果只缺少 [user] ,状态为 212;如果只缺少 [password] ,状态为 214;两者都缺少则为 216;
- 第 38–40 行:如果任何一个 POST 提交的值缺失,就返回错误结果,其响应为错误列表;
- 第 41–42 行:POST 提交的身份标识;
- 第 44–47 行:验证数对 [[$user, $password]] 是否存在于配置文件的 [$config["users"]] 数组中。如果数组中至少有一个元素满足箭头函数所表达的条件,函数 [array_any] (PHP 8.4)就返回 [true] 。密码使用函数 [hash_equals] 进行比较,其执行时间与第一个不同字符的位置无关:攻击者无法通过测量响应时间逐字符猜出密码。PHP 7 脚本使用的是 [while] 循环;
- 第 48–51 行:如果未找到用户,则返回 HTTP 状态为 [401 Unauthorized] 、应用状态为 [221] 的错误结果。PHP 7 的消息中包含所输入的密码:密码绝不能回传给客户端,也不能写入日志;
- 第 53 行:身份验证成功。通过在会话中添加键 [user](以用户标识为值)来记录这一点。该键的存在表示身份验证成功;
- 第 55 行:向主控制器返回成功结果,状态为 [200]。
23.11.4. [curl] 测试
我们在之前打开的会话中,以 JSON 模式继续测试 [AuthenticateUserController] 控制器:
| > curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=calculate-tax" -d "children=2"
{"action":"calculate-tax","status":104,"response":["action requested by unauthenticated user"]}
> curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=authenticate-user"
{"action":"authenticate-user","status":201,"response":"POST method required, parameter [action] in the URL, posted parameters [user, password]"}
> curl -c cookies.txt -b cookies.txt -X POST "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=authenticate-user"
{"action":"authenticate-user","status":216,"response":["missing parameter [user]","missing parameter [password]"]}
> curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=authenticate-user" -d "password=x"
{"action":"authenticate-user","status":212,"response":["missing parameter [user]"]}
> curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=authenticate-user" -d "user=x"
{"action":"authenticate-user","status":214,"response":["missing parameter [password]"]}
> curl -i -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=authenticate-user" -d "user=x&password=x"
HTTP/1.0 401 Unauthorized
Date: Thu, 01 Oct 2026 16:51:52 GMT
Server: Apache/2.4.58
X-Powered-By: PHP/8.5.11
Cache-Control: max-age=0, private, must-revalidate
Cache-Control: no-cache, private
Connection: close
Content-Type: application/json; charset=utf-8
{"action":"authenticate-user","status":221,"response":"Authentication failed [x]"}
> curl -i -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=authenticate-user" -d "user=admin&password=admin"
HTTP/1.0 200 OK
Date: Thu, 01 Oct 2026 16:51:52 GMT
Server: Apache/2.4.58
X-Powered-By: PHP/8.5.11
Cache-Control: max-age=0, private, must-revalidate
Cache-Control: no-cache, private
Connection: close
Content-Type: application/json; charset=utf-8
{"action":"authenticate-user","status":200,"response":"Authentication successful [admin]"}
|
- 第 1–2 行:在任何身份验证之前就请求税额计算。选项 [-d] 把请求转换为 POST。主控制器拒绝该动作:状态 [104];
- 第 4–5 行:动作 [authenticate-user] 在需要 POST 时使用了 GET:状态 [201];
- 第 7–8 行:不带 POST 提交参数的 POST(选项 [-X POST]):状态 [216];
- 第 10–11 行:只带 [password] 参数的 POST:状态 [212]。使用 [-d] 选项时,参数的提交方式与 HTML 表单相同:请求体是字符串 [password=x],并且头 [Content-Type] 被设置为 [application/x-www-form-urlencoded];
- 第 13–14 行:只带单个参数 [user] 的 POST;状态 [214];
- 第 16–26 行:使用无效身份标识的 POST:状态 [221]。请注意响应状态 [401 Unauthorized] (第 17 行);
- 第 28–38 行:使用有效身份标识的 POST:状态 [200] 以及状态 [200 OK] (第 29 行)。
23.11.5. 动作 [calculate-tax]
[calculate-tax] 动作由如下 [CalculateTaxController] 控制器处理:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// Symfony 依赖
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\Session\Session;
// Predis 依赖
use Predis\Client as RedisClient;
use Predis\PredisException;
// 类别名:版本 9 的 [dao] 层配合 Redis 使用
use Application\ServerDaoWithSession as ServerDaoWithRedis;
// 操作 [calculate-tax]:用提交的参数 [married, children, salary] 计算税款
final class CalculateTaxController implements InterfaceController
{
#[\Override]
public function execute(array $config, Request $request, Session $session): ControllerResult
{
// 必须是 POST 请求,且 URL 中只有一个参数 [action]
if ($request->getMethod() !== "POST" || $request->query->count() !== 1) {
$message = "you must use the [post] method with [action] in the URL"
. " and the posted parameters [married, children, salary]";
return new ControllerResult(Response::HTTP_BAD_REQUEST, 301, $message);
}
// 我们检查提交的参数
// 每个错误都会给状态加上一个不同的值:最终状态说明发生了哪些错误
$errors = [];
$status = 310;
// 婚姻状况
if (!$request->request->has("married")) {
$status += 2;
$errors[] = "missing parameter [married]";
} else {
$married = strtolower(trim($request->request->getString("married")));
if (!in_array($married, ["yes", "no"], true)) {
$status += 4;
$errors[] = "invalid value [$married] for parameter [married]";
}
}
// 子女数和年薪:整数 >= 0
$values = [];
foreach (["children" => [8, 9], "salary" => [16, 17]] as $parameter => [$missing, $invalid]) {
if (!$request->request->has($parameter)) {
$status += $missing;
$errors[] = "missing parameter [$parameter]";
continue;
}
$value = trim($request->request->getString($parameter));
if (preg_match('/^\d+$/', $value) !== 1) {
$status += $invalid;
$errors[] = "invalid value [$value] for parameter [$parameter]";
} else {
$values[$parameter] = (int) $value;
}
}
// 有错误吗?
if ($errors !== []) {
return new ControllerResult(Response::HTTP_BAD_REQUEST, $status, $errors);
}
[$children, $salary] = [$values["children"], $values["salary"]];
// 我们有了有效的参数 - [application] 作用域的内存:一个 Redis 服务器
try {
$redis = new RedisClient($config["redis"]);
// 我们立即连接到服务器,以确认它是否存在
$redis->connect();
} catch (PredisException $ex) {
// 500 错误
return new ControllerResult(
Response::HTTP_INTERNAL_SERVER_ERROR,
350,
"[redis], " . self::utf8($ex->getMessage())
);
}
// 创建 [dao] 层
try {
$json = $redis->get("taxAdminData");
if ($json === null) {
// 税务数据取自数据库,然后放入 Redis
$dao = new ServerDaoWithRedis(ROOT_DIRECTORY . "/" . $config["databaseFilename"]);
$redis->set("taxAdminData", (string) $dao->getTaxAdminData());
} else {
// 税务数据取自 Redis
$taxAdminData = TaxAdminData::fromArray(json_decode($json, true, flags: JSON_THROW_ON_ERROR));
$dao = new ServerDaoWithRedis($taxAdminData);
}
} catch (TaxException $ex) {
// 500 错误
return new ControllerResult(Response::HTTP_INTERNAL_SERVER_ERROR, 341, self::utf8($ex->getMessage()));
} finally {
// 我们不再需要 Redis 服务器
$redis->disconnect();
}
// 创建 [business] 层并计算税款
$result = (new ServerBusiness($dao))->calculateTax($married, $children, $salary);
// 模拟:[$result] 数组的键成为命名参数
$simulation = new Simulation($married, $children, $salary, ...$result);
// 我们把它添加到会话的模拟列表中
$session->set("simulations", [...$session->get("simulations", []), $simulation]);
// 成功
return new ControllerResult(Response::HTTP_OK, 300, $simulation);
}
// DBMS 或 Redis 驱动的错误消息可能不是 UTF-8 编码
// (Windows 上是 Windows-1252):这样就无法把它放入 JSON 字符串
private static function utf8(string $message): string
{
return mb_check_encoding($message, "UTF-8") ? $message : mb_convert_encoding($message, "UTF-8", "Windows-1252");
}
}
|
说明
- 期望的请求是带有三个 POST 提交参数 [POST main.php?action=calculate-tax] 的 [married, children, salary]:
- [married] 的值必须在 [yes, no] 之中;
- [children, salary] 必须是正整数或零;
- 第 13–16 行:与版本 10 一样,我们使用 [Predis] 库和版本 9 中的 [dao] 层,别名为 [ServerDaoWithRedis];
- 第 25–29 行:我们验证确实是带有一个 URL 参数的 POST 请求。如果不是,则向主控制器返回错误结果,状态为 [301];
- 第 32–33 行:错误消息累积在数组 [$errors] 中。计数从 310 开始,每出现一个错误就加一;
- 第 35–44 行:我们检查参数 [married] 是否存在(缺失加 2),然后验证它的值是否在 [yes, no] 之中(否则加 4);
- 第 47–60 行:参数 [children] 和 [salary] 由同一个循环检查。被遍历的数组把每个参数与一对值关联起来,当该参数缺失或无效时,这对值会加到状态上:[children] 为 (8, 9),[salary] 为 (16, 17)。[[$missing, $invalid]] 的解包直接在 [foreach] 语句中完成。PHP 7 脚本把同样的代码写了两遍;
- 第 48–52 行:参数缺失;[continue] 语句转到下一个参数;
- 第 54–59 行:该值必须是至少一位数字的序列。如果是,就把它转换为整数并存入数组 [$values];
- 第 62–64 行:如果存在错误,就返回一个包含错误列表的结果;
- 第 65 行:参数有效,可以计算税额。为此,必须创建能够执行该计算的 [dao] 层和 [business] 层;
- 第 68–79 行:创建一个名为 [Redis] 的客户端,并立即与服务器建立连接。如果无法连接到 [Redis] 服务器,就返回状态为 [500 Internal Server Error] 、应用状态为 [350] 的结果;
- 第 81–98 行:构造 [dao] 层:
- 第 82 行:检查 [Redis] 服务器中是否存在键 [taxAdminData]。该键代表税务管理数据。如果键不存在,[get] 方法(来自 [Predis] )返回 [null] ;
- 第 85 行:键不存在;必须从数据库中获取税务数据。数据库描述文件的路径相对于应用程序的根目录,该根目录由 [ROOT_DIRECTORY] 这个常量确定,它由 [main.php] 定义;
- 第 86 行:从数据库获取的数据以其 JSON 字符串的形式,使用键 [Redis] [taxAdminData] 存入内存;
- 第 89–90 行:如果键 [taxAdminData] 存在于 [Redis] 内存中,就把税务数据直接传给 [dao] 层的构造函数;
- 第 92–94 行:如果数据库查询失败,就返回一个结果,其状态为 [500 Internal Server Error],应用状态为 [341],并包含 [dao] 层抛出的异常消息。PHP 7 课程的代码清单在这里显示的是状态 340,而它的源代码、配置(把状态 341 与税额计算视图相关联)和正文都使用 341。我们选择 341:状态 340 已经是带有三个无效 POST 参数的请求的状态(310 + 4 + 9 + 17);
- 第 95–98 行:[finally] 子句在所有情况下都会执行,无论是否发生异常,即使 [catch] 块以 [return] 结束也是如此。这里关闭的是与 [Redis] 服务器的连接;
- 第 100 行:创建 [business] 层并计算税额。结果是 [tax, surcharge, discount, reduction, rate] 数组;
- 第 102 行:根据计算结果创建一个 [Simulation] 对象。前三个参数是位置参数。然后运算符 [...] 展开关联数组 [$result]:从 PHP 8.1 开始,它的键成为命名参数——这里是 [tax, surcharge, discount, reduction, rate]——它们是构造函数最后几个参数的名称;
- 第 104 行:把刚刚构造的模拟添加到位于会话中的已计算模拟列表中。会话 [get] 方法的第二个参数是键不存在时返回的值:如果尚未执行任何模拟,则为空列表。新列表由展开旧列表、再加上新的模拟构成,然后写回会话;
- 第 106 行:把模拟返回给主控制器,状态为 [300];
- 第 111 行:DBMS 驱动程序的错误消息可能不是 UTF-8 编码的(见版本 8)。这时它就无法放入 JSON 字符串中。PHP 7 脚本使用 [utf8_encode] 函数,该函数自 PHP 8.2 起已被弃用;我们现在使用 [mb_convert_encoding]。
23.11.6. [curl] 测试
我们在用户已通过身份验证的情况下,以 JSON 模式测试 [CalculateTaxController] 控制器:
| > curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=calculate-tax"
{"action":"calculate-tax","status":301,"response":"you must use the [post] method with [action] in the URL and the posted parameters [married, children, salary]"}
> curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=calculate-tax" --data-urlencode "married=maybe" -d "children=x&salary=y"
{"action":"calculate-tax","status":340,"response":["invalid value [maybe] for parameter [married]","invalid value [x] for parameter [children]","invalid value [y] for parameter [salary]"]}
> curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=calculate-tax" -d "salary=y"
{"action":"calculate-tax","status":337,"response":["missing parameter [married]","missing parameter [children]","invalid value [y] for parameter [salary]"]}
> curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=calculate-tax" --data-urlencode "married=yes" -d "children=2&salary=55555"
{"action":"calculate-tax","status":300,"response":{"married":"yes","children":2,"salary":55555,"tax":2814,"surcharge":0,"discount":0,"reduction":0,"rate":0.14}}
> curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=calculate-tax" --data-urlencode "married=no" -d "children=3&salary=200000"
{"action":"calculate-tax","status":300,"response":{"married":"no","children":3,"salary":200000,"tax":58006,"surcharge":26649,"discount":0,"reduction":0,"rate":0.45}}
|
- 第 1–2 行:我们发出的是 GET 请求而不是 POST:状态 [301];
- 第 4–5 行:POST 请求,三个参数 [married, children, salary] 都存在但全部无效:状态 310 + 4 + 9 + 17 = 340;
- 第 7–8 行:只提交了参数 [salary] ,而且它也无效:状态 310 + 2 + 8 + 17 = 337;
- 第 10–11 行:使用有效参数进行税额计算:状态 [300]。结果是该模拟的 JSON 对象。这与 2019 年官方示例中,育有两个孩子、收入为 55,555 欧元的夫妇应缴税额 2,814 欧元相吻合;
- 第 13–14 行:第二次税额计算。
请注意,状态并不总是对应唯一的错误组合:8 + 17 = 9 + 16。状态 337 也对应于这样一种请求:缺少 [married] 和 [salary] ,并且 [children] 无效。错误消息列表则精确描述了这些错误。
现在我们来模拟 [Redis] 服务器故障。我们不关闭服务器,而是在 [config.json] 中指定一个没有任何服务器监听的端口:["port": 6380]。重新进行身份验证之后,计算请求返回如下响应:
| > curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=authenticate-user" -d "user=admin&password=admin"
{"action":"authenticate-user","status":200,"response":"Authentication successful [admin]"}
> curl -i -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=calculate-tax" --data-urlencode "married=yes" -d "children=2&salary=55555"
HTTP/1.0 500 Internal Server Error
Date: Thu, 01 Oct 2026 16:51:52 GMT
Server: Apache/2.4.58
X-Powered-By: PHP/8.5.11
Cache-Control: max-age=0, private, must-revalidate
Cache-Control: no-cache, private
Connection: close
Content-Type: application/json; charset=utf-8
{"action":"calculate-tax","status":350,"response":"[redis], Connection refused [tcp://127.0.0.1:6380]"}
|
- 第 5 行:状态 [500 Internal Server Error];
- 第 14 行:状态 [350] 以及 [Predis] 抛出的异常消息。
已向应用程序管理员发送了一封电子邮件:可以在 [Mailpit] 的 Web 界面(URL [http://localhost:8025])中看到。其主题为 [tax calculation server crash],正文包含发送给客户端的 JSON 响应。别忘了恢复端口 6379。
23.11.7. 动作 [list-simulations]
动作 [list-simulations] 由如下次级控制器 [ListSimulationsController] 处理:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// Symfony 依赖
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\Session\Session;
// 操作 [list-simulations]:返回会话的模拟列表
final class ListSimulationsController implements InterfaceController
{
#[\Override]
public function execute(array $config, Request $request, Session $session): ControllerResult
{
// 必须是 GET 请求,且 URL 中只有一个参数 [action]
if ($request->getMethod() !== "GET" || $request->query->count() !== 1) {
$message = "GET required, with the single parameter [action] in the URL";
return new ControllerResult(Response::HTTP_BAD_REQUEST, 501, $message);
}
// 会话的模拟列表(如果还没有则为空)
return new ControllerResult(Response::HTTP_OK, 500, $session->get("simulations", []));
}
}
|
说明
- [GET main.php?action=list-simulations] 请求;
- 第 20–23 行:验证是否为只带一个参数的 GET 请求。如果不是,则向主控制器返回错误结果,状态为 [501];
- 第 25 行:把会话中找到的模拟列表返回给主控制器——如果会话中没有模拟,则返回空列表——状态为 [500]。PHP 7 课程声明该类时没有写 [implements InterfaceController]:这是一处疏漏,在此已更正。
23.11.8. [curl] 测试
我们将运行两个测试,一个出错,一个成功:
| > curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=list-simulations¶m1=x"
{"action":"list-simulations","status":501,"response":"GET required, with the single parameter [action] in the URL"}
> curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=list-simulations"
{"action":"list-simulations","status":500,"response":[{"married":"yes","children":2,"salary":55555,"tax":2814,"surcharge":0,"discount":0,"reduction":0,"rate":0.14},{"married":"no","children":3,"salary":200000,"tax":58006,"surcharge":26649,"discount":0,"reduction":0,"rate":0.45}]}
|
- 第 1–2 行:URL 中带有多余 [param1] 参数的 GET 请求:状态 [501];
- 第 4–5 行:有效的查询:状态 [500]。响应是之前执行的两次模拟的 JSON 列表。
23.11.9. 动作 [delete-simulation]
动作 [delete-simulation] 由如下次级控制器 [DeleteSimulationController] 处理:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// Symfony 依赖
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\Session\Session;
// 操作 [delete-simulation]:从模拟列表中删除第 [number] 号模拟
final class DeleteSimulationController implements InterfaceController
{
#[\Override]
public function execute(array $config, Request $request, Session $session): ControllerResult
{
// 必须是 GET 请求,且 URL 中只有参数 [action, number]
if ($request->getMethod() !== "GET" || $request->query->count() !== 2) {
return self::error(602, "GET required, with the parameters [action, number]");
}
// [number] 参数必须存在
if (!$request->query->has("number")) {
return self::error(604, "missing parameter [number]");
}
// [number] 参数必须是整数 >= 0
$number = trim($request->query->getString("number"));
if (preg_match('/^\d+$/', $number) !== 1) {
return self::error(612, "invalid parameter [$number]");
}
// 第 [number] 号模拟必须存在:[number] 位于区间 [0, n-1] 内
$number = (int) $number;
$simulations = $session->get("simulations", []);
if ($number >= count($simulations)) {
return self::error(628, "simulation no. [$number] does not exist");
}
// 我们删除该模拟:[array_splice] 会对列表中后面的元素重新编号
array_splice($simulations, $number, 1);
// 我们把这些模拟放回会话
$session->set("simulations", $simulations);
// 我们返回新的模拟列表
return new ControllerResult(Response::HTTP_OK, 600, $simulations);
}
// 错误结果
private static function error(int $status, string $message): ControllerResult
{
return new ControllerResult(Response::HTTP_BAD_REQUEST, $status, $message);
}
}
|
说明
- 请求 [GET main.php?action=delete-simulation&number=x];
- 第 20–22 行:检查是否为带有两个参数的 GET 请求。否则状态为 [602];
- 第 24–26 行:检查参数 [number] 是否存在于 URL 参数中。否则状态为 [604];
- 第 28–31 行:检查参数 [number] 的值在语法上是否正确:正整数或零。否则状态为 [612];
- 第 33–37 行:验证编号为 [number] 的模拟确实存在:该编号必须在范围 [0, n-1] 内,其中 n 是会话中的模拟数量。否则状态为 [628]。由于编号不可能为负,只需验证它小于 n 即可。如果会话中没有模拟,则 n 为 0;
- 第 39 行:编号为 [number] 的模拟由函数 [array_splice] 删除,该函数从位置 [$number] 开始删除一个元素,并对后面的元素重新编号。PHP 7 脚本使用 [unset],它不会改变其他元素的键,随后再用 [array_values] 得到键为 [0, n-2] 的列表;
- 第 41 行:新的模拟数组被返回给会话;
- 第 43 行:把新的模拟列表返回给主控制器,状态为 [600];
- 第 47 行:一个构造错误结果的工具方法。错误状态与 PHP 7 脚本中的一致,该脚本随着检查的进行,依次在状态 600 上加 2、4、8、16 来计算它们。
23.11.10. [curl] 测试
我们将进行错误测试和成功测试:
| > curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=delete-simulation"
{"action":"delete-simulation","status":602,"response":"GET required, with the parameters [action, number]"}
> curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=delete-simulation¶m1=x"
{"action":"delete-simulation","status":604,"response":"missing parameter [number]"}
> curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=delete-simulation&number=x"
{"action":"delete-simulation","status":612,"response":"invalid parameter [x]"}
> curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=delete-simulation&number=100"
{"action":"delete-simulation","status":628,"response":"simulation no. [100] does not exist"}
> curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=delete-simulation&number=0"
{"action":"delete-simulation","status":600,"response":[{"married":"no","children":3,"salary":200000,"tax":58006,"surcharge":26649,"discount":0,"reduction":0,"rate":0.45}]}
> curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=delete-simulation&number=0"
{"action":"delete-simulation","status":600,"response":[]}
|
- 第 1–2 行:不带参数 [number] 的 GET 请求:状态 [602];
- 第 4–5 行:带有两个参数但没有 [number] 的 GET 请求:状态 [604];
- 第 7–8 行:编号在语法上不正确的请求:状态 [612];
- 第 10–11 行:模拟编号等于 100 的请求,该模拟不存在:状态 [628];
- 第 13–14 行:删除 0 号模拟,即列表中的第一个:状态 [600]。响应是新的列表,其中现在只剩第二个模拟;
- 第 16–17 行:重复该操作;会话中已没有模拟。
23.11.11. 动作 [end-session]
动作 [end-session] 由如下次级控制器 [EndSessionController] 处理:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// Symfony 依赖
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\Session\Session;
// 操作 [end-session]:结束模拟会话
final class EndSessionController implements InterfaceController
{
#[\Override]
public function execute(array $config, Request $request, Session $session): ControllerResult
{
// 必须是 GET 请求,且 URL 中只有一个参数 [action]
if ($request->getMethod() !== "GET" || $request->query->count() !== 1) {
$message = "GET required with the single parameter [action] in the URL";
return new ControllerResult(Response::HTTP_BAD_REQUEST, 401, $message);
}
// 我们保存会话类型
$type = $session->get("type");
// 我们使当前会话失效:其数据被删除,并开始一个新会话
$session->invalidate();
// 我们把类型放回新会话
$session->set("type", $type);
// 成功
return new ControllerResult(Response::HTTP_OK, 400, "session deleted");
}
}
|
说明
- 请求 [GET main.php?action=end-session];
- 第 20–23 行:验证该动作是否为只带单个参数 [action] 的 GET 请求。否则状态为 [401];
- 第 25 行:在会话结束之前,先保存会话类型([json, xml, html]);
- 第 27 行:当前会话失效。这会删除其中存储的数据,并以新的标识符启动一个新会话;
- 第 29 行:把上一个会话的类型恢复到新会话中。最终,我们重新开始一个只有唯一键 [type] 的新会话:用户需要重新进行身份验证;
- 第 31 行:把结果返回给主控制器,状态为 [400]。
23.11.12. [curl] 测试
我们将进行一个错误测试和一个成功测试:
| > curl -c cookies.txt -b cookies.txt -X POST "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=end-session"
{"action":"end-session","status":401,"response":"GET required with the single parameter [action] in the URL"}
> curl -i -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=end-session"
HTTP/1.0 200 OK
Date: Thu, 01 Oct 2026 16:51:52 GMT
Server: Apache/2.4.58
X-Powered-By: PHP/8.5.11
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: PHPSESSID=deleted; expires=Thu, 01 Jan 1970 00:00:01 GMT; Max-Age=0; path=/
Set-Cookie: PHPSESSID=c86e31f4c347e0952fdc18bd64ffabee; path=/
Cache-Control: no-cache, private
Connection: close
Content-Type: application/json; charset=utf-8
{"action":"end-session","status":400,"response":"session deleted"}
> curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=list-simulations"
{"action":"list-simulations","status":104,"response":["action requested by unauthenticated user"]}
|
- 第 1–2 行:我们使用 POST 而不是期望的 GET 来请求结束会话:状态 [401];
- 第 4–16 行:有效的 [end-session] 动作:状态 [400];
- 第 10–11 行:服务器发送两个 [Set-Cookie] 头。第一个指示客户端删除旧的会话 Cookie(其过期日期已过)。第二个向客户端提供新的会话 Cookie:一个新的 Web 会话开始了。我们已经看到,在同一个会话内,服务器在第一次响应之后就不再发送会话 Cookie;
- 第 18–19 行:在新会话中,用户不再处于已验证状态:状态 [104]。
23.12. 服务器响应类型
23.12.1. 简介
我们来回顾应用程序的整体架构:

现在我们来介绍可能的响应类型 [3a]。它们位于项目的 [Responses] 文件夹中。我们已经介绍过 [InterfaceResponse] 接口、父类 [ParentResponse],以及 [JsonResponse] 类。会话的响应类型由动作 [init-session] 设置,并存入会话中。它由 [ResponseType] 枚举表示,位于 [Entities] 文件夹中:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// 客户端可以通过 [init-session] 操作请求的响应类型
enum ResponseType: string
{
case Json = "json";
case Xml = "xml";
case Html = "html";
// 负责发送此类型响应的对象
public function response(): InterfaceResponse
{
return match ($this) {
self::Json => new JsonResponse(),
self::Xml => new XmlResponse(),
self::Html => new HtmlResponse(),
};
}
}
|
说明
- 第 11–13 行:三种响应类型。每个枚举项的值就是动作 [type] 参数 [init-session] 所期望的值;
- 第 16–23 行:[response] 方法返回负责发送此类响应的对象。返回类型是 [InterfaceResponse] 接口:调用代码只知道该接口的 [send] 方法。PHP 7 课程在配置文件中把每种类型与一个类名关联起来(键 [types]),并使用 [new $response()] 实例化它。
我们来回顾主控制器中请求向客户端发送响应的代码:
| // 响应的类型在会话中 - 如果尚未设置,默认为 JSON
$type = ResponseType::tryFrom($session->get("type", "")) ?? ResponseType::Json;
// 所请求类型的 [InterfaceResponse] 对象向客户端发送响应
$type->response()->send(
$request,
$session,
$config,
$result->statusCode,
$content,
$result->headers,
$logger
);
|
- 第 107 行:确定响应类型;
- 第 109 行:实例化相应的响应类,并使用其方法 [send($request, $session, $config, $statusCode, $content, $headers, $logger)] 把响应发送给客户端。
23.12.2. [JsonResponse] 类
已经介绍过。不过,我们再次给出它的代码,以便更好地突出这三个响应类之间的一致性:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// Symfony 依赖
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Session\Session;
// JSON 响应
final class JsonResponse extends ParentResponse
{
#[\Override]
public function send(
Request $request,
Session $session,
array $config,
int $statusCode,
array $content,
array $headers = [],
?Logger $logger = null
): void {
// JSON 序列化:[json_encode] 也会序列化 [Simulation] 对象的公共属性
$json = json_encode($content, self::JSON_OPTIONS);
// 由父类发送响应
$this->sendResponse($statusCode, $json, "application/json", $headers);
// 日志
$logger?->write("response=$json");
}
}
|
23.12.3. [XmlResponse] 类
[XmlResponse] 类如下:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// Symfony 依赖
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Session\Session;
// XML 响应
final class XmlResponse extends ParentResponse
{
#[\Override]
public function send(
Request $request,
Session $session,
array $config,
int $statusCode,
array $content,
array $headers = [],
?Logger $logger = null
): void {
// 用版本 11 的 [XmlUtilities] 类进行 XML 序列化
// [Simulation] 对象先被转换为关联数组
$xml = XmlUtilities::arrayToXml(self::toArray($content), "root");
// 由父类发送响应
$this->sendResponse($statusCode, $xml, "application/xml", $headers);
// JSON 日志,比 XML 更简洁
$this->log($logger, $content);
}
}
|
说明
- 第 27 行:响应 [$content] 由版本 11 中 [arrayToXml] 类 [XmlUtilities] 的方法序列化为 XML。该方法期望一个数组,其值要么是数组,要么是简单值:父类的 [toArray] 方法首先把 [Simulation] 对象替换为其属性的数组。文档的根元素命名为 [root],与 PHP 7 课程相同;
- 第 29 行:父类把响应发送给客户端,类型为 [application/xml];
- 第 31 行:响应以 JSON 形式记入日志,它比 XML 更简洁。
PHP 7 课程使用 [Symfony / Serializer] 库中的 XML 编码器,并使用第二个 JSON 编码器来记录日志。
23.12.4. [curl] 测试
我们已经用 JSON 运行了所有可能的错误测试,用 XML 无需再做其他事情。我们启动一个 XML 类型的新会话(文件 [cookies.txt] 已删除):
| > curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=init-session&type=xml"
<?xml version="1.0" encoding="UTF-8"?>
<root>
<action>init-session</action>
<status>700</status>
<response>session started with type [xml]</response>
</root>
> curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=authenticate-user" -d "user=admin&password=admin"
<?xml version="1.0" encoding="UTF-8"?>
<root>
<action>authenticate-user</action>
<status>200</status>
<response>Authentication successful [admin]</response>
</root>
> curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=calculate-tax" --data-urlencode "married=yes" -d "children=2&salary=55555"
<?xml version="1.0" encoding="UTF-8"?>
<root>
<action>calculate-tax</action>
<status>300</status>
<response>
<married>yes</married>
<children>2</children>
<salary>55555</salary>
<tax>2814</tax>
<surcharge>0</surcharge>
<discount>0</discount>
<reduction>0</reduction>
<rate>0.14</rate>
</response>
</root>
> curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=list-simulations"
<?xml version="1.0" encoding="UTF-8"?>
<root>
<action>list-simulations</action>
<status>500</status>
<response>
<item>
<married>yes</married>
<children>2</children>
<salary>55555</salary>
<tax>2814</tax>
<surcharge>0</surcharge>
<discount>0</discount>
<reduction>0</reduction>
<rate>0.14</rate>
</item>
</response>
</root>
> curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=calculate-tax" -d "children=x"
<?xml version="1.0" encoding="UTF-8"?>
<root>
<action>calculate-tax</action>
<status>337</status>
<response>
<item>missing parameter [married]</item>
<item>invalid value [x] for parameter [children]</item>
<item>missing parameter [salary]</item>
</response>
</root>
|
- 第 1–7 行:XML 会话启动请求,以及服务器的 XML 响应。从现在起,服务器的所有响应都将是 XML。之前用过的所有请求都可以原样重复使用,每个请求都会返回 XML 格式的响应;
- 第 9–15 行:成功的身份验证;
- 第 17–32 行:税额计算。元素 [response] 以子元素的形式包含模拟的各个属性;
- 第 34–51 行:模拟列表。每个模拟是 [item] 元素,位于 [response] 元素之中;
- 第 53–63 行:错误列表。每条错误消息是一个 [item] 元素。
23.12.5. [HtmlResponse] 响应
当会话类型为 [html] 时,会实例化一个 [HtmlResponse] 类型的对象来向客户端发送响应。该对象向客户端发送一个 HTML 文档,该文档取决于处理该动作的次级控制器所返回的状态码。这种映射 [status => view],在配置文件 [config.json] 中按如下方式填写:
| "views": {
"view-authentication.php": [700, 221, 400],
"view-tax-calculation.php": [200, 300, 341, 350, 800],
"view-simulations-list.php": [500, 600]
},
"view-errors": "view-errors.php"
|
该配置按如下方式解释:[‘view name' => ‘statuses associated with this view']:
- 第 56 行:如果次级控制器返回的状态属于数组 [700, 221, 400],则显示 [view-authentication.php] 视图;
- 第 57 行:如果次级控制器返回的状态属于数组 [200, 300, 341, 350, 800],则显示 [view-tax-calculation.php] 视图;
- 第 58 行:如果次级控制器返回的状态属于数组 [500, 600],则显示 [view-simulations-list.php] 视图;
- 第 60 行:如果次级控制器返回的状态不在上述任何数组中,则显示视图 [view-errors.php]。
视图包含在项目的 [Views] 文件夹中。[HtmlResponse] 类的代码如下:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// Symfony 依赖
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Session\Session;
// HTML 响应:[Views] 文件夹中的某个视图
final class HtmlResponse extends ParentResponse
{
#[\Override]
public function send(
Request $request,
Session $session,
array $config,
int $statusCode,
array $content,
array $headers = [],
?Logger $logger = null
): void {
// HTML 响应取决于控制器返回的状态码
$status = $content["status"];
// 视图对应一个状态:我们查找状态列表包含 [$status] 的第 1 个视图
// 如果没有合适的视图,那就是意外错误:我们显示错误视图
$view = array_find_key(
$config["views"],
fn(array $statuses): bool => in_array($status, $statuses, true)
) ?? $config["view-errors"];
// 我们执行视图:它写出的内容被放入缓冲区,而不是发送给客户端
// 视图可以访问该方法的变量 [$request, $session, $config, $content]
ob_start();
require __DIR__ . "/../Views/$view";
// 我们获取缓冲区的内容即 HTML 文档,并清空缓冲区
$html = ob_get_clean();
// 由父类发送响应
$this->sendResponse($statusCode, $html, "text/html", $headers);
// 控制器响应的 JSON 日志,不含 HTML
$this->log($logger, $content);
}
}
|
说明
- 第 26 行:要显示的视图取决于处理该动作的控制器所返回的状态码。该状态码位于 [$content["status"]] 中;
- 第 29–32 行:在应用程序配置中查找与该状态对应的视图。函数 [array_find_key](PHP 8.4)返回数组 [$config["views"]] 中第一个满足箭头函数所表达条件的元素的键——这里是其状态列表包含 [$status] 的第一个视图的名称。如果没有元素满足条件,它返回 [null]:这表明对 HTML 应用程序来说这是一个异常状态码,此时通过运算符 [??] 显示错误视图。PHP 7 脚本使用一个十五行的 [while] 循环来完成这一查找;
- 第 35–38 行:执行所选视图中的 PHP 代码,并把结果存入变量 [$html]。这段代码需要做一些解释。假设所选视图是 [view-authentication.php],它显示一个 Web 身份验证表单:
- 第 35 行:函数 [ob_start] 启动文档中所说的输出延迟。由 [print]、[echo] 操作写出的任何内容,或被包含脚本中的 HTML 文本——它们通常会立即发送给客户端——都会被放入输出缓冲区(ob),而不发送给客户端;
- 第 36 行:加载视图 [view-authentication.php];这是一个包含 PHP 代码的动态 HTML 视图。接着发生两件事。首先,执行视图中的 PHP 代码,结果是一个只包含 HTML,乃至 CSS 和 JavaScript,但不再包含 PHP 的页面。然后,这段 HTML 代码通常会被发送给客户端。事实上,PHP 解释器遇到的任何非 PHP 代码的文本都是如此。由于启用了输出延迟,这段
HTML 代码被放入输出缓冲区,而不会发送给客户端;
- 第 38 行:[ob_get_clean] 函数做两件事:它返回输出缓冲区的内容——也就是放入其中的 HTML 页面——并清空缓冲区、停止输出延迟。从客户端的角度看,就好像什么都没有发生:它仍然什么也没有收到;
- 视图由 [send] 方法包含:因此视图的代码可以访问该方法的局部变量,特别是它的参数 [$request]、[$session]、[$config],以及 [$content]。视图正是这样获得它需要显示的数据的;
- [__DIR__] 是当前正在运行的脚本所在文件夹的绝对路径,这里是 [Responses] 文件夹。因此,要找到视图,必须先上一级到 [..] ,然后进入 [Views] 文件夹;
- 第 40 行:父类把响应发送给客户端,类型为 [text/html];
- 第 42 行:处理当前动作的次级控制器所提供的响应 [$content] 以 JSON 形式记入日志,不包含 HTML。
23.12.6. [curl] 测试
要真正测试会话的 HTML 模式,我们需要检查所有视图。我们稍后再做。现在,我们只需验证:在一个新的 [init-session] 动作(状态 700)成功执行后,类型为 [html] 的新会话确实会产生 HTML 响应。根据配置文件,响应就是视图 [view-authentication.php] :
| > curl -D - -o view.html -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=init-session&type=html"
HTTP/1.0 200 OK
Date: Thu, 01 Oct 2026 16:51:53 GMT
Server: Apache/2.4.58
X-Powered-By: PHP/8.5.11
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: PHPSESSID=60bf588b0873f085af3b33940c0d8417; path=/
Cache-Control: no-cache, private
Vary: Accept-Encoding
Connection: close
Content-Type: text/html; charset=utf-8
|
- 第 1 行:选项 [-D -] 指示 [curl] 把响应的 HTTP 头写到标准输出([-] 文件),选项 [-o view.html] 把响应体写入 [view.html] 文件;
- 第 11 行:响应是一个 HTML 文档。
在浏览器中打开时,文件 [view.html] 显示身份验证视图,如下所示。
23.13. HTML Web 应用程序
23.13.1. 视图概览
HTML Web 应用程序使用四个视图。身份验证视图:

税额计算视图:

模拟列表视图:

意外错误视图:

这些视图使用 CSS 框架 [Bootstrap] 5.3 版。PHP 7 课程使用的是 4.1 版:一些 CSS 类已经变化或被移除;我们会在讲解过程中指出。我们将逐一介绍这些视图。
23.13.2. 身份验证视图
23.13.2.1. 视图概览
身份验证视图如下:

该视图由三个元素组成,我们称之为片段:
- 顶部横幅(含徽标和标题)由脚本 [v-banner.php] 生成;
- 身份验证表单由脚本 [v-authentication.php] 生成;
- 粉色错误框仅在有错误时显示,由脚本 [v-errors.php] 生成。
身份验证视图由如下页面 [view-authentication.php] 生成:
| <?php
// 身份验证视图 - 状态 [700, 221, 400]
// 我们继承了对此视图执行 [require] 的 [HtmlResponse::send] 方法的变量:
// Request $request:当前请求
// Session $session:应用程序的会话
// array $config:应用程序的配置
// array $content:控制器的响应 [action, status, response]
// Symfony 依赖
use Symfony\Component\HttpFoundation\Request;
// 我们计算视图的模型
$model = getModelForThisView($request, $content);
function getModelForThisView(Request $request, array $content): stdClass
{
// 模型取决于应用程序的状态
return match ($content["status"]) {
// 身份验证失败:我们重新显示输入的标识符和一条错误消息
221 => (object) [
"login" => $request->request->getString("user"),
"errorsTitle" => "The following errors occurred:",
"errors" => ["Authentication failed"],
],
// 700、400:空表单,没有错误
default => (object) ["login" => "", "errors" => []],
};
}
?>
<!doctype html>
<html lang="en">
<head>
<!-- 采用 UTF-8 编码的文档,占满屏幕的整个宽度 -->
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<!-- Bootstrap 5.3 -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/css/bootstrap.min.css"
integrity="sha384-sRIl4kxILFvY47J16cr9ZwB07vP4J8+LH7qKQnuqkuIAvNWLzeN8tE5YBujZqJLB" crossorigin="anonymous">
<title>Tax application</title>
</head>
<body>
<div class="container">
<!-- 横幅 -->
<?php require __DIR__ . "/v-banner.php" ?>
<!-- 占 9 列的身份验证表单 -->
<div class="row">
<div class="col-md-9">
<?php require __DIR__ . "/v-authentication.php" ?>
</div>
</div>
<!-- 如果有错误,我们将其显示在表单下方 -->
<?php if ($model->errors !== []): ?>
<div class="row">
<div class="col-md-9">
<?php require __DIR__ . "/v-errors.php" ?>
</div>
</div>
<?php endif ?>
</div>
</body>
</html>
|
说明
- 第 2–7 行:视图由 [require] 语句在 [HtmlResponse::send] 方法中执行。它继承该方法的变量;
- 第 13–28 行:视图的 PHP 部分计算视图模型。我们稍后再回到这一点;
- 第 30 行:HTML5 文档以这一行开头;
- 第 31–61 行:HTML 页面包含在 [<html>] 和 [</html>] 标签之间。[lang] 属性指定文档的语言;
- 第 32–40 行:HTML 文档的头部(head):
- 第 34 行:[<meta charset>] 标签表明文档采用 UTF-8 编码;
- 第 35 行:[<meta name="viewport">] 标签设置视图的初始显示方式:占满显示它的屏幕的整个宽度(width),并采用初始缩放比例(initial-scale)。PHP 7 版本中的 [shrink-to-fit=no] 值在当前浏览器中已不再使用;
- 第 37–38 行:[<link rel="stylesheet">] 标签指定控制视图外观的 CSS 文件。我们使用 CSS [Bootstrap] 5.3.8 框架,从 [jsDelivr] ([https://getbootstrap.com/docs/5.3/getting-started/introduction/])分发网络下载。[integrity] 属性包含文件的指纹:如果下载的文件与该指纹不匹配,浏览器就会拒绝它,从而保护页面免受分发网络上文件被篡改的影响;
- 第 39 行:[<title>] 标签设置页面标题,显示在浏览器标签页中;
- 第 41–60 行:网页的主体包含在 [<body>] 和 [</body>] 标签之间;
- 第 42 行:[<div>] 标签划定所显示页面的一个区域。视图中使用的 [class] 属性都指向 CSS Bootstrap 框架。[<div class="container">] 标签划定一个在页面上居中的 Bootstrap 容器;
- 第 44 行:包含 [v-banner.php] 片段,它生成页面头部。我们稍后会介绍它。路径使用 [__DIR__](即 [Views] 文件夹)构造:像 ["v-banner.php"] 这样的简单相对路径,会先在 [include_path] 指令(PHP)指定的目录中查找,然后才在调用脚本所在的文件夹([Responses])和当前文件夹中查找,这可能导致意想不到的结果;
- 第 46–47 行:[<div class="row">] 标签划定一个 Bootstrap 行。这些行由 12 列组成。[<div class="col-md-9">] 标签划定一个占 9 列的区域;
- 第 48 行:包含片段 [v-authentication.php],它显示身份验证表单;
- 第 52–58 行:如果模型的错误列表不为空,就包含片段 [v-errors.php],它在新的 Bootstrap 行中显示错误。这里我们使用 PHP 控制结构的替代语法 [if (...):] …… [endif],在 HTML 页面中它比花括号更易读。PHP 7 脚本使用 HTML 语法([heredoc])来书写错误代码([print <<<EOT ... EOT;])。
我们来记下这段代码中需要定义的动态元素:
- [$model->errors]:错误消息列表,没有错误时为空;
- [$model->errorsTitle]:位于错误列表之前的文本。
23.13.2.2. 片段 [v-banner.php]
片段 [v-banner.php] 在 Web 应用程序的所有视图上显示顶部横幅:
| <?php
// 片段:所有视图的顶部横幅
// 模型:[$model->logo](可选)- 徽标的 URL,相对于所显示页面的 URL
?>
<!-- 横幅:带圆角的浅灰色边框 -->
<div class="p-4 my-4 bg-body-tertiary rounded-3">
<div class="row align-items-center">
<div class="col-md-4">
<img src="<?= htmlspecialchars($model->logo ?? "Views/logo.jpg") ?>" alt="Cherry tree in bloom">
</div>
<div class="col-md-8">
<h1>Calculate your tax</h1>
</div>
</div>
</div>
|
说明
- 第 6 行:头部被包裹在一个区块中,其 Bootstrap 类提供内边距(p-4)、垂直外边距(my-4)、浅灰色背景(bg-body-tertiary)和圆角(rounded-3)。PHP 7 课程使用的是 Bootstrap 4 的类 [jumbotron],它在 Bootstrap 5 中已不存在:这四个类取代了它;
- 第 7 行:一个 Bootstrap 行。[align-items-center] 类使其各列的内容垂直居中;
- 第 8–10 行:一幅 [<img>] 图像被放在该行的前四列中;
- 第 9 行:语法 [<?= expression ?>] 等价于 [<?php echo expression ?>]。换句话说,[src] 属性的值将是该 PHP 表达式的值。它是:
- [$model->logo ?? "Views/logo.jpg"]:如果视图模型包含徽标,就是徽标的 URL;否则就是相对于 [Views/logo.jpg] 的 URL。应用程序中的所有 URL 都具有 [http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=…] 的形式:相对于 [Views/logo.jpg] 的 URL 由浏览器补全为所显示页面的路径,得到 [http://localhost/php8-oct-2026/scripts-web/tax/version-12/Views/logo.jpg]。PHP 7 的片段根据服务器变量([REQUEST_SCHEME]、[SERVER_NAME]、[SERVER_PORT]、[REQUEST_URI])和一个正则表达式构造徽标的绝对 URL:这是不必要的;
- [htmlspecialchars(...)]:函数 [htmlspecialchars] 把 HTML 中的特殊字符替换为相应的实体:[&] 变为 [&],[<] 变为 [<],[>] 变为 [>],["] 变为 ["],而 ['] 变为 [']。这样,写入页面的值就无法破坏 [src] 属性,也无法向页面中插入标签;
- 第 11–13 行:该行中的另外 8 列(注意总共有 12 列)用于以大号字体显示文本(标签 [<h1>])。
动态元素:[$model->logo],横幅中所显示图像的 URL(可选)。
写入 HTML 页面的任何动态值都必须经过 [htmlspecialchars]。这是针对 XSS(跨站脚本)攻击的防护:如果用户输入的值或来自不可信来源的值被原样写入页面,恶意用户就可以注入代码——例如 [<script>…</script>]——这些代码会被查看该页面的人的浏览器执行。PHP 7 不对任何值进行转义。从 PHP 8.1 开始,[htmlspecialchars] 的默认选项([ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401])也会对撇号进行编码:无论值是写在文本中,还是写在以引号或撇号界定的属性中,调用 [htmlspecialchars($value)] 都已足够。
23.13.2.3. 片段 [v-authentication.php]
片段 [v-authentication.php] 显示 Web 应用程序的身份验证表单:
| <?php
// 片段:身份验证表单
// 模型:[$model->login] - 要显示在 [user] 输入框中的标识符
?>
<!-- HTML 表单 - 其值随 [authenticate-user] 操作一起提交 -->
<form method="post" action="main.php?action=authenticate-user">
<!-- 蓝色背景的标题 -->
<div class="alert alert-primary" role="alert">
<h4>Please authenticate</h4>
</div>
<!-- 第 1 行:标识符 -->
<div class="row mb-3">
<!-- 占 3 列的标签 -->
<label for="user" class="col-md-3 col-form-label">User name</label>
<!-- 占 4 列的文本输入框 -->
<div class="col-md-4">
<input type="text" class="form-control" id="user" name="user"
placeholder="User name" value="<?= htmlspecialchars($model->login) ?>">
</div>
</div>
<!-- 第 2 行:密码 -->
<div class="row mb-3">
<label for="password" class="col-md-3 col-form-label">Password</label>
<!-- 隐藏的输入框 -->
<div class="col-md-4">
<input type="password" class="form-control" id="password" name="password"
placeholder="Password">
</div>
</div>
<!-- 第 3 行:[submit] 按钮 -->
<div class="row mb-3">
<div class="col-md-2">
<button type="submit" class="btn btn-primary">Submit</button>
</div>
</div>
</form>
|
说明
- 第 6–36 行:[<form>] 标签划定一个 HTML 表单。该表单通常具有以下特点:
- 它定义输入字段([<input>] 标签);
- 它有一个 [submit] 类型的按钮,把输入的值提交到 [action] 属性(位于 [<form>] 标签中)所指定的 URL。用于请求该 URL 的 HTTP 方法由 [method] 属性(位于 [<form>] 标签中)指定;
- 这里,当用户点击 [Submit] 按钮时,浏览器会把表单中输入的值提交到 URL [main.php?action=authenticate-user];
- 提交的值就是用户在两个输入字段中输入的值。它们将以 [user=xx&password=yy] 的形式提交。参数名 [user, password] 对应于输入字段的 [name] 属性;
- 第 8–10 行:一个 Bootstrap 区块,用于在蓝色背景上显示标题;
- 第 12–20 行:表单的第一行。类 [mb-3] 为该行添加下外边距。Bootstrap 4 使用类 [form-group],它在 Bootstrap 5 中已不存在;
- 第 14 行:标签,占三列。[for] 属性(位于 [<label>] 标签中)把标签与输入字段的 [id] 属性关联起来:点击标签会把光标置于输入字段中;
- 第 16 行:输入字段放在四列布局中;
- 第 17–18 行:HTML [<input>] 标签定义一个输入字段。它有几个属性:
- [type="text"]:这是一个文本输入字段。可以在其中输入任何内容;
- [class="form-control"]:输入字段的 Bootstrap 样式;
- [id="user"]:输入字段的 ID。该 ID 通常供 CSS 和 JavaScript 代码使用;
- [name="user"]:输入字段的名称。用户输入的值将由浏览器以该名称提交([user=xx]);
- [placeholder="prompt"]:用户尚未输入任何内容时,输入字段中显示的文本;
- [value="value"]:输入字段一出现在屏幕上、用户尚未输入任何内容时就显示的文本。出错时利用这一机制来显示导致错误的输入。这里,该值将是 [$model->login] 的值,并由 [htmlspecialchars] 转义:输入的标识中即使含有引号,也无法关闭 [value] 属性;
- 第 22–29 行:密码输入字段的类似代码。[type="password"] 属性创建一个文本输入字段,其中正在输入的字符会被隐藏;
- 第 31–35 行:用于 [Submit] 按钮的第三行;
- 第 33 行:由于它具有属性 [type="submit"],点击该按钮会触发浏览器把输入的值发送给服务器。CSS 类 [btn btn-primary] 显示一个蓝色按钮。
还有最后一点需要解释。[action="main.php?action=authenticate-user"] 属性(位于 [<form>] 标签中)定义了一个不完整的 URL(它不是以 http://machine:port/path 开头)。身份验证视图会通过不同的 URL 输入得到:
- [http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=init-session&type=html];
- [http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=authenticate-user]。
这些 URL 都指向一个 [main.php] 文档,它位于路径 [http://localhost/php8-oct-2026/scripts-web/tax/version-12] 下。本应用程序中的所有 URL 都是如此。发送输入的值时,URL [main.php?action=authenticate-user] 会加上该路径作为前缀。因此,这些值将被提交到 URL [http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=authenticate-user]。
23.13.2.4. [v-errors.php] 片段
片段 [v-errors.php] 显示错误消息列表。应用程序四个视图中的三个使用它:
| <?php
// 片段:粉色边框中的错误消息列表
// 模型:[$model->errorsTitle] - 引导文字,[$model->errors] - 消息
?>
<div class="alert alert-danger" role="alert">
<?= htmlspecialchars($model->errorsTitle) ?>
<ul class="mb-0">
<?php foreach ($model->errors as $error): ?>
<li><?= htmlspecialchars($error) ?></li>
<?php endforeach ?>
</ul>
</div>
|
- 第 5 行:错误显示在带有粉色背景的 Bootstrap 容器中;
- 第 6 行:引出错误的文本;
- 第 7–11 行:HTML [<ul>] 标签(无序列表)显示带项目符号的列表。每个列表项的语法为 [<li>item</li>]。类 [mb-0] 去掉列表的下外边距;
- 第 8–10 行:循环 [foreach] 的替代语法。每条消息都由 [htmlspecialchars] 转义:控制器的错误消息包含客户端发送的值([invalid value [x] for parameter [children]])。在 PHP 7 课程中,视图模型包含通过拼接字符串 [<li>$error</li>] 构造的 HTML 错误列表:包含 JavaScript 代码的 POST 提交值就会被浏览器执行。
动态元素:[$model->errorsTitle] 和 [$model->errors]。
23.13.2.5. 可视化测试
我们可以在把视图集成到应用程序之前很早就对它们进行测试。这里的目标是测试它们的视觉外观。我们把所有测试视图集中放在项目的 [Tests] 文件夹中。要测试 [view-authentication.php] 视图,需要创建它将显示的数据模型。脚本 [Tests/view-authentication.php] 如下:
| <?php
// 身份验证视图的可视化测试:用测试模型显示该视图
// 我们计算视图的模型
$model = getModelForThisView();
function getModelForThisView(): stdClass
{
return (object) [
// 用户的标识符
"login" => "albert",
// 错误列表 - 第 2 个用于检查特殊 HTML 字符已被中和
"errorsTitle" => "The following errors occurred:",
"errors" => ["error1", "<b>error2</b>"],
// 横幅的徽标,相对于此脚本的 URL
"logo" => "../Views/logo.jpg",
];
}
?>
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/css/bootstrap.min.css"
integrity="sha384-sRIl4kxILFvY47J16cr9ZwB07vP4J8+LH7qKQnuqkuIAvNWLzeN8tE5YBujZqJLB" crossorigin="anonymous">
<title>Tax application</title>
</head>
<body>
<div class="container">
<!-- 横幅 -->
<?php require __DIR__ . "/../Views/v-banner.php" ?>
<!-- 占 9 列的身份验证表单 -->
<div class="row">
<div class="col-md-9">
<?php require __DIR__ . "/../Views/v-authentication.php" ?>
</div>
</div>
<!-- 如果有错误,我们将其显示在表单下方 -->
<?php if ($model->errors !== []): ?>
<div class="row">
<div class="col-md-9">
<?php require __DIR__ . "/../Views/v-errors.php" ?>
</div>
</div>
<?php endif ?>
</div>
</body>
</html>
|
说明
- 第 5 行:身份验证视图包含由 [$model] 对象控制的动态部分。这个对象称为视图模型。根据 MVC 缩写词的两种定义之一,它就是 MVC 中的 M。它由函数 [getModelForThisView] 计算。在脚本顶层定义的函数,从脚本开始执行时就是已知的:可以在定义之前调用它;
- 第 9–17 行:视图模型是 PHP 的通用类 [stdClass] 类型的对象。这里通过 [(object)] 运算符把关联数组转换为对象来获得它:数组的键成为对象的属性。类型 [stdClass] 是唯一仍可以添加未声明属性的对象类型(见“类”一章)。使用关联数组同样可以达到相同的结果;
- 第 14 行:视图动态元素的测试值。第二条错误包含 HTML 标签:我们将验证它们被原样显示,而不会被浏览器解释;
- 第 16 行:徽标的 URL 相对于测试脚本的 URL,而测试脚本位于 [Tests] 文件夹中;
- 第 32 行:脚本的其余部分来自视图 [Views/view-authentication.php]。所包含的片段来自 [Views] 文件夹:它们就是被测试的片段。PHP 7 课程把它们的一个版本复制到了 [Tests] 文件夹中。
可视化测试通过在浏览器中请求 URL [http://localhost/php8-oct-2026/scripts-web/tax/version-12/Tests/view-authentication.php] 来进行:

请注意,第二条错误中的 [<b>] 标签被显示出来而没有被解释:针对 XSS 攻击的防护有效。继续这些可视化测试,直到对结果满意为止。调试期间,我们在 [VS Code] 中修改文件,然后刷新浏览器页面(F5)。
23.13.2.6. 计算视图模型
视图的视觉外观确定之后,就可以着手在真实条件下计算视图模型了。我们来回顾导向该视图的状态码,它们可以在配置文件中找到:
| "views": {
"view-authentication.php": [700, 221, 400],
"view-tax-calculation.php": [200, 300, 341, 350, 800],
"view-simulations-list.php": [500, 600]
},
"view-errors": "view-errors.php"
|
因此,状态码 [700, 221, 400] 会导致显示身份验证视图。要确定这些状态码的含义,可以参考针对 JSON 应用程序所做的 [curl] 测试:
- 700 是 [init-session] 动作成功之后的状态码:此时显示空白的身份验证表单;
- 221 是 [authenticate-user] 动作失败(凭据无法识别)之后的状态码:此时显示身份验证表单,以便更正凭据;
- 400 是 [end-session] 动作成功之后的状态码:此时显示空的身份验证表单。
现在我们知道了何时应显示身份验证表单,就可以在 [view-authentication.php] 中计算它的模型了:
| <?php
// 身份验证视图 - 状态 [700, 221, 400]
// 我们继承了对此视图执行 [require] 的 [HtmlResponse::send] 方法的变量:
// Request $request:当前请求
// Session $session:应用程序的会话
// array $config:应用程序的配置
// array $content:控制器的响应 [action, status, response]
// Symfony 依赖
use Symfony\Component\HttpFoundation\Request;
// 我们计算视图的模型
$model = getModelForThisView($request, $content);
function getModelForThisView(Request $request, array $content): stdClass
{
// 模型取决于应用程序的状态
return match ($content["status"]) {
// 身份验证失败:我们重新显示输入的标识符和一条错误消息
221 => (object) [
"login" => $request->request->getString("user"),
"errorsTitle" => "The following errors occurred:",
"errors" => ["Authentication failed"],
],
// 700、400:空表单,没有错误
default => (object) ["login" => "", "errors" => []],
};
}
?>
|
说明
- 第 3–7 行:我们声明从 [HtmlResponse::send] 方法继承的变量,该方法使用 [require] 渲染视图;
- 第 10 行:视图代码中使用的 Symfony 类。视图没有命名空间:如果没有这条语句,[Request] 将指代类 [\Request],而该类并不存在;
- 第 15–28 行:[getModelForThisView] 函数计算视图模型。它接收来自控制器的请求和响应——这是它所需要的全部数据。视图没有 [declare(strict_types=1)] 声明:它们是带有一些 PHP 代码的 HTML 页面;
- 第 18–27 行:模型取决于处理当前动作的控制器所返回的状态码:
- 第 20–23 行:身份验证失败时:重新显示用户输入的用户名(可在 POST 提交的参数 [$request->request] 中找到),并显示一条错误消息。然后用户可以再次尝试身份验证;
- 第 26 行:状态码 700 和 400:空白的身份验证表单,没有错误。
脚本 PHP 7 使用了一条修改函数开头所创建对象的语句。
23.13.2.7. [curl] 测试
我们已经有了能产生 [700, 221, 400] 状态码的查询,它们会显示身份验证视图。只需在 [html] 类型的会话中重用它们,并检查它们是否正确显示了身份验证视图。我们在上一段打开的 HTML 会话中,使用用户 [x, x] 进行身份验证:
| > curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=authenticate-user" -d "user=x&password=x"
<!doctype html>
<html lang="en">
<head>
<!-- UTF-8 encoded document, displayed over the full width of the screen -->
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<!-- Bootstrap 5.3 -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/css/bootstrap.min.css"
integrity="sha384-sRIl4kxILFvY47J16cr9ZwB07vP4J8+LH7qKQnuqkuIAvNWLzeN8tE5YBujZqJLB" crossorigin="anonymous">
<title>Tax application</title>
</head>
<body>
<div class="container">
<!-- banner -->
<!-- banner: a light grey frame with rounded corners -->
<div class="p-4 my-4 bg-body-tertiary rounded-3">
<div class="row align-items-center">
<div class="col-md-4">
<img src="Views/logo.jpg" alt="Cherry tree in bloom">
</div>
<div class="col-md-8">
<h1>Calculate your tax</h1>
</div>
</div>
</div>
<!-- authentication form on 9 columns -->
<div class="row">
<div class="col-md-9">
<!-- HTML form - its values are posted with the [authenticate-user] action -->
<form method="post" action="main.php?action=authenticate-user">
<!-- title on a blue background -->
<div class="alert alert-primary" role="alert">
<h4>Please authenticate</h4>
</div>
<!-- 1st row: the identifier -->
<div class="row mb-3">
<!-- label on 3 columns -->
<label for="user" class="col-md-3 col-form-label">User name</label>
<!-- text input field on 4 columns -->
<div class="col-md-4">
<input type="text" class="form-control" id="user" name="user"
placeholder="User name" value="x">
</div>
</div>
<!-- 2nd row: the password -->
<div class="row mb-3">
<label for="password" class="col-md-3 col-form-label">Password</label>
<!-- hidden input field -->
<div class="col-md-4">
<input type="password" class="form-control" id="password" name="password"
placeholder="Password">
</div>
</div>
<!-- 3rd row: [submit] button -->
<div class="row mb-3">
<div class="col-md-2">
<button type="submit" class="btn btn-primary">Submit</button>
</div>
</div>
</form>
</div>
</div>
<!-- if there are errors, we display them below the form -->
<div class="row">
<div class="col-md-9">
<div class="alert alert-danger" role="alert">
The following errors occurred: <ul class="mb-0">
<li>Authentication failed</li>
</ul>
</div>
</div>
</div>
</div>
</body>
</html>
|
- 第 1 行:请求发送字符串 [user=x&password=x];
- 第 42–43 行:错误的用户被再次显示;
- 第 67–71 行:显示一条错误消息,由 [htmlspecialchars] 转义。
在浏览器中,显示如下视图:

23.13.2.8. 结论
我们无需编写其他视图,就能测试视图 [view-authentication.php] 。之所以能做到这一点,是因为:
- 所有控制器都已编写完成;
- [curl] 使我们无需视图就能向服务器发送请求。编写控制器时,你必须意识到任何人都可以这样做。因此必须做好准备,处理任何视图都不会允许的请求。这些请求是用 [curl] 手工创建的。绝不要先验地假定“这个请求不可能出现”,必须对其进行验证。
23.13.3. 税额计算视图
23.13.3.1. 视图概览
税额计算视图如下:

该视图有五个部分:
- 顶部横幅由片段 [v-banner.php] 生成,该片段已经介绍过;
- 税额计算表单由片段 [v-tax-calculation.php] 生成;
- 带有两个链接的菜单由片段 [v-menu.php] 生成;
- 计算结果显示在绿色框中;
- 错误由片段 [v-errors.php] 显示在粉色框中。
在应用程序中,绿色框和粉色框绝不会同时显示:上面的屏幕截图来自视图的可视化测试,稍后介绍。税额计算视图由如下脚本 [view-tax-calculation.php] 生成,目前我们只展示其中的 HTML 部分:
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/css/bootstrap.min.css"
integrity="sha384-sRIl4kxILFvY47J16cr9ZwB07vP4J8+LH7qKQnuqkuIAvNWLzeN8tE5YBujZqJLB" crossorigin="anonymous">
<title>Tax application</title>
</head>
<body>
<div class="container">
<!-- 横幅 -->
<?php require __DIR__ . "/v-banner.php" ?>
<!-- 两列的行:菜单占 3 列,表单占 9 列 -->
<div class="row">
<div class="col-md-3">
<?php require __DIR__ . "/v-menu.php" ?>
</div>
<div class="col-md-9">
<?php require __DIR__ . "/v-tax-calculation.php" ?>
</div>
</div>
<!-- 成功:计算结果显示在表单下方的绿色边框中 -->
<?php if ($model->results !== []): ?>
<div class="row">
<div class="col-md-9 offset-md-3">
<div class="alert alert-success" role="alert">
<?php foreach ($model->results as $line): ?>
<?= htmlspecialchars($line) ?><br>
<?php endforeach ?>
</div>
</div>
</div>
<?php endif ?>
<!-- 失败:错误消息显示在表单下方的粉色边框中 -->
<?php if ($model->errors !== []): ?>
<div class="row">
<div class="col-md-9 offset-md-3">
<?php require __DIR__ . "/v-errors.php" ?>
</div>
</div>
<?php endif ?>
</div>
</body>
</html>
|
说明
我们只对新增的内容进行说明:
- 第 57 行:引入视图的顶部横幅;
- 第 60–62 行:引入菜单,它将占据头部之后那一行 Bootstrap 行中的三列;
- 第 63–65 行:引入税额计算表单,它将占据这一行中剩余的九列;
- 第 68–78 行:如果税额计算成功,列表 [$model->results] 就不为空,并且计算结果显示在绿色框中(类 [alert-success])。结果的每一行后面都有一个换行([<br>])。该框位于新的 Bootstrap 行上,占九列,并偏移三列(类 [offset-md-3])。因此它会紧挨着出现在税额计算表单下方。PHP 7 脚本使用一个空列 [<div class="col-md-3"></div>] 来实现偏移;
- 第 80–86 行:如果税额计算失败,列表 [$model->errors] 就不为空,错误由片段 [v-errors.php] 显示在同一位置的粉色框中。
23.13.3.2. 片段 [v-tax-calculation.php]
片段 [v-tax-calculation.php] 显示税额计算表单:
| <?php
// 片段:税款计算表单
// 模型:[$model->married] (yes / no)、[$model->children]、[$model->salary] - 显示的值
?>
<!-- 随 [calculate-tax] 操作提交的 HTML 表单 -->
<form method="post" action="main.php?action=calculate-tax">
<!-- 蓝色背景的标题 -->
<div class="alert alert-primary" role="alert">
<h4>Fill in the form below and then submit it</h4>
</div>
<!-- 第 1 行:婚姻状况,属于同一 [married] 组的两个单选按钮 -->
<fieldset class="row mb-3">
<legend class="col-form-label col-md-4 pt-0">Are you married or in a civil partnership?</legend>
<div class="col-md-5">
<div class="form-check">
<input class="form-check-input" type="radio" name="married" id="marriedYes" value="yes"
<?= $model->married === "yes" ? "checked" : "" ?>>
<label class="form-check-label" for="marriedYes">Yes</label>
</div>
<div class="form-check">
<input class="form-check-input" type="radio" name="married" id="marriedNo" value="no"
<?= $model->married === "yes" ? "" : "checked" ?>>
<label class="form-check-label" for="marriedNo">No</label>
</div>
</div>
</fieldset>
<!-- 第 2 行:子女数,整数 >= 0 -->
<div class="row mb-3">
<label for="children" class="col-md-4 col-form-label">Number of dependent children</label>
<div class="col-md-5">
<input type="number" min="0" step="1" class="form-control" id="children" name="children"
placeholder="Number of dependent children" value="<?= htmlspecialchars($model->children) ?>">
</div>
</div>
<!-- 第 3 行:年薪,整数 >= 0 -->
<div class="row mb-3">
<label for="salary" class="col-md-4 col-form-label">Annual salary</label>
<div class="col-md-5">
<input type="number" min="0" step="1" class="form-control" id="salary" name="salary"
placeholder="Annual salary" aria-describedby="salaryHelp"
value="<?= htmlspecialchars($model->salary) ?>">
<div id="salaryHelp" class="form-text">Round down to the nearest euro</div>
</div>
</div>
<!-- 第 4 行:[submit] 按钮 -->
<div class="row mb-3">
<div class="col-md-5">
<button type="submit" class="btn btn-primary">Submit</button>
</div>
</div>
</form>
|
说明
- 第 6 行:HTML 表单将被提交(属性 [method])到 URL [main.php?action=calculate-tax](属性 [action])。提交的值将是各输入字段的值:
- 所选单选按钮的值,形式为 [married=yes](如果选中 [Yes] 单选按钮),或 [married=no](如果选中 [No] 单选按钮)。[married] 是这两个单选按钮的 [name] 属性的值,[yes] 和 [no] 则是 它们的 [value] 属性的值;
- 数值输入字段 [children] 的值,形式为 [children=xx],其中 [xx] 是用户通过键盘输入的值;
- 数值输入字段 [salary] 的值,形式为 [salary=xx];
- 最终,提交的值将具有 [married=xx&children=yy&salary=zz] 的形式;
- 当用户点击第 48 行标有 [Submit] 的按钮时,输入的值将被提交;
- 第 12–26 行:两个单选按钮。[<fieldset>] 标签把表单元素分组在一起,[<legend>] 标签为它们提供标题;
- 第 16–21 行:由于有 [type="radio"] 属性,它们是单选按钮。这两个单选按钮属于同一个单选按钮组,因为它们共用同一个 [name] 属性。浏览器确保在一组单选按钮中,任何时刻只有一个被选中。因此,点击其中一个会取消之前被选中的那个;
- 第 17–22 行:显示表单时,必须有一个单选按钮处于选中状态;为此,只需添加 [checked] 属性到相应的 [<input type="radio">] 标签上即可。三元运算符在 [Yes] 按钮上设置该属性(如果 [$model->married] 等于 [yes]);否则就在 [No] 按钮上设置。由于所写入的值是常量,因此无需转义。PHP 7 课程在模型中插入了两个变量 [checkedYes] 和 [checkedNo],其中包含文本 [checked="checked"] 或空字符串;
- 第 31–32 行:一个数值输入字段([type="number"]),最小值为 0([min="0"])。在现代浏览器中,这意味着用户只能输入大于或等于 0 的数。也可以通过滑块输入,点击滑块可以增大或减小该值。属性 [step="1"] 表示滑块以 1 为增量变化:滑块只接受从 0 到 n、步长为 1 的整数值。对于手动输入,这意味着不接受带小数的数。在某些视图中,孩子数量输入字段必须预先填入该字段上一次输入的值:这就是属性 [value] 的作用,其值由 [$model->children] 提供;
- 第 39–42 行:薪资输入的说明与孩子数量输入相同。输入字段下方的提示文字具有类 [form-text];Bootstrap 4 使用的是标签 [<small>]。
动态元素:[$model->married], [$model->children], [$model->salary]。
该片段在税额计算表单的左侧显示一个菜单。其代码如下:
| <?php
// 片段:应用程序的菜单
// 模型:[$model->menuOptions] - 数组 [链接文字 => 目标 URL]
?>
<!-- Bootstrap 菜单:垂直的链接列表 -->
<nav class="nav flex-column">
<?php foreach ($model->menuOptions as $text => $url): ?>
<a class="nav-link" href="<?= htmlspecialchars($url) ?>"><?= htmlspecialchars($text) ?></a>
<?php endforeach ?>
</nav>
|
说明
- 第 6–10 行:HTML [<nav>] 标签包围文档中包含指向其他文档的导航链接的部分。[nav, flex-column, nav-link] 类是定义菜单外观的 Bootstrap 类:一个垂直的链接列表;
- 第 7 行:该片段的 [$model->menuOptions] 模型是一个形如 [["List of simulations" => "main.php?action=list-simulations", "End of session" => "main.php?action=end-session"]] 的数组;
- 第 8 行:HTML [<a>] 标签引入一个导航链接。[$url] 是点击 [$text] 链接时所导航到的 URL。随后浏览器执行 [GET $url] 操作。如果 [$url] 是相对 URL,就会用浏览器当前显示的 URL 的路径对其补全。因此,当浏览器当前的 URL 形如 [http://path/main.php?parameters] 时,[List of simulations] 链接指向 [http://path/main.php?action=list-simulations]。文本和 URL 都由 [htmlspecialchars] 转义:在 URL 中,用于分隔参数的字符 [&] 在 HTML 文档中必须写成 [&] 。
23.13.3.4. 可视化测试
我们在文件夹 [Tests] 中为视图 [view-tax-calculation.php] 创建一个测试脚本:
| <?php
// 税款计算视图的可视化测试:用测试模型显示该视图
// 我们计算视图的模型
$model = getModelForThisView();
function getModelForThisView(): stdClass
{
return (object) [
// 表单
"married" => "no",
"children" => "2",
"salary" => "300000",
// 成功消息
"results" => [
"Tax amount: 1000 euros",
"Discount: 15 euros",
"Reduction: 20 euros",
"Surcharge: 0 euros",
"Tax rate: 14 %",
],
// 错误消息
"errorsTitle" => "The following error occurred:",
"errors" => ["error1", "error2"],
// 菜单
"menuOptions" => [
"List of simulations" => "main.php?action=list-simulations",
"End of session" => "main.php?action=end-session",
],
// 横幅的徽标
"logo" => "../Views/logo.jpg",
];
}
?>
|
说明
- 第 9–32 行:我们初始化 [view-tax-calculation.php] 视图以及片段 [v-banner.php]、[v-tax-calculation.php]、[v-menu.php] 和 [v-errors.php] 的所有动态部分;
- 第 15–21 行:包含计算结果的各行;
- 第 24 行:同时显示一个错误列表,以便查看两个框。
我们通过请求 URL [http://localhost/php8-oct-2026/scripts-web/tax/version-12/Tests/view-tax-calculation.php] 来测试 [view-tax-calculation.php] 视图。我们会得到本段开头所示的结果。我们继续调整该视图,直到对视觉效果满意为止。然后就可以着手把该视图集成到当前正在开发的 Web 应用程序中。
23.13.3.5. 计算视图模型
视图的视觉外观确定之后,就可以着手在真实条件下计算视图模型了。导向该视图的状态码就是配置中的 [200, 300, 341, 350, 800] 这些码。要确定这些状态码的含义,可以参考针对 JSON 应用程序所做的 [curl] 测试:
- 200 是 [authenticate-user] 动作成功之后的状态码:此时显示空白的税额计算表单;
- 300 是 [calculate-tax] 动作成功之后的状态码。此时显示带有所输入数据和税额的计算表单。用户随后可以再进行一次计算;
- 341 是使用有效参数进行税额计算时,因无法连接 DBMS 而导致错误所返回的状态码;
- 350 是使用有效参数进行税额计算时,因无法连接 [Redis] 服务器而导致错误所返回的状态码;
- 状态码 800 稍后讨论。我们还没有遇到过它;
- 这里我们假定用户使用的是现代浏览器。因此,对于所讨论的表单,在 [children, salary] 输入字段中不可能输入负数、非数字字符串或小数。如果这些错误仍然发生(在手工构造的请求中),它们将被视为意外错误:此时将显示视图 [view-errors.php]。
现在我们知道了何时应显示税额计算表单,就可以在 [view-tax-calculation.php] 中定义它的模型了:
| <?php
// 税款计算视图 - 状态 [200, 300, 341, 350, 800]
// 我们继承 [HtmlResponse::send] 方法的变量 [$request, $session, $config, $content]
// Symfony 依赖
use Symfony\Component\HttpFoundation\Request;
// 我们计算视图的模型
$model = getModelForThisView($request, $content);
function getModelForThisView(Request $request, array $content): stdClass
{
$model = new stdClass();
// 应用程序状态
$status = $content["status"];
// 表单:为空 (200, 800) 或以输入的值还原 (300, 341, 350)
$entered = in_array($status, [300, 341, 350], true);
$model->married = $entered ? $request->request->getString("married") : "no";
$model->children = $entered ? $request->request->getString("children") : "";
$model->salary = $entered ? $request->request->getString("salary") : "";
// 计算成功 (300):控制器的响应是一个 [Simulation] 对象
$model->results = [];
if ($status === 300) {
$simulation = $content["response"];
$model->results = [
"Tax amount: $simulation->tax euros",
"Discount: $simulation->discount euros",
"Reduction: $simulation->reduction euros",
"Surcharge: $simulation->surcharge euros",
"Tax rate: " . $simulation->rate * 100 . " %",
];
}
// 计算失败(341:数据库不可用,350:Redis 不可用)
$model->errorsTitle = "The following error occurred:";
$model->errors = in_array($status, [341, 350], true) ? [$content["response"]] : [];
// 菜单
$model->menuOptions = [
"List of simulations" => "main.php?action=list-simulations",
"End of session" => "main.php?action=end-session",
];
// 我们返回模型
return $model;
}
?>
|
说明
- 第 17 行:对于状态 300、341 和 350,表单会带着所输入的值重新显示;
- 第 18–20 行:所输入的值位于 POST 提交的参数 [$request->request] 中。对于状态 200 和 800,表单为空,并选中 [No] 按钮;
- 第 23–32 行:税额计算成功。来自 [$content["response"]] 控制器的响应是一个 [Simulation] 对象:结果各行根据它的属性构造。税率以百分比显示。由于模拟是一个对象,[$simulation->tax] 被直接插值到以引号括起的字符串中;
- 第 35 行:由于数据库或服务器([Redis])不可用而导致税额计算失败的情形。此时控制器的响应就是错误消息;
- 第 37–40 行:两个菜单选项。
23.13.3.6. [curl] 测试
返回状态 300 的查询让我们能够查看成功的税额计算。在浏览器中,身份验证成功后,填写表单并提交:

我们来试一个错误场景:由于 [Redis] 服务器不可用而产生错误 350([config.json] 中的端口 6380):

请注意,表单已带着所输入的值重新显示。
23.13.4. 模拟列表视图
23.13.4.1. 视图概览
显示模拟列表的视图如下:

由脚本 [view-simulations-list.php] 生成的视图有三个部分:
- 顶部横幅,由片段 [v-banner.php] 生成,该片段已经介绍过;
- 带有两个链接的菜单,由片段 [v-menu.php] 生成,该片段已经介绍过;
- 模拟表格,由片段 [v-simulations-list.php] 生成。
[view-simulations-list.php] 脚本的 HTML 部分如下:
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/css/bootstrap.min.css"
integrity="sha384-sRIl4kxILFvY47J16cr9ZwB07vP4J8+LH7qKQnuqkuIAvNWLzeN8tE5YBujZqJLB" crossorigin="anonymous">
<title>Tax application</title>
</head>
<body>
<div class="container">
<!-- 横幅 -->
<?php require __DIR__ . "/v-banner.php" ?>
<!-- 两列的行:菜单占 3 列,模拟列表占 9 列 -->
<div class="row">
<div class="col-md-3">
<?php require __DIR__ . "/v-menu.php" ?>
</div>
<div class="col-md-9">
<?php require __DIR__ . "/v-simulations-list.php" ?>
</div>
</div>
</div>
</body>
</html>
|
- 第 33 行:引入应用程序横幅;
- 第 37 行:引入菜单。它将显示在横幅下方的三列中;
- 第 40 行:引入模拟表格。它将显示在横幅下方、菜单右侧的九列中。
片段 [v-simulations-list.php] 如下:
| <?php
// 片段:模拟表
// 模型:[$model->simulations] - 要显示的 [Simulation] 对象列表
?>
<!-- 蓝色背景的标题 -->
<div class="alert alert-primary" role="alert">
<h4>List of your simulations</h4>
</div>
<!-- 模拟表 -->
<table class="table table-sm table-hover table-striped">
<!-- 表格十列的表头 -->
<thead>
<tr>
<th scope="col">#</th>
<th scope="col">Married</th>
<th scope="col">Number of children</th>
<th scope="col">Annual salary</th>
<th scope="col">Tax amount</th>
<th scope="col">Surcharge</th>
<th scope="col">Discount</th>
<th scope="col">Reduction</th>
<th scope="col">Rate</th>
<th scope="col"></th>
</tr>
</thead>
<!-- 表格主体:每个模拟一行 -->
<tbody>
<?php foreach ($model->simulations as $i => $simulation): ?>
<tr>
<!-- 模拟编号是该行的表头 -->
<th scope="row"><?= $i ?></th>
<td><?= htmlspecialchars($simulation->married) ?></td>
<td><?= $simulation->children ?></td>
<td><?= $simulation->salary ?></td>
<td><?= $simulation->tax ?></td>
<td><?= $simulation->surcharge ?></td>
<td><?= $simulation->discount ?></td>
<td><?= $simulation->reduction ?></td>
<td><?= $simulation->rate ?></td>
<!-- 删除第 $i 号模拟的链接 -->
<td><a href="<?= htmlspecialchars("main.php?action=delete-simulation&number=$i") ?>">Delete</a></td>
</tr>
<?php endforeach ?>
</tbody>
</table>
|
说明
- 第 10–45 行:使用 [<table>] 标签创建一个 HTML 表格。Bootstrap 类赋予它紧凑的外观(table-sm)、鼠标悬停时高亮显示的行(table-hover)以及交替的行颜色(table-striped);
- 第 12–25 行:表格的列标题定义在
***[<thead>]***(表头)标签中。***[<tr>] (表行)标签定义一行。[<th>] 标签(表格标题)定义一个列标题。共有十个。[scope="col"] 表示该标题作用于列。[scope="row"]* 表示该标题作用于行;
- 第 27–44 行:[<tbody>] 标签包围表格所显示的数据;
- 第 28 行:模拟列表位于 [$model->simulations] 模型中。它是一个 [Simulation] 对象的列表:[$i] 是模拟在列表中的编号;
- 第 29–42 行:[<tr>] 标签包围表格的一行;
- 第 31 行:[<th scope="row">] 标签定义行标题,即模拟编号;
- 第 32–39 行:每个 [<td>] 标签定义该行中的一列。只有婚姻状况——一个字符串——被转义:模拟的其他属性都是数字,在 [Simulation] 类中被声明为相应类型,不可能包含 HTML 的特殊字符;
- 第 41 行:删除该模拟的链接。URL [main.php?action=delete-simulation&number=$i] 取自表格第一列中显示的编号。
23.13.4.2. 可视化测试
我们在 [view-simulations-list.php] 视图的 [Tests] 文件夹中创建一个测试脚本:
| <?php
// 模拟列表视图的可视化测试:用测试模型显示该视图
// 应用程序的 [Simulation] 类
require_once __DIR__ . "/../Entities/Simulation.php";
use Application\Simulation;
// 我们计算视图的模型
$model = getModelForThisView();
function getModelForThisView(): stdClass
{
return (object) [
// 两个模拟(命名参数)
"simulations" => [
new Simulation(married: "yes", children: 2, salary: 60000, tax: 448,
surcharge: 0, discount: 100, reduction: 20, rate: 0.14),
new Simulation(married: "no", children: 2, salary: 200000, tax: 25600,
surcharge: 8400, discount: 0, reduction: 0, rate: 0.45),
],
// 菜单
"menuOptions" => [
"Tax calculation" => "main.php?action=display-tax-calculation",
"End of session" => "main.php?action=end-session",
],
// 横幅的徽标
"logo" => "../Views/logo.jpg",
];
}
?>
|
说明
- 第 5–7 行:测试模型包含 [Simulation] 对象:我们加载该类并导入其完整名称;
- 第 16–21 行:HTML 表格所显示的两个模拟。它们使用命名参数(PHP 8.0)构造:每个参数的名称写在其值之前,这样即使不知道构造函数参数的顺序,代码也易于阅读;
- 第 23–26 行:菜单选项的数组。
使用 URL [http://localhost/php8-oct-2026/scripts-web/tax/version-12/Tests/view-simulations-list.php] 请求的可视化测试,会产生本段开头所示的结果。
23.13.4.3. 计算视图模型
导向模拟视图的状态码就是配置中的 [500, 600] 这些码:
- 500 是 [list-simulations] 动作成功之后的状态码:此时显示用户已执行的模拟列表;
- 600 是 [delete-simulation] 动作成功之后的状态码。此时显示删除之后得到的新模拟列表。
在这两种情况下,控制器的响应都是模拟列表。视图模型在 [view-simulations-list.php] 中计算:
| <?php
// 模拟列表视图 - 状态 [500, 600]
// 我们继承 [HtmlResponse::send] 方法的变量 [$request, $session, $config, $content]
// 我们计算视图的模型
$model = getModelForThisView($content);
function getModelForThisView(array $content): stdClass
{
return (object) [
// 模拟列表:控制器的响应是一个 [Simulation] 对象列表
"simulations" => $content["response"],
// 菜单
"menuOptions" => [
"Tax calculation" => "main.php?action=display-tax-calculation",
"End of session" => "main.php?action=end-session",
],
];
}
?>
|
- 第 12 行:[$model->simulations] 模型被 [v-simulations-list.php] 片段使用,它就是控制器返回的 [Simulation] 对象列表。PHP 7 脚本使用类 [Simulation] 的 getter 把每个对象转换为关联数组:有了公共属性,这就没有必要了;
- 第 14–17 行:[$model->menuOptions] 模型被 [v-menu.php] 片段使用。[Tax calculation] 链接使用 [display-tax-calculation] 动作,我们稍后就会实现它。
23.13.4.4. [curl] 测试
动作 [list-simulations] (状态 500)显示在 HTML 会话中执行的模拟列表。在浏览器中,进行两次税额计算之后,点击菜单中的 [List of simulations] 链接:

点击 0 号模拟的 [Delete] 链接(状态 600),会显示少了一个模拟的模拟列表:

23.13.5. 查看意外错误
这里,意外错误是指在正常使用 Web 应用程序时不应发生的错误。我们以如下请求为例,在 JSON 会话中:
| > curl -c cookies.txt -b cookies.txt "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=calculate-tax" -d "salary=y"
{"action":"calculate-tax","status":337,"response":["missing parameter [married]","missing parameter [children]","invalid value [y] for parameter [salary]"]}
|
缺少参数 [married] 和 [children] ,并且参数 [salary] 无效。然而,在 Web 应用程序的 HTML 表单中,这种情况不可能出现:
- 所有参数都存在;
- 参数 [married] 的值来自两个单选按钮的 [value] 属性,它必须是 [yes] 或 [no];
- 使用现代浏览器时,[<input type="number" min="0" step="1" …>] 属性确保孩子数量和薪资的输入必然是 >= 0 的整数。
然而,没有什么能阻止用户在 HTML 会话期间向我们的服务器发送这样的请求——使用 [curl] 或其浏览器的开发者工具。我们把任何不应在 HTML 应用程序中出现的错误称为“意外错误”。如果它确实出现,很可能是有人在试图“黑”这个应用程序。出于教学目的,我们决定在这些情况下显示一个错误页面。实际上,我们也可以重新显示最近一次发送给客户端的页面。为此,只需把最近发送的 HTML 响应存入会话。遇到意外错误时,就返回这个响应。这样,由于所显示的页面没有变化,用户会觉得服务器没有对其错误作出响应。
23.13.5.1. 视图概览
显示意外错误的视图如下:

由脚本 [view-errors.php] 生成的视图有三个部分:
- 顶部横幅,由片段 [v-banner.php] 生成;
- 带有三个链接的菜单,由片段 [v-menu.php] 生成;
- 意外错误,由片段 [v-errors.php] 显示。
[view-errors.php] 脚本的 HTML 部分如下:
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/css/bootstrap.min.css"
integrity="sha384-sRIl4kxILFvY47J16cr9ZwB07vP4J8+LH7qKQnuqkuIAvNWLzeN8tE5YBujZqJLB" crossorigin="anonymous">
<title>Tax application</title>
</head>
<body>
<div class="container">
<!-- 横幅 -->
<?php require __DIR__ . "/v-banner.php" ?>
<!-- 两列的行:菜单占 3 列,错误占 9 列 -->
<div class="row">
<div class="col-md-3">
<?php require __DIR__ . "/v-menu.php" ?>
</div>
<div class="col-md-9">
<?php require __DIR__ . "/v-errors.php" ?>
</div>
</div>
</div>
</body>
</html>
|
- 第 36 行:引入应用程序横幅;
- 第 40 行:引入菜单,位于横幅下方的三列中;
- 第 43 行:使用已介绍过的片段 [v-errors.php] 在九列中显示错误。
23.13.5.2. 可视化测试
我们在 [view-errors.php] 视图的 [Tests] 文件夹中创建一个测试脚本:
| <?php
// 意外错误视图的可视化测试:用测试模型显示该视图
// 我们计算视图的模型
$model = getModelForThisView();
function getModelForThisView(): stdClass
{
return (object) [
// 意外错误的数组
"errorsTitle" => "The following unexpected errors occurred:",
"errors" => ["error1", "error2"],
// 菜单
"menuOptions" => [
"Tax calculation" => "main.php?action=display-tax-calculation",
"List of simulations" => "main.php?action=list-simulations",
"End of session" => "main.php?action=end-session",
],
// 横幅的徽标
"logo" => "../Views/logo.jpg",
];
}
?>
|
- 第 12 行:意外错误列表;
- 第 14–18 行:三个菜单选项的数组。
使用 URL [http://localhost/php8-oct-2026/scripts-web/tax/version-12/Tests/view-errors.php] 请求的可视化测试,会产生本段开头所示的结果。
23.13.5.3. 视图模型的计算
配置文件的 [views] 键中缺失的状态码会导致显示意外错误视图。[view-errors.php] 中计算视图模型的代码如下:
| <?php
// 意外错误视图 - 配置的 [views] 键中没有的所有状态
// 我们继承 [HtmlResponse::send] 方法的变量 [$request, $session, $config, $content]
// 我们计算视图的模型
$model = getModelForThisView($content);
function getModelForThisView(array $content): stdClass
{
// 控制器的响应:一条错误消息或一个消息列表
$response = $content["response"];
return (object) [
"errorsTitle" => "The following unexpected errors occurred:",
"errors" => is_array($response) ? $response : [$response],
// 菜单
"menuOptions" => [
"Tax calculation" => "main.php?action=display-tax-calculation",
"List of simulations" => "main.php?action=list-simulations",
"End of session" => "main.php?action=end-session",
],
];
}
?>
|
- 第 11 行:从控制器的响应中获取错误;
- 第 14 行:根据控制器和错误的不同,响应要么是单条消息,要么是消息列表。[$model->errors] 模型被 [v-errors.php] 片段使用,它始终是一个列表;
- 第 16–20 行:[$model->menuOptions] 模型被 [v-menu.php] 片段使用。
23.13.5.4. [curl] 测试
要得到状态 338——它不是 HTML 应用程序所期望的状态——必须提交一个手工构造的请求:缺少 [married]、孩子数量无效且薪资无效。在 HTML 会话中使用 [curl] 会得到意外错误视图。在浏览器中,也可以使用开发者工具(F12)构造这样的表单。得到如下页面:

23.13.6. 实现应用程序的菜单动作
这里我们讨论菜单动作的实现。我们来回顾已遇到的各个链接的含义:
视图 | 链接 | 目标 | 作用 |
税额计算 | [List of simulations] | [main.php?action=list-simulations] | 请求模拟列表 |
税额计算 | [End of session] | [main.php?action=end-session] | 请求结束会话 |
模拟列表 | [Tax calculation] | [main.php?action=display-tax-calculation] | 显示税额计算视图 |
模拟列表 | [End of session] | [main.php?action=end-session] | 请求结束会话 |
意外错误 | [Tax calculation] | [main.php?action=display-tax-calculation] | 显示税额计算视图 |
意外错误 | [List of simulations] | [main.php?action=list-simulations] | 请求模拟列表 |
意外错误 | [End of session] | [main.php?action=end-session] | 请求结束会话 |
请注意,点击链接会对链接的目标发出 GET 请求。[list-simulations, end-session] 动作是通过 GET 操作实现的,因此我们可以把它们用作链接目标。当动作通过 POST 执行时,除非结合 JavaScript,否则就无法再使用链接。
从上面列出的动作可以看出,[display-tax-calculation] 动作尚未实现。这是两个视图之间的导航操作:JSON 或 XML 服务器没有理由实现它,因为它们没有视图的概念。是 HTML 服务器引入了这一概念。因此我们需要实现动作 [display-tax-calculation]。这让我们可以回顾在服务器中实现一个动作的步骤:
- 我们向 [Action] 枚举中添加一个枚举项:[case DisplayTaxCalculation = "display-tax-calculation";];
- 我们把次级控制器 [DisplayTaxCalculationController] 写入 [Controllers] 文件夹;
- 把它的文件添加到 [dependencies] 键中,该键位于 [config.json] 文件里;
- 把分支 [Action::DisplayTaxCalculation => new DisplayTaxCalculationController()] 添加到主控制器的 [match] 表达式中;
- 把控制器返回的状态码 800 与税额计算视图关联起来,写在 [views] 键中 ,该键位于 [config.json] 中。
[DisplayTaxCalculationController] 控制器如下:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// Symfony 依赖
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\Session\Session;
// 操作 [display-tax-calculation]:导航到税款计算视图(HTML 应用程序)
final class DisplayTaxCalculationController implements InterfaceController
{
#[\Override]
public function execute(array $config, Request $request, Session $session): ControllerResult
{
// 视图切换:我们只返回与目标视图关联的状态码
return new ControllerResult(Response::HTTP_OK, 800, "");
}
}
|
- 第 14 行:与其他次级控制器一样,新的控制器实现 [InterfaceController] 接口;
- 第 20 行:视图切换很容易实现:只需设置与目标视图关联的状态码——这里是代码 800。视图切换不会导致错误。
23.13.7. 真实场景测试
代码已经写好,每个动作都已用 [curl] 测试过。我们还需要在真实场景中测试视图流程。我们需要一种初始化 HTML 会话的方法。我们知道,需要向服务器发送参数 [action=init-session&type=html]。为了避免把它们输入浏览器地址栏,我们向应用程序中添加脚本 [index.php] :
| <?php
declare(strict_types=1);
// 在 [html] 模式下重定向(代码 302)到 [main.php]
header("Location: main.php?action=init-session&type=html");
|
- 第 6 行:[header] 是一个向响应添加 HTTP 头的函数。HTTP 头 [Location: main.php?action=init-session&type=html] 指示客户端浏览器重定向到指定的 URL。随后 PHP 把响应状态设置为 [302 Found]。
通过 URL [index.php] 脚本来请求 [http://localhost/php8-oct-2026/scripts-web/tax/version-12/index.php] scripts。当客户端浏览器收到 指向相对 URL [main.php?action=init-session&type=html] 的重定向时,它会请求绝对 URL [http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php?action=init-session&type=html],HTML 会话随之开始。
启动 URL 可以简化为 [http://localhost/php8-oct-2026/scripts-web/tax/version-12/]。如果 URL 中没有指定文档,[Apache] 就使用该文件夹中的 [index.html] 或 [index.php] 文档。因此在这里将使用脚本 [index.php] 。我们用 [curl] 来验证:
| > curl -i http://localhost/php8-oct-2026/scripts-web/tax/version-12/
HTTP/1.1 302 Found
Date: Thu, 01 Oct 2026 16:51:53 GMT
Server: Apache/2.4.58
X-Powered-By: PHP/8.5.11
Location: main.php?action=init-session&type=html
Content-Length: 0
Content-Type: text/html; charset=UTF-8
|
- 第 2 行:HTTP 代码 [302] 是重定向代码:它告诉客户端所请求的 URL 已被移走;
- 第 6 行:新的 URL 由头 [Location] 指定。浏览器会通过一个新的 GET 请求跟随这一重定向。[curl] 只有在指定了 [-L] 选项时才会这样做。
在浏览器中,开发者工具(F12,[Network] 选项卡)会显示这两个请求:第一个收到 302 响应,第二个显示身份验证页面。我们开始吧:现在介绍几个视图序列。我们来请求 URL [http://localhost/php8-oct-2026/scripts-web/tax/version-12/] 对应的视图:

浏览器显示的地址是重定向后的 URL [main.php?action=init-session&type=html]。我们来填写收到的表单:

提交之后,出现税额计算界面(状态 200):

我们来运行几次模拟:


我们来请求模拟列表:

我们来删除第一个模拟:

我们通过链接 [Tax calculation] (状态 800)返回税额计算视图:

我们通过链接 [End of session] 结束会话:回到身份验证界面(状态 400):

最后,下面是一个简短会话(JSON:init-session、authenticate-user、calculate-tax)的 [Data/logs.txt] 日志:
| 01/10/26 18:51:53.156 : ---new request
01/10/26 18:51:53.156 : action [init-session] requested
01/10/26 18:51:53.156 : controller : Application\InitSessionController
01/10/26 18:51:53.156 : response={"action":"init-session","status":700,"response":"session started with type [json]"}
01/10/26 18:51:53.166 : ---new request
01/10/26 18:51:53.166 : action [authenticate-user] requested
01/10/26 18:51:53.166 : controller : Application\AuthenticateUserController
01/10/26 18:51:53.167 : response={"action":"authenticate-user","status":200,"response":"Authentication successful [admin]"}
01/10/26 18:51:53.178 : ---new request
01/10/26 18:51:53.178 : action [calculate-tax] requested
01/10/26 18:51:53.178 : controller : Application\CalculateTaxController
01/10/26 18:51:53.179 : response={"action":"calculate-tax","status":300,"response":{"married":"yes","children":2,"salary":55555,"tax":2814,"surcharge":0,"discount":0,"reduction":0,"rate":0.14}}
|
对于每个请求,无论会话类型如何,都会记录所请求的动作、处理它的控制器以及 JSON 格式的响应。建议读者自行进行更多测试。
23.14. JSON Web 服务客户端
23.14.1. 客户端/服务器架构

我们现在来关注 Web 服务 [B] 的 JSON 客户端 [A]。客户端 [A]与 Web 服务 [B] 一样,具有分层结构:

这一架构体现在 [scripts-console/tax/version-12] 文件夹中的如下代码组织方式上:
| scripts-console/tax/version-12
├── Business
│ ├── ClientBusiness.php
│ └── InterfaceClientBusiness.php
├── Dao
│ ├── ClientDao.php
│ └── InterfaceClientDao.php
├── Data
│ ├── config.json
│ ├── errors.json
│ ├── results.json
│ └── taxpayersdata.json
├── Main
│ └── main.php
└── Tests
└── ClientBusinessTest.php
|
客户端使用的其他类已经讨论和讲解过。与之前的客户端一样,它们从其编写所在的文件夹中加载:
类 | 作用和来源 |
TaxException | 应用程序的异常类。版本 5,文件夹 [Entities] |
TaxPayerData | 纳税人的数据 [married, children, salary]。版本 5,文件 [Entities] |
Utilities | 读写 JSON 文件。版本 5,文件夹 [Utilities] |
TraitDao | 方法 [getTaxPayersData] 和 [saveResults] 的实现。版本 5,文件夹 [Dao] |
Simulation | 税额计算模拟。版本 12 服务器,文件夹 [Entities] |
客户端使用服务器的 [Simulation] 类:这是服务器发送模拟所采用的格式,而这个带有公共属性的 [readonly] 类对客户端和服务器都适用。PHP 7 的类 [BaseEntity](PHP 7 的客户端类 [Simulation] 曾派生自它)已不复存在。
23.14.2. [dao] 层

23.14.2.1. 接口
[dao] 层的接口如下:[Dao/InterfaceClientDao.php]:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// 版本 12 的 JSON Web 服务客户端的 [dao] 层接口
// 出错时所有方法都会抛出 [TaxException] 异常
interface InterfaceClientDao
{
// 读取纳税人数据(由 trait [TraitDao] 实现)
/** @return TaxPayerData[] */
public function getTaxPayersData(string $taxPayersFilename, string $errorsFilename): array;
// 保存结果(由 trait [TraitDao] 实现)
/** @param Simulation[] $simulations */
public function saveResults(string $resultsFilename, array $simulations): void;
// 操作 [init-session]:开始 json、xml 或 html 类型的会话
public function initSession(string $type = "json"): void;
// 操作 [authenticate-user]
public function authenticateUser(string $user, #[\SensitiveParameter] string $password): void;
// 操作 [calculate-tax]:计算纳税人的税款
public function calculateTax(string $married, int $children, int $salary): Simulation;
// 操作 [list-simulations]:会话的模拟列表
/** @return Simulation[] */
public function listSimulations(): array;
// 操作 [delete-simulation]:返回新的模拟列表
/** @return Simulation[] */
public function deleteSimulation(int $number): array;
// 操作 [end-session]
public function endSession(): void;
}
|
说明
- 第 14 行:[getTaxPayersData] 方法用于处理包含纳税人数据的 JSON 文件。该方法由版本 5 中的 [TraitDao] trait 实现;
- 第 18 行:[saveResults] 方法允许你把多次税额计算的结果保存到 JSON 文件中。该方法同样由 trait [TraitDao] 实现。这个 trait 把工作委托给方法 [Utilities::writeJsonFile],它可以根据公共属性把任何对象转换为 JSON:之前的版本中是 [TaxPayerData] 对象,这里是 [Simulation] 对象;
- 第 21–38 行:为 Web 服务接受的每一个动作都创建了一个方法,唯独 [display-tax-calculation] 动作除外,它只供 HTML 应用程序使用;
- 第 24 行:[SensitiveParameter] 属性(注解)(PHP 8.2),我们已经遇到过:如果在方法执行期间抛出异常,密码的值不会出现在调用跟踪中;
- 文档注释(PHPDoc)[@return Simulation[]],和 [@param Simulation[] $simulations] 指明了数组的内容。PHP 无法确定数组内容的类型:类型 [array] 并未指明元素是 [Simulation] 对象。这些注释把这一信息传达给 [VS Code] 编辑器(PHP Intelephense 扩展),这样它在遍历数组时就可以提示 [Simulation] 的属性。
23.14.2.2. 实现
[InterfaceClientDao] 接口由如下 [ClientDao] 类实现:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// Symfony 依赖
use Symfony\Component\HttpClient\HttpClient;
use Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface;
use Symfony\Contracts\HttpClient\HttpClientInterface;
use Symfony\Contracts\HttpClient\ResponseInterface;
// 版本 12 的 JSON Web 服务客户端的 [dao] 层
// 服务器的每个操作对应一个方法;会话通过会话 Cookie 维持
class ClientDao implements InterfaceClientDao
{
// 版本 5 的 trait 实现了接口的 [getTaxPayersData] 和 [saveResults] 方法
use TraitDao;
// HTTP 客户端
private readonly HttpClientInterface $httpClient;
// 会话 Cookie(在服务器发送它之前为 null)
private ?string $sessionCookie = null;
// 构造函数
// $urlServer:JSON Web 服务的 URL
// $httpClientOptions:HTTP 客户端的选项(verify_peer、verify_host……)
// $verbose:如果为 true,则在控制台显示服务器的响应
public function __construct(
private readonly string $urlServer,
array $httpClientOptions = [],
private readonly bool $verbose = true,
) {
$this->httpClient = HttpClient::create($httpClientOptions);
}
|
说明
- 第 19 行:该类使用 [TraitDao] trait,它实现了接口的两个方法:
- [getTaxPayersData(string $taxPayersFilename, string $errorsFilename): array];
- [saveResults(string $resultsFilename, array $simulations): void];
- 第 22 行:Symfony 的
HTTP 客户端只在构造函数中创建一次,并用于所有请求。PHP 客户端过去在每个方法中都创建一个新的 HTTP 客户端;
- 第 24 行:会话 Cookie。它的作用已在版本 9 的客户端中介绍过。在服务器发送它之前,它被设为 [null] ;
- 第 30–34 行:构造函数接收三个参数,其中两个被提升为属性:
- JSON Web 服务的 URL [$urlServer] ;
- HTTP 客户端的 [$httpClientOptions] 选项。它们来自配置文件:与版本 11 一样,这些是 [verify_peer] 和 [verify_host] 选项,如果服务器的 URL 使用 [https] 协议,这些选项允许使用 [Laragon] 的自签名证书;
- 一个布尔值 [$verbose] ,当它被设为 [true] 时,表示该类应在控制台上显示服务器的响应。
[initSession] 方法
[initSession] 方法的实现如下:
| // 操作 [init-session]:它必须是向服务器请求的第 1 个操作
#[\Override]
public function initSession(string $type = "json"): void
{
// GET main.php?action=init-session&type=json - 响应是一条简单消息
$this->sendRequest("GET", ["action" => "init-session", "type" => $type]);
}
|
由于动作 [init-session] 是向 Web 服务请求的第一个动作,方法 [initSession] 将是 [dao] 层中第一个被调用的方法。
说明
- 第 40 行:所需的会话类型作为参数传入。如果没有提供参数,则启动 JSON 会话。JSON 客户端可以请求 XML 会话:它将收到版本 11 的 XML 响应,而它无法处理这些响应;
- 第 43 行:向 Web 服务发送 GET 请求。它的两个参数放在 URL 中:[main.php?action=init-session&type=json]。服务器的响应(一条简单消息)不做处理。如果 HTTP 响应码不是 200 OK,私有方法 [sendRequest] 会抛出异常。
PHP 7 客户端在它的每个方法中都重复以下步骤:创建 HTTP 客户端、准备请求选项(包括会话 Cookie)、调用方法 [getResponse]。我们把这些工作提取到私有方法 [sendRequest] 中。
[sendRequest] 方法
| // 向服务器发送请求并使用其响应
// $method:GET 或 POST
// $query:URL 的参数
// $body:提交的参数(仅限 POST)
// 返回服务器 JSON 响应的 [response] 元素
private function sendRequest(string $method, array $query, array $body = []): mixed
{
// 请求的选项
$options = ["query" => $query];
if ($body !== []) {
// 提交的参数以 [param1=v1¶m2=v2...] 的形式发送
$options["body"] = $body;
}
if ($this->sessionCookie !== null) {
// 我们把服务器发给我们的会话 Cookie 发回给服务器
$options["headers"] = ["Cookie" => $this->sessionCookie];
}
// 我们发出请求 - 响应要到 [getResponse] 才会真正被读取
$response = $this->httpClient->request($method, $this->urlServer, $options);
// 我们使用响应
return $this->getResponse($response);
}
|
说明
- 第 51 行:该方法接收请求的 HTTP 方法(GET 或 POST)、URL 参数,以及(对于 POST)提交的参数。[$body] 参数是可选的;其默认值是空数组;
- 第 54 行:Symfony HTTP 客户端的 [query] 选项包含 URL 参数。Symfony 会自行对它们编码;
- 第 57 行:当 [body] 选项是数组时,Symfony 以 [param1=v1¶m2=v2…] 的形式发送提交的参数,并带有头 [Content-Type: application/x-www-form-urlencoded],就像浏览器提交表单时那样;
- 第 59–61 行:从第二个请求开始,我们把服务器发给我们的会话 Cookie 再发回给服务器。服务器就是这样取回客户端的会话的;
- 第 64 行:请求已准备好。Symfony 的 HTTP 客户端是异步的:只有当我们请求响应的状态、头或内容时,请求才会真正发送、响应才会被读取,这正是 [getResponse] 方法所做的;
- 第 66 行:返回服务器响应中的 [response] 元素。
[getResponse] 方法
[getResponse] 方法负责处理 Web 服务的响应:
| // 使用服务器的响应
// 返回 JSON 响应 {"action": ..., "status": ..., "response": ...} 的 [response] 元素
private function getResponse(ResponseInterface $response): mixed
{
try {
// 响应的状态、头部和 JSON 文档,即使出错也是如此(参数 false)
$statusCode = $response->getStatusCode();
$headers = $response->getHeaders(false);
$json = $response->getContent(false);
} catch (TransportExceptionInterface $ex) {
// 无法连接到服务器
throw new TaxException("Error communicating with the server ({$ex->getMessage()})", 40, $ex);
}
// 日志
if ($this->verbose) {
print "$json\n";
}
// 会话 Cookie:我们保留服务器发送的最后一个
// ([end-session] 操作会删除旧 Cookie 并发送一个新的)
foreach ($headers["set-cookie"] ?? [] as $cookie) {
if (preg_match('/^PHPSESSID=([^;]+)/', $cookie, $fields) === 1) {
$this->sessionCookie = "PHPSESSID=$fields[1]";
}
}
// 解码 JSON 响应
try {
$array = json_decode($json, true, flags: JSON_THROW_ON_ERROR);
} catch (\JsonException) {
$array = null;
}
if (!is_array($array) || !array_key_exists("response", $array)) {
throw new TaxException("Invalid server response [$json]", 41);
}
// 出错?
if ($statusCode !== 200) {
// 异常的消息是服务器的响应,并补充其 HTTP 状态
$message = json_encode(
["HTTP status" => $statusCode] + $array,
JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR
);
throw new TaxException($message, 42);
}
// 我们返回响应中有用的元素
return $array["response"];
}
|
说明
- 第 71 行:该方法是私有的。它的参数类型是 [ResponseInterface],这是 Symfony HTTP 客户端所有响应实现的接口。PHP 7 的客户端使用类型 [CurlResponse],即 HTTP 客户端使用 [curl] 库实现时的响应类:[dao] 层就不必要地依赖于 Symfony 所选的实现;
- 第 73–80 行:获取响应的状态、头和内容。[false] 参数可防止在响应的 HTTP 状态落在 [3xx, 4xx, 5xx] 范围内时 Symfony 抛出异常。如果无法连接服务器,Symfony 会抛出 [TransportExceptionInterface] 异常,它被转换为状态码为 40 的 [TaxException] 异常,与之前的版本一样;
- 第 83–84 行:如果处于 [$verbose] 模式,则在控制台上显示服务器的响应;
- 第 88–90 行:我们获取会话 Cookie。PHP 7 客户端只在 [initSession] 方法中这样做。我们在每个请求之后都这样做,因为版本 12 的服务器会在 [end-session] 动作期间更换会话 Cookie:它发送两个头,第一个用于删除旧 Cookie([PHPSESSID=deleted]),第二个用于新 Cookie。循环保留最后一个。正则表达式 [/^PHPSESSID=([^;]+)/] 捕获 Cookie 的值,直到第一个分号为止,分号把值与 Cookie 的属性(路径、过期时间等)分隔开;
- 第 95 行:把 JSON 字符串解析为数组。如果该字符串不是有效的 JSON,选项 [JSON_THROW_ON_ERROR] 会导致抛出 [JsonException] 异常;
- 第 99–100 行:如果响应不是带有键 [response] 的 JSON 对象,那它就不是来自我们 Web 服务的响应。抛出代码为 41 的异常;
- 第 103–109 行:如果服务器响应的 HTTP 状态不是 200,就抛出代码为 42 的异常;异常消息是服务器的 JSON 响应,并像之前的客户端一样补充上 HTTP 状态。运算符 [+] 作用于两个关联数组时会合并它们:数组 [["HTTP status" => $statusCode]] 中会填入来自 [action, status, response] 数组 [$array] 的键;
- 第 112 行:相关信息位于 [$array["response"]] 中。根据动作的不同,它是一条消息、一个关联数组(一次模拟),或一个关联数组列表(多次模拟)。因此该方法的返回类型是 [mixed]。
[authenticateUser] 方法
[authenticateUser] 方法如下:
| // 操作 [authenticate-user]
#[\Override]
public function authenticateUser(string $user, #[\SensitiveParameter] string $password): void
{
// POST main.php?action=authenticate-user,提交参数 [user, password]
$this->sendRequest(
"POST",
["action" => "authenticate-user"],
["user" => $user, "password" => $password]
);
}
|
说明
- 第 121 行:客户端的请求是 POST;
- 第 122 行:URL 的唯一参数;
- 第 123 行:POST 的参数;
- 不处理响应:我们知道,出错时(HTTP 代码不是 200),[getResponse] 方法本身就会抛出异常。
[calculateTax] 方法
| // 操作 [calculate-tax]
#[\Override]
public function calculateTax(string $married, int $children, int $salary): Simulation
{
// POST main.php?action=calculate-tax,提交参数 [married, children, salary]
$serverResponse = $this->sendRequest(
"POST",
["action" => "calculate-tax"],
["married" => $married, "children" => $children, "salary" => $salary]
);
// 响应是一个模拟的属性数组
return self::toSimulation($serverResponse);
}
|
说明
- 第 134 行:URL 的唯一参数;
- 第 135 行:POST 的三个参数;
- 第 138 行:如果执行到这里,就意味着 [getResponse] 方法没有抛出异常。响应是一次模拟各属性的关联数组。稍后介绍的 [toSimulation] 方法把它转换为 [Simulation] 对象。
[listSimulations] 方法
| // 操作 [list-simulations]
#[\Override]
public function listSimulations(): array
{
// GET main.php?action=list-simulations
$serverResponse = $this->sendRequest("GET", ["action" => "list-simulations"]);
// 响应是一个模拟列表
return self::getSimulations($serverResponse);
}
|
说明
- 第 146 行:带有唯一参数 [action] 的 GET 请求;
- 第 148 行:把响应转换为 [Simulation] 对象列表的工作由私有方法 [getSimulations] 完成。
[getSimulations] 方法
| // 将从服务器收到的关联数组列表转换为 [Simulation] 对象列表
/** @return Simulation[] */
private static function getSimulations(array $serverResponse): array
{
return array_map(self::toSimulation(...), $serverResponse);
}
// 将关联数组 [married, children, salary, tax, ...] 转换为 [Simulation] 对象
private static function toSimulation(array $attributes): Simulation
{
// 数组的键是 [Simulation] 构造函数参数的名称
return new Simulation(...$attributes);
}
|
说明
- 第 153 行:该方法接收服务器的响应,即一个关联数组列表,其中每个数组包含一次模拟的全部属性。它不使用任何对象属性:它是静态的,通过 [self::getSimulations(...)] 调用;
- 第 155 行:函数 [array_map] 把方法 [toSimulation] 应用于列表的每个元素,并返回结果列表。语法 [self::toSimulation(...)](PHP 8.1,“一等可调用语法”)根据方法创建一个匿名函数([Closure]),其来源是方法 [toSimulation]。它取代了旧语法 [[self::class, "toSimulation"]];
- 第 162 行:[...] 运算符把 [$attributes] 数组展开为构造函数的参数。从 PHP 8.1 开始,数组的字符串键成为命名参数:键 [married] 传给参数 [$married],键 [tax] 传给参数 [$tax],依此类推,与数组中键的顺序无关。如果服务器发送了构造函数不认识的键,PHP 会抛出 [Error] 错误;
- PHP 7 客户端使用 [setFromArrayOfAttributes] 方法(属于类 [BaseEntity] ),用数组的元素初始化 [Simulation] 对象。请注意,其 [Simulation] 对象的 JSON 序列化包含冗余属性 [arrayOfAttributes] ,它继承自 [BaseEntity] 类。现在不再如此。
[deleteSimulation] 方法
| // 操作 [delete-simulation]
#[\Override]
public function deleteSimulation(int $number): array
{
// GET main.php?action=delete-simulation&number=1
$serverResponse = $this->sendRequest("GET", ["action" => "delete-simulation", "number" => $number]);
// 服务器返回新的模拟列表
return self::getSimulations($serverResponse);
}
|
说明
- 第 170 行:发出带有两个 URL 参数的 GET 请求;
- 第 172 行:删除之后,服务器返回新的模拟列表。该列表被返回。
[endSession] 方法
与 Web 服务的一次工作会话通常以调用 [endSession] 方法结束:
| // 操作 [end-session]
#[\Override]
public function endSession(): void
{
// GET main.php?action=end-session - 响应是一条简单消息
$this->sendRequest("GET", ["action" => "end-session"]);
}
|
说明
- 第 180 行:向 GET 发出带有唯一参数 [action] 的请求。如果响应的 HTTP 状态码不是 200,就会抛出异常。服务器以新的会话 Cookie 作为响应,由 [getResponse] 方法保存:此后的请求将在新会话中进行,而用户在新会话中并未通过身份验证。
23.14.3. [business] 层

23.14.3.1. 接口
[business] 层的接口如下:[Business/InterfaceClientBusiness.php]:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// 版本 12 的 JSON Web 服务客户端的 [business] 层接口
interface InterfaceClientBusiness
{
// 批处理模式下的税款计算:[business] 层特有的唯一方法
// 只有当 [$resultsFileName] 不为 null 时才保存结果
public function executeBatchTaxes(
string $taxPayersFileName,
string $errorsFileName,
?string $resultsFileName = null
): void;
// 下面的方法是 [dao] 层的方法
// 计算纳税人的税款
public function calculateTax(string $married, int $children, int $salary): Simulation;
// 保存结果
/** @param Simulation[] $simulations */
public function saveResults(string $resultsFilename, array $simulations): void;
// 会话开始
public function initSession(string $type = "json"): void;
// 认证
public function authenticateUser(string $user, #[\SensitiveParameter] string $password): void;
// 模拟列表
/** @return Simulation[] */
public function listSimulations(): array;
// 删除一个模拟
/** @return Simulation[] */
public function deleteSimulation(int $number): array;
// 会话结束
public function endSession(): void;
}
|
说明
- 第 13 行:只有方法 [executeBatchTaxes] 是 [business] 层特有的。其他所有方法都属于实现它们的 [dao] 层;
- 第 16 行:结果文件是可选的。如果缺少它,结果就不保存。该参数的类型是 [?string] (字符串或 [null])。我们把它放在最后:可选参数必须位于必选参数之后。PHP 7 课程声明为 [string $resultsFileName] 并向该方法传入 [NULL] ,这在 [strict_types=1] 模式下会导致 [TypeError] 类型的错误。
23.14.3.2. [ClientBusiness] 类
实现 [business] 层的类如下:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// 客户端的 [business] 层:税款计算由服务器完成
class ClientBusiness implements InterfaceClientBusiness
{
// [dao] 层由构造函数注入
public function __construct(private readonly InterfaceClientDao $clientDao)
{
}
// 批处理模式下的税款计算
#[\Override]
public function executeBatchTaxes(
string $taxPayersFileName,
string $errorsFileName,
?string $resultsFileName = null
): void {
// 我们让来自 [dao] 层的异常向上传递
// 我们获取纳税人数据
$taxPayersData = $this->clientDao->getTaxPayersData($taxPayersFileName, $errorsFileName);
// 我们计算每位纳税人的税款:服务器把模拟存储在会话中
$simulations = array_map(
fn(TaxPayerData $taxPayerData): Simulation => $this->calculateTax(
$taxPayerData->married,
$taxPayerData->children,
$taxPayerData->salary
),
$taxPayersData
);
// 如有要求,保存结果
if ($resultsFileName !== null) {
$this->clientDao->saveResults($resultsFileName, $simulations);
}
}
// 其他方法把工作委托给 [dao] 层
#[\Override]
public function calculateTax(string $married, int $children, int $salary): Simulation
{
return $this->clientDao->calculateTax($married, $children, $salary);
}
#[\Override]
public function saveResults(string $resultsFilename, array $simulations): void
{
$this->clientDao->saveResults($resultsFilename, $simulations);
}
#[\Override]
public function initSession(string $type = "json"): void
{
$this->clientDao->initSession($type);
}
#[\Override]
public function authenticateUser(string $user, #[\SensitiveParameter] string $password): void
{
$this->clientDao->authenticateUser($user, $password);
}
#[\Override]
public function listSimulations(): array
{
return $this->clientDao->listSimulations();
}
#[\Override]
public function deleteSimulation(int $number): array
{
return $this->clientDao->deleteSimulation($number);
}
#[\Override]
public function endSession(): void
{
$this->clientDao->endSession();
}
}
|
说明
- 第 12 行:要实例化,[business] 层需要一个对 [dao] 层的引用。该引用由构造函数注入,并通过构造函数属性提升成为只读属性;
- 第 18–22 行:只有 [executeBatchTaxes] 方法是 [business] 层特有的。其他方法的实现把工作委托给 [dao] 层中的同名方法;
- 第 25 行:访问 [dao] 层,把纳税人数据取回到 [TaxPayerData] 类型对象的数组中;
- 第 27–34 行:计算 [$taxPayersData] 数组中每位纳税人的税额。由 [array_map] 调用的箭头函数(PHP 7.4)为每位纳税人返回服务器返回的 [Simulation] 对象。每次计算也由服务器存入用户的会话中;
- 第 36–37 行:只有指定了文件名,结果才会被保存到 JSON 文件中。
注意:[business] 层几乎什么也不做。也可以决定删除它,把所有内容合并到 [dao] 层中。
23.14.4. 主脚本

主脚本由如下文件 [Data/config.json] 配置:
| {
"urlServer": "http://localhost/php8-oct-2026/scripts-web/tax/version-12/main.php",
"user": {
"login": "admin",
"passwd": "admin"
},
"httpClientOptions": {
"verify_peer": false,
"verify_host": false
},
"taxPayersDataFilename": "Data/taxpayersdata.json",
"resultsFilename": "Data/results.json",
"errorsFilename": "Data/errors.json",
"dependencies": [
"../version-05/Entities/TaxException.php",
"../version-05/Entities/TaxPayerData.php",
"../version-05/Utilities/Utilities.php",
"../version-05/Dao/TraitDao.php",
"../../../scripts-web/tax/version-12/Entities/Simulation.php",
"Dao/InterfaceClientDao.php",
"Dao/ClientDao.php",
"Business/InterfaceClientBusiness.php",
"Business/ClientBusiness.php"
]
}
|
- 第 2 行:版本 12 中服务器主控制器的 URL。我们使用 [http] 协议,自版本 8 起一直如此(参见版本 8 一章中“为什么用 [http] 而不用 [https]?”一节);
- 第 3 行:用户的凭据;
- 第 7 行:HTTP 客户端选项,版本 11 的客户端已经使用过:如果 URL 使用 [https] 协议,则不验证服务器的自签名证书;
- 第 14–24 行:要加载的应用程序文件,相对于客户端的 [version-12] 文件夹。其中包括服务器的 [Simulation] 类。PHP 7 课程还提供了绝对根目录 [rootDirectory] 以及 Composer 自动加载器的绝对路径。与之前的版本一样,现在路径基于常量 [__DIR__] 计算:[php8-oct-2026] 文件夹可以移动而无需更改配置。
主脚本 [Main/main.php] 如下:
| <?php
// 严格遵守所声明的函数参数和结果的类型
declare(strict_types=1);
// 命名空间
namespace Application;
// 客户端的根文件夹:配置文件的路径相对于此文件夹
const ROOT_DIRECTORY = __DIR__ . "/..";
// 配置文件的路径
const CONFIG_FILENAME = ROOT_DIRECTORY . "/Data/config.json";
// 获取配置
$config = json_decode(file_get_contents(CONFIG_FILENAME), true, flags: JSON_THROW_ON_ERROR);
// 我们引入脚本所需的依赖:第三方库 (Symfony),然后是应用程序文件
require_once ROOT_DIRECTORY . "/../../../vendor/autoload.php";
foreach ($config["dependencies"] as $dependency) {
require_once ROOT_DIRECTORY . "/$dependency";
}
// 数据文件的路径
$taxPayersDataFilename = ROOT_DIRECTORY . "/" . $config["taxPayersDataFilename"];
$resultsFilename = ROOT_DIRECTORY . "/" . $config["resultsFilename"];
$errorsFilename = ROOT_DIRECTORY . "/" . $config["errorsFilename"];
// 创建 [dao] 层 - 服务器的响应将被显示(详细模式)
$clientDao = new ClientDao($config["urlServer"], $config["httpClientOptions"], verbose: true);
// 创建 [business] 层
$clientBusiness = new ClientBusiness($clientDao);
// 与 JSON Web 服务的完整对话
try {
// 初始化 JSON 会话
$clientBusiness->initSession("json");
// 认证
$clientBusiness->authenticateUser($config["user"]["login"], $config["user"]["passwd"]);
// 批处理模式下的税款计算,不保存结果(没有 [resultsFileName] 参数)
$clientBusiness->executeBatchTaxes(
taxPayersFileName: $taxPayersDataFilename,
errorsFileName: $errorsFilename
);
// 模拟列表
$clientBusiness->listSimulations();
// 删除第 1 号模拟(列表中的第 2 个)
$simulations = $clientBusiness->deleteSimulation(1);
// 保存剩余的模拟
$clientBusiness->saveResults($resultsFilename, $simulations);
print count($simulations) . " simulations have been saved in the file [{$config["resultsFilename"]}]\n";
// 会话结束
$clientBusiness->endSession();
// 在新会话中的操作,此时我们未通过身份验证:必须失败
$clientBusiness->listSimulations();
} catch (TaxException $ex) {
// 我们显示错误
print "Error no. {$ex->getCode()}: {$ex->getMessage()}\n";
}
// 结束
print "Done\n";
|
说明
- 第 10–15 行:处理配置文件 [config.json];
- 第 18–20 行:加载所有依赖项;
- 第 24–26 行:数据文件的绝对路径;
- 第 29–31 行:构建 [dao] 层和 [business] 层。参数 [$verbose] 以名称传入:[verbose: true] 比单纯的 [true] 更具描述性;
- 第 36 行:初始化 JSON 会话;
- 第 38 行:向服务器进行身份验证;
- 第 40–43 行:为一组纳税人计算税额。不保存结果:借助命名参数,我们只需省略可选参数 [resultsFileName];
- 第 45 行:取回所有这些计算的结果;
- 第 47 行:删除 1 号模拟(列表中的第二个);
- 第 49 行:保存剩余的模拟;
- 第 52 行:结束会话。服务器删除该会话并启动一个新会话;
- 第 54 行:请求模拟列表。在新会话中,用户未通过身份验证。因此应当出现一个异常,指出用户未通过身份验证。
文件 [taxpayersdata.json] 与之前的版本相同:
| [
{
"married": "yes",
"children": 2,
"salary": 55555
},
{
"married": "yesx",
"children": "2x",
"salary": "55555x"
},
{
"married": "yes",
"children": "2",
"salary": 50000
},
{
"married": "yes",
"children": 3,
"salary": 50000
},
{
"married": "no",
"children": 2,
"salary": 100000
},
{
"married": "no",
"children": 3,
"salary": 100000
},
{
"married": "yes",
"children": 3,
"salary": 100000
},
{
"married": "yes",
"children": 5,
"salary": 100000
},
{
"married": "no",
"children": 0,
"salary": 100000
},
{
"married": "yes",
"children": 2,
"salary": 30000
},
{
"married": "no",
"children": 0,
"salary": 200000
},
{
"married": "yes",
"children": 3,
"salary": 200000
}
]
|
共有 12 位纳税人,其中 1 位不正确。因此总共有 11 次模拟。其中一次将被删除,应当剩下 10 次。
控制台输出如下(在详细模式下,服务器的 JSON 响应会显示在控制台上):
| > php main.php
{"action":"init-session","status":700,"response":"session started with type [json]"}
{"action":"authenticate-user","status":200,"response":"Authentication successful [admin]"}
{"action":"calculate-tax","status":300,"response":{"married":"yes","children":2,"salary":55555,"tax":2814,"surcharge":0,"discount":0,"reduction":0,"rate":0.14}}
{"action":"calculate-tax","status":300,"response":{"married":"yes","children":2,"salary":50000,"tax":1384,"surcharge":0,"discount":384,"reduction":347,"rate":0.14}}
{"action":"calculate-tax","status":300,"response":{"married":"yes","children":3,"salary":50000,"tax":0,"surcharge":0,"discount":720,"reduction":0,"rate":0.14}}
{"action":"calculate-tax","status":300,"response":{"married":"no","children":2,"salary":100000,"tax":19884,"surcharge":4480,"discount":0,"reduction":0,"rate":0.41}}
{"action":"calculate-tax","status":300,"response":{"married":"no","children":3,"salary":100000,"tax":16782,"surcharge":7176,"discount":0,"reduction":0,"rate":0.41}}
{"action":"calculate-tax","status":300,"response":{"married":"yes","children":3,"salary":100000,"tax":9200,"surcharge":2180,"discount":0,"reduction":0,"rate":0.3}}
{"action":"calculate-tax","status":300,"response":{"married":"yes","children":5,"salary":100000,"tax":4230,"surcharge":0,"discount":0,"reduction":0,"rate":0.14}}
{"action":"calculate-tax","status":300,"response":{"married":"no","children":0,"salary":100000,"tax":22986,"surcharge":0,"discount":0,"reduction":0,"rate":0.41}}
{"action":"calculate-tax","status":300,"response":{"married":"yes","children":2,"salary":30000,"tax":0,"surcharge":0,"discount":0,"reduction":0,"rate":0.0}}
{"action":"calculate-tax","status":300,"response":{"married":"no","children":0,"salary":200000,"tax":64210,"surcharge":7498,"discount":0,"reduction":0,"rate":0.45}}
{"action":"calculate-tax","status":300,"response":{"married":"yes","children":3,"salary":200000,"tax":42842,"surcharge":17283,"discount":0,"reduction":0,"rate":0.41}}
{"action":"list-simulations","status":500,"response":[{"married":"yes","children":2,"salary":55555,"tax":2814,"surcharge":0,"discount":0,"reduction":0,"rate":0.14},{"married":"yes","children":2,"salary":50000,"tax":1384,"surcharge":0,"discount":384,"reduction":347,"rate":0.14},{"married":"yes","children":3,"salary":50000,"tax":0,"surcharge":0,"discount":720,"reduction":0,"rate":0.14},{"married":"no","children":2,"salary":100000,"tax":19884,"surcharge":4480,"discount":0,"reduction":0,"rate":0.41},{"married":"no","children":3,"salary":100000,"tax":16782,"surcharge":7176,"discount":0,"reduction":0,"rate":0.41},{"married":"yes","children":3,"salary":100000,"tax":9200,"surcharge":2180,"discount":0,"reduction":0,"rate":0.3},{"married":"yes","children":5,"salary":100000,"tax":4230,"surcharge":0,"discount":0,"reduction":0,"rate":0.14},{"married":"no","children":0,"salary":100000,"tax":22986,"surcharge":0,"discount":0,"reduction":0,"rate":0.41},{"married":"yes","children":2,"salary":30000,"tax":0,"surcharge":0,"discount":0,"reduction":0,"rate":0.0},{"married":"no","children":0,"salary":200000,"tax":64210,"surcharge":7498,"discount":0,"reduction":0,"rate":0.45},{"married":"yes","children":3,"salary":200000,"tax":42842,"surcharge":17283,"discount":0,"reduction":0,"rate":0.41}]}
{"action":"delete-simulation","status":600,"response":[{"married":"yes","children":2,"salary":55555,"tax":2814,"surcharge":0,"discount":0,"reduction":0,"rate":0.14},{"married":"yes","children":3,"salary":50000,"tax":0,"surcharge":0,"discount":720,"reduction":0,"rate":0.14},{"married":"no","children":2,"salary":100000,"tax":19884,"surcharge":4480,"discount":0,"reduction":0,"rate":0.41},{"married":"no","children":3,"salary":100000,"tax":16782,"surcharge":7176,"discount":0,"reduction":0,"rate":0.41},{"married":"yes","children":3,"salary":100000,"tax":9200,"surcharge":2180,"discount":0,"reduction":0,"rate":0.3},{"married":"yes","children":5,"salary":100000,"tax":4230,"surcharge":0,"discount":0,"reduction":0,"rate":0.14},{"married":"no","children":0,"salary":100000,"tax":22986,"surcharge":0,"discount":0,"reduction":0,"rate":0.41},{"married":"yes","children":2,"salary":30000,"tax":0,"surcharge":0,"discount":0,"reduction":0,"rate":0.0},{"married":"no","children":0,"salary":200000,"tax":64210,"surcharge":7498,"discount":0,"reduction":0,"rate":0.45},{"married":"yes","children":3,"salary":200000,"tax":42842,"surcharge":17283,"discount":0,"reduction":0,"rate":0.41}]}
10 simulations have been saved in the file [Data/results.json]
{"action":"end-session","status":400,"response":"session deleted"}
{"action":"list-simulations","status":104,"response":["action requested by unauthenticated user"]}
Error no. 42: {"HTTP status":400,"action":"list-simulations","status":104,"response":["action requested by unauthenticated user"]}
Done
|
- 第 2–3 行:JSON 会话启动,用户通过身份验证;
- 第 4–14 行:11 次税额计算。不正确的纳税人没有被发送到服务器;
- 第 15 行:11 次模拟的列表;
- 第 16 行:删除 1 号模拟(税额 1384)之后剩余的 10 次模拟的列表;
- 第 17 行:保存结果之后来自主脚本的消息;
- 第 18 行:会话结束;
- 第 19–20 行:模拟列表被拒绝(状态 104):在新会话中,用户未通过身份验证。PHP 7 客户端此前在这里收到的是状态 103(没有活动会话),因为它继续发送旧的会话 Cookie。版本 12 的服务器在 [end-session] 动作期间保留会话类型:因此客户端仍然是 JSON 客户端,但必须重新进行身份验证。
主脚本运行之后,JSON 文件 [results.json] 如下所示:
| [
{
"married": "yes",
"children": 2,
"salary": 55555,
"tax": 2814,
"surcharge": 0,
"discount": 0,
"reduction": 0,
"rate": 0.14
},
{
"married": "yes",
"children": 3,
"salary": 50000,
"tax": 0,
"surcharge": 0,
"discount": 720,
"reduction": 0,
"rate": 0.14
},
{
"married": "no",
"children": 2,
"salary": 100000,
"tax": 19884,
"surcharge": 4480,
"discount": 0,
"reduction": 0,
"rate": 0.41
},
{
"married": "no",
"children": 3,
"salary": 100000,
"tax": 16782,
"surcharge": 7176,
"discount": 0,
"reduction": 0,
"rate": 0.41
},
{
"married": "yes",
"children": 3,
"salary": 100000,
"tax": 9200,
"surcharge": 2180,
"discount": 0,
"reduction": 0,
"rate": 0.3
},
{
"married": "yes",
"children": 5,
"salary": 100000,
"tax": 4230,
"surcharge": 0,
"discount": 0,
"reduction": 0,
"rate": 0.14
},
{
"married": "no",
"children": 0,
"salary": 100000,
"tax": 22986,
"surcharge": 0,
"discount": 0,
"reduction": 0,
"rate": 0.41
},
{
"married": "yes",
"children": 2,
"salary": 30000,
"tax": 0,
"surcharge": 0,
"discount": 0,
"reduction": 0,
"rate": 0.0
},
{
"married": "no",
"children": 0,
"salary": 200000,
"tax": 64210,
"surcharge": 7498,
"discount": 0,
"reduction": 0,
"rate": 0.45
},
{
"married": "yes",
"children": 3,
"salary": 200000,
"tax": 42842,
"surcharge": 17283,
"discount": 0,
"reduction": 0,
"rate": 0.41
}
]
|
确实有 10 次模拟。JSON 文件 [errors.json] 的内容如下:
| [
{
"number": 1,
"errors": [
{
"married": "yesx"
},
{
"children": "2x"
},
{
"salary": "55555x"
}
]
}
]
|
23.14.5. [PHPUnit] 测试
与之前的客户端一样,版本 12 的客户端可以使用 [PHPUnit] 进行测试。测试类 [Tests/ClientBusinessTest.php] 与之前客户端的测试类相似:
| <?php
// 严格遵守所声明的函数参数和结果的类型
declare(strict_types=1);
// 测试的命名空间
namespace Application\Tests;
// 被测试的类
use Application\ClientDao;
use Application\ClientBusiness;
use Application\TaxException;
use Application\InterfaceClientBusiness;
use Application\Simulation;
// PHPUnit 的类
use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\TestCase;
// 测试 JSON Web 服务客户端的 [business] 层:服务器必须处于运行状态
final class ClientBusinessTest extends TestCase
{
// 客户端的根文件夹
private const string ROOT_DIRECTORY = __DIR__ . "/..";
// 客户端的配置
private static array $config;
// 被测试的 [business] 层
private InterfaceClientBusiness $business;
// 在类的第一个测试之前执行一次
#[\Override]
public static function setUpBeforeClass(): void
{
// 我们获取客户端的配置
self::$config = json_decode(file_get_contents(self::ROOT_DIRECTORY . "/Data/config.json"), true, flags: JSON_THROW_ON_ERROR);
// 我们引入客户端的依赖(Composer 自动加载器已由 PHPUnit 加载)
foreach (self::$config["dependencies"] as $dependency) {
require_once self::ROOT_DIRECTORY . "/$dependency";
}
}
// 在每个测试之前执行:每个测试都有自己的已通过身份验证的 JSON 会话
#[\Override]
protected function setUp(): void
{
// 创建 [dao](非详细模式)层和 [business] 层
$clientDao = new ClientDao(self::$config["urlServer"], self::$config["httpClientOptions"], verbose: false);
$this->business = new ClientBusiness($clientDao);
// 初始化 JSON 会话
$this->business->initSession("json");
// 认证
$this->business->authenticateUser(self::$config["user"]["login"], self::$config["user"]["passwd"]);
}
// 官方数据表中的纳税人
public static function taxpayers(): array
{
// [married, children, salary, 官方税款, 预期的 [tax, surcharge, discount, reduction, rate]]
return [
"couple, 2 children, 55555" => ["yes", 2, 55555, 2815, [2814, 0, 0, 0, 0.14]],
"couple, 2 children, 50000" => ["yes", 2, 50000, 1385, [1384, 0, 384, 347, 0.14]],
"couple, 3 children, 50000" => ["yes", 3, 50000, 0, [0, 0, 720, 0, 0.14]],
"single, 2 children, 100000" => ["no", 2, 100000, 19884, [19884, 4480, 0, 0, 0.41]],
"single, 3 children, 100000" => ["no", 3, 100000, 16782, [16782, 7176, 0, 0, 0.41]],
"couple, 3 children, 100000" => ["yes", 3, 100000, 9200, [9200, 2180, 0, 0, 0.3]],
"couple, 5 children, 100000" => ["yes", 5, 100000, 4230, [4230, 0, 0, 0, 0.14]],
"single, 0 children, 100000" => ["no", 0, 100000, 22986, [22986, 0, 0, 0, 0.41]],
"couple, 2 children, 30000" => ["yes", 2, 30000, 0, [0, 0, 0, 0, 0.0]],
"single, 0 children, 200000" => ["no", 0, 200000, 64211, [64210, 7498, 0, 0, 0.45]],
"couple, 3 children, 200000" => ["yes", 3, 200000, 42843, [42842, 17283, 0, 0, 0.41]],
];
}
// 对数据提供者中的每一位纳税人各执行一次的测试
#[DataProvider("taxpayers")]
public function testCalculateTax(string $married, int $children, int $salary, int $officialTax, array $expected): void
{
// 税款计算
$simulation = $this->business->calculateTax($married, $children, $salary);
// 税款与官方模拟器的结果相差在 1 欧元以内
$this->assertEqualsWithDelta($officialTax, $simulation->tax, 1);
// 该模拟与预期完全一致:[assertEquals] 比较两个对象的属性
$this->assertEquals(new Simulation($married, $children, $salary, ...$expected), $simulation);
}
// [list-simulations] 和 [delete-simulation] 操作
public function testListDeleteSimulations(): void
{
// 新会话中的两个模拟
$this->business->calculateTax("yes", 2, 55555);
$this->business->calculateTax("no", 0, 100000);
$this->assertCount(2, $this->business->listSimulations());
// 删除第 1 个:第 2 个保留
$simulations = $this->business->deleteSimulation(0);
$this->assertCount(1, $simulations);
$this->assertSame(22986, $simulations[0]->tax);
// 第 1 号模拟不再存在:状态 628,HTTP 状态 400
$this->assertError(400, 628, fn() => $this->business->deleteSimulation(1));
}
// 会话结束后,用户不再处于已通过身份验证的状态
public function testEndSession(): void
{
$this->business->endSession();
// 状态 104:未通过身份验证的用户请求了操作
$this->assertError(400, 104, fn() => $this->business->listSimulations());
}
// 检查操作 [$action] 抛出代码为 42 的 [TaxException] 异常
// 其 JSON 消息包含预期的 HTTP 状态和状态
private function assertError(int $httpStatus, int $status, \Closure $action): void
{
try {
$action();
$this->fail("a [TaxException] exception was expected");
} catch (TaxException $ex) {
$this->assertSame(42, $ex->getCode());
$error = json_decode($ex->getMessage(), true, flags: JSON_THROW_ON_ERROR);
$this->assertSame($httpStatus, $error["HTTP status"]);
$this->assertSame($status, $error["status"]);
}
}
}
|
说明
- 第 31–37 行:客户端配置的读取和依赖项的加载只在第一个测试之前进行一次;
- 第 43–51 行:请注意,[setUp] 方法在每个测试之前都会执行。它构造 [dao] 层(非详细模式)和 [business] 层,然后初始化一个 JSON 会话并进行身份验证。因此每个测试都在它自己的会话中运行,与其他测试相互独立。PHP 7 课程在测试类的构造函数中完成这项工作,而 PHPUnit 已不再允许这样做;
- 第 55–69 行:来自之前版本的数据提供者。对于每位纳税人,我们有官方模拟器计算出的税额,以及 [tax, surcharge, discount, reduction, rate] 的五个预期结果;
- 第 82 行:构造预期的模拟,并与服务器返回的模拟进行比较。应用于两个对象时,[assertEquals] 方法验证它们属于同一个类且属性相等。这里运算符 [...] 展开一个列表:其元素依次传给构造函数的最后五个参数;
- 第 86–97 行:对动作 [list-simulations] 和 [delete-simulation] 的测试。我们运行两次模拟,删除第一次,并验证第二次仍然存在。然后我们请求删除一个不存在的模拟:服务器必须以状态 628 响应;
- 第 101–105 行:会话结束之后,模拟列表必须被拒绝,状态码为 104;
- 第 110–119 行:一个工具方法,用于验证作为匿名函数传入的动作 [$action] 会抛出带有代码 42、预期 HTTP 状态和预期状态的 [TaxException] 异常。由于异常消息是服务器的 JSON 响应,因此要对它解码以验证其各个元素。如果没有抛出异常,[fail] 方法会使测试失败。
测试结果如下:
| > php vendor/bin/phpunit scripts-console/tax/version-12/Tests --testdox
PHPUnit 12.5.37 by Sebastian Bergmann and contributors.
Runtime: PHP 8.5.11
Configuration: .../php8-oct-2026/phpunit.xml
............. 13 / 13 (100%)
Time: 00:00.195, Memory: 16.00 MB
Client Business (Application\Tests\ClientBusiness)
✔ Calculate tax with data set "couple, 2 children, 55555"
✔ Calculate tax with data set "couple, 2 children, 50000"
✔ Calculate tax with data set "couple, 3 children, 50000"
✔ Calculate tax with data set "single, 2 children, 100000"
✔ Calculate tax with data set "single, 3 children, 100000"
✔ Calculate tax with data set "couple, 3 children, 100000"
✔ Calculate tax with data set "couple, 5 children, 100000"
✔ Calculate tax with data set "single, 0 children, 100000"
✔ Calculate tax with data set "couple, 2 children, 30000"
✔ Calculate tax with data set "single, 0 children, 200000"
✔ Calculate tax with data set "couple, 3 children, 200000"
✔ List delete simulations
✔ End session
OK (13 tests, 31 assertions)
|
还应当进行许多其他测试:
- 测试 [dao] 层的各个方法;
- 测试 Web 服务器返回的状态码。这些状态码很重要,因为它们的值决定了要显示哪个 HTML 页面。