13. 实践练习——版本 5
我们已经编写了这个练习的若干版本。最近的版本采用了分层架构:

[dao] 层实现 [InterfaceDao] 接口。我们创建了一个实现该接口的类:
- [DaoTaxWithTaxAdminDataInJsonFile],它从 JSON 文件中获取税务数据。
我们将实现 [InterfaceDao] 接口,使用一个新类 [DaoTaxWithTaxAdminDataInDatabase],它将从 MySQL 数据库中获取税务机关的数据。
13.1. 创建 [dbtaxes-2019] 数据库
沿用上一章的例子,我们将创建一个名为 [dbtaxes-2019] 的 MySQL 数据库,属于用户 [admtaxes] ,密码为 [pwdtaxes]。该数据库将有两个表:
- 表 [tbbrackets] 将包含税率档次;
- 表 [tbconstants] 将包含税款计算中使用的常量。
PHP 7 课程使用 [phpMyAdmin] 向导创建数据库、用户和表,然后把得到的结构导出为 SQL 文件。我们将采用相反的方法:直接编写 SQL 脚本 [dbtaxes-2019.sql] ,并将它放在版本 5 的 [Data] 文件夹中:
| -- database [dbtaxes-2019] of the tax calculation application - MySQL DBMS
-- to be executed by the administrator [root] of the DBMS:
-- mysql -u root < dbtaxes-2019.sql
-- the database, its tables and its user are recreated if they already exist
-- the database
DROP DATABASE IF EXISTS `dbtaxes-2019`;
CREATE DATABASE `dbtaxes-2019` CHARACTER SET utf8mb4;
-- its owner [admtaxes] with password [pwdtaxes]
DROP USER IF EXISTS 'admtaxes'@'localhost';
CREATE USER 'admtaxes'@'localhost' IDENTIFIED BY 'pwdtaxes';
GRANT ALL PRIVILEGES ON `dbtaxes-2019`.* TO 'admtaxes'@'localhost';
-- the tables are created in the [dbtaxes-2019] database
USE `dbtaxes-2019`;
-- the table of the tax brackets
CREATE TABLE tbbrackets (
id INT NOT NULL AUTO_INCREMENT,
limits DECIMAL(10, 2) NOT NULL,
coeffr DECIMAL(6, 2) NOT NULL,
coeffn DECIMAL(10, 2) NOT NULL,
PRIMARY KEY (id)
);
-- the table of the tax calculation constants
CREATE TABLE tbconstants (
id INT NOT NULL AUTO_INCREMENT,
halfShareQfCeiling DECIMAL(10, 2) NOT NULL,
singleIncomeCeilingForReduction DECIMAL(10, 2) NOT NULL,
coupleIncomeCeilingForReduction DECIMAL(10, 2) NOT NULL,
halfShareReductionValue DECIMAL(10, 2) NOT NULL,
singleDiscountCeiling DECIMAL(10, 2) NOT NULL,
coupleDiscountCeiling DECIMAL(10, 2) NOT NULL,
singleTaxCeilingForDiscount DECIMAL(10, 2) NOT NULL,
coupleTaxCeilingForDiscount DECIMAL(10, 2) NOT NULL,
tenPercentAllowanceMax DECIMAL(10, 2) NOT NULL,
tenPercentAllowanceMin DECIMAL(10, 2) NOT NULL,
PRIMARY KEY (id)
);
|
说明
- 第 7 行:如果 [dbtaxes-2019] 数据库存在,则将其删除。这样,如果数据库被删除或损坏,就可以再次运行该脚本来重新生成它。数据库名包含连字符:必须用反引号 ` 括起来,这样 MySQL 才不会把它解释为减法;
- 第 8 行:使用字符集 [utf8mb4] 创建数据库;
- 第 11–13 行:(重新)创建用户 [admtaxes],密码为 [pwdtaxes]。该用户对数据库 [dbtaxes-2019] 拥有全部权限;
- 第 16 行:以下命令作用于数据库 [dbtaxes-2019];
- 第 19–25 行:表 [tbbrackets] 有四列:
- [id] 是整数,为表的主键,由 DBMS 自动递增([AUTO_INCREMENT])。这意味着 MySQL 在插入时自己管理主键的值:第一次插入时将主键赋值为 1,下一次赋值为 2,依此类推;
- [limits] 是一个 10 位小数,带 2 位小数([DECIMAL(10, 2)])。它将包含税率档次中 [limits] 列的元素;
- [coeffr] 是一个 6 位小数,带 2 位小数。它将包含税率档次中 [coeffR] 列的元素;
- [coeffn] 是一个 10 位小数,带 2 位小数。它将包含税率档次中 [coeffN] 列的元素;
- 第 28–41 行:表 [tbconstants] 有一个主键 [id] ,以及每个税款计算常量对应的一个小数列。它只包含一行。
[DECIMAL] 类型精确存储数值,不同于实数类型 [FLOAT] 和 [DOUBLE],后者以二进制存储近似值:0.14 被精确地存储为 0.14。
在 [Laragon] 终端中,于 [version-05/Data] 文件夹下使用以下命令运行该脚本:
| mysql -u root < dbtaxes-2019.sql
|
如果一切顺利,不会显示任何内容。以 [admtaxes] 身份登录来验证结果:
| > mysql -u admtaxes -ppwdtaxes dbtaxes-2019 -e "show tables"
mysql: [Warning] Using a password on the command line interface can be insecure.
+------------------------+
| Tables_in_dbtaxes-2019 |
+------------------------+
| tbbrackets |
| tbconstants |
+------------------------+
|
| > mysql -u admtaxes -ppwdtaxes dbtaxes-2019 -e "describe tbbrackets"
mysql: [Warning] Using a password on the command line interface can be insecure.
+--------+---------------+------+-----+---------+----------------+
| Field | Type | Null | Key | Default | Extra |
+--------+---------------+------+-----+---------+----------------+
| id | int | NO | PRI | NULL | auto_increment |
| limits | decimal(10,2) | NO | | NULL | |
| coeffr | decimal(6,2) | NO | | NULL | |
| coeffn | decimal(10,2) | NO | | NULL | |
+--------+---------------+------+-----+---------+----------------+
|
- 第 6 行:[id] 列是主键(PRI),其值由 MySQL 管理(auto_increment)。
当然,你也可以打开并运行脚本 [dbtaxes-2019.sql] ,在 [HeidiSQL] 或 [phpMyAdmin] 中查看表结构。
13.2. 代码组织
为了更好地说明我们所编写的各个 PHP 脚本的作用,我们将把版本 5 的代码组织到若干文件夹中:
| version-05
├── Business
│ ├── Business.php
│ └── InterfaceBusiness.php
├── Dao
│ ├── DaoTaxWithTaxAdminDataInDatabase.php
│ ├── DaoTransferAdminDataFromJsonFile2Database.php
│ ├── InterfaceDao.php
│ ├── InterfaceDao4TransferAdminData2Database.php
│ └── TraitDao.php
├── Data
│ ├── database.json
│ ├── dbtaxes-2019.sql
│ ├── errors.json
│ ├── results.json
│ ├── taxadmindata.json
│ └── taxpayersdata.json
├── Entities
│ ├── Database.php
│ ├── TaxAdminData.php
│ ├── TaxException.php
│ └── TaxPayerData.php
├── Main
│ ├── MainCalculateTaxWithTaxAdminDataInMySQLDatabase.php
│ └── MainTransferAdminDataFromJsonFile2MySQLDatabase.php
├── Tests
│ ├── data
│ │ ├── database-incomplete.json
│ │ └── database-wrong-pwd.json
│ ├── BusinessTest.php
│ └── DaoTest.php
└── Utilities
└── Utilities.php
|
- [Entities]:应用程序实体,即各层之间交换的对象;
- [Utilities]:应用程序工具;
- [Data]:应用程序使用或产生的数据,以及 SQL 数据库脚本。这里我们决定文本文件只使用 JSON 文件。它们有几个优点:
- 许多工具都能识别它们;
- 这些工具支持语法高亮。此外,JSON 表示法遵循特定的规则。当这些规则未被遵守时,工具会标出错误。例如,在普通文本文件中很难发现的一种错误,是把大写字母 O 用成了数字零。如果你在 JSON 文件中不小心键入了 ["coupleIncomeCeilingForReduction": 42O74],[VS Code] 会用红线标出值 42O74——因为它既不是数字,也不是用引号括起来的字符串——并且 [Problems] 选项卡会显示该错误。开发人员的注意力会被吸引到这个错误上,从而可以改正它;
- [Dao]:[dao] 层的接口、trait 和类;
- [Business]:[business] 层的接口和类。PHP 7 课程将该文件夹称为 [Métier]。我们避免在文件夹和文件名中使用带重音的字符:在系统之间传输文件(ZIP 压缩包、Git 仓库等)时,它们会引起问题;
- [Main]:版本 5 的主脚本;
- [Tests]:版本 5 的测试([PHPUnit])。
版本 5 有两个不同的目标:
- 将 JSON 文件的内容填入 MySQL 数据库 [dbtaxes-2019] ,即文件 [Data/taxadmindata.json] 的内容;
- 使用现在来自 MySQL 数据库 [dbtaxes-2019] 的税务数据来实现税款计算。
我们将分别处理这两个目标。
13.3. 填充 [dbtaxes-2019] 数据库
13.3.1. 目标
文件 [Data/taxadmindata.json] 包含税务机关的数据。这是版本 4 的文件:
| {
"limits": [9964, 27519, 73779, 156244, 0],
"coeffR": [0, 0.14, 0.3, 0.41, 0.45],
"coeffN": [0, 1394.96, 5798, 13913.69, 20163.45],
"halfShareQfCeiling": 1551,
"singleIncomeCeilingForReduction": 21037,
"coupleIncomeCeilingForReduction": 42074,
"halfShareReductionValue": 3797,
"singleDiscountCeiling": 1196,
"coupleDiscountCeiling": 1970,
"coupleTaxCeilingForDiscount": 2627,
"singleTaxCeilingForDiscount": 1595,
"tenPercentAllowanceMax": 12502,
"tenPercentAllowanceMin": 437
}
|
我们的目标是把这些数据传送到前面创建的 MySQL 数据库 [dbtaxes-2019] 中。
13.3.2. 实体
实体是在应用程序各层之间交换的对象。其中三个来自版本 4,原样纳入,不做任何修改:
- 异常 [TaxException];
- [readonly] [TaxAdminData] 类,包含税务管理数据,通过其静态方法 [fromJsonFile] 和 [fromArray] 构造;
- [readonly] [TaxPayerData] 类,包含纳税人的数据及其税款计算的结果。
我们再增加第四个实体 [Database],它描述数据库。
13.3.2.1. 为什么没有基类 [BaseEntity]?
PHP 7 课程在这里引入了一个父类 [BaseEntity],所有实体都派生自它。它基于一条规则:实体的属性与其所封装的 JSON 文件中的键同名。于是 [BaseEntity] 可以用如下循环,根据 JSON 文件或关联数组初始化任何实体:
| foreach ($arrayOfAttributes as $key => $value) {
$this->$key = $value;
}
|
实体属性被声明为 [protected] (无类型),以便父类可以修改它们,并且每个实体都添加了自己的 getter 和 setter。我们不采用这种方案:
- 当 JSON 文件中的某个键拼写错误时,上述循环会悄悄地创建一个动态属性。这自 PHP 8.2 起已被弃用,并且在 [readonly] 类中是被禁止的;
- 实体可以被任何层通过其 setter 或 [setFromArrayOfAttributes] 方法修改。我们的实体是不可变的:某一层不会意外修改从另一层收到的对象;
- “JSON 与类中名称相同”这条规则仍然适用,但 PHP 8 直接使用它:表达式 [new self(...$data)] 将数组的键转换为构造函数的命名参数(PHP 8.1)。随后由 PHP 来验证没有缺失的键、没有未知的键,并且每个值的类型正确。不再有任何需要提取到父类中的公共代码。
最后,版本 4 已经添加了 [fromArray] 方法,它属于 [TaxAdminData] 类。我们将看到,这个方法足以根据从数据库读取的数据构造 [TaxAdminData] 对象。一个重要的结果是,版本 4 的 [business] 层将被原样复用:在 PHP 7 课程中,对实体的更改曾迫使我们修改 [business] 层。
13.3.2.2. 实体 [Database]
实体 [Database] 将用于封装以下 JSON 文件的数据:[Data/database.json]:
| {
"dsn": "mysql:host=localhost;dbname=dbtaxes-2019;charset=utf8mb4",
"id": "admtaxes",
"pwd": "pwdtaxes",
"tableBrackets": "tbbrackets",
"colId": "id",
"colLimits": "limits",
"colCoeffR": "coeffr",
"colCoeffN": "coeffn",
"tableConstants": "tbconstants",
"colHalfShareQfCeiling": "halfShareQfCeiling",
"colSingleIncomeCeilingForReduction": "singleIncomeCeilingForReduction",
"colCoupleIncomeCeilingForReduction": "coupleIncomeCeilingForReduction",
"colHalfShareReductionValue": "halfShareReductionValue",
"colSingleDiscountCeiling": "singleDiscountCeiling",
"colCoupleDiscountCeiling": "coupleDiscountCeiling",
"colSingleTaxCeilingForDiscount": "singleTaxCeilingForDiscount",
"colCoupleTaxCeilingForDiscount": "coupleTaxCeilingForDiscount",
"colTenPercentAllowanceMax": "tenPercentAllowanceMax",
"colTenPercentAllowanceMin": "tenPercentAllowanceMin"
}
|
它的属性描述 MySQL 数据库 [dbtaxes-2019] 的特征:
属性 | 作用 |
dsn | 数据库的 DSN |
id | 数据库所有者 |
pwd | 其密码 |
tableBrackets | 包含税率档次的表的名称 |
colId / colLimits / colCoeffR / colCoeffN | 表 [tableBrackets] 中的列名 |
tableConstants | 包含税款计算常量的表的名称 |
colHalfShareQfCeiling / colSingleIncomeCeilingForReduction / colCoupleIncomeCeilingForReduction / colHalfShareReductionValue / colSingleDiscountCeiling / colCoupleDiscountCeiling / colSingleTaxCeilingForDiscount / colCoupleTaxCeilingForDiscount / colTenPercentAllowanceMax / colTenPercentAllowanceMin | 表 [tableConstants] 中包含税款计算常量的列名 |
既然我们已经知道表名和列名,而且它们不太可能改变,为什么还要列出它们?在 MySQL DBMS 之后,我们还将使用 PostgreSQL DBMS 来存储税务管理数据。然而,PostgreSQL 中的列名和表名所遵循的规则与 MySQL 不同,我们将不得不使用不同的名称。其他 DBMS 也是如此。如果我们希望代码可以跨 DBMS 移植,最好使用参数,而不是硬编码的表名和列名。与 PHP 7 课程相比,我们增加了属性 [colId],它是税率档次表中主键列的名称:我们需要它,才能按插入的顺序读回这些税率档次。
[Database] 类如下:[Entities/Database.php]:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// 税务数据库的描述:一个不可变对象
final readonly class Database
{
// 税款计算常量:每个常量在 [tableConstants] 表中都有自己的列
public const array CONSTANTS = [
"halfShareQfCeiling",
"singleIncomeCeilingForReduction",
"coupleIncomeCeilingForReduction",
"halfShareReductionValue",
"singleDiscountCeiling",
"coupleDiscountCeiling",
"singleTaxCeilingForDiscount",
"coupleTaxCeilingForDiscount",
"tenPercentAllowanceMax",
"tenPercentAllowanceMin",
];
// 私有构造函数:必须通过 [fromJsonFile] 方法
private function __construct(
// 连接到数据库
public string $dsn,
public string $id,
#[\SensitiveParameter] public string $pwd,
// 税率档表及其列
public string $tableBrackets,
public string $colId,
public string $colLimits,
public string $colCoeffR,
public string $colCoeffN,
// 计算常量表及其列
public string $tableConstants,
public string $colHalfShareQfCeiling,
public string $colSingleIncomeCeilingForReduction,
public string $colCoupleIncomeCeilingForReduction,
public string $colHalfShareReductionValue,
public string $colSingleDiscountCeiling,
public string $colCoupleDiscountCeiling,
public string $colSingleTaxCeilingForDiscount,
public string $colCoupleTaxCeilingForDiscount,
public string $colTenPercentAllowanceMax,
public string $colTenPercentAllowanceMin,
) {
}
// 从 JSON 文件构建,其键是属性的名称
public static function fromJsonFile(string $databaseFilename): self
{
// 可能抛出 [TaxException] 异常
$data = Utilities::readJsonFile($databaseFilename);
// JSON 必须是对象 {...}
if (!is_array($data) || array_is_list($data)) {
throw new TaxException("The file [$databaseFilename] does not contain a JSON object", 20);
}
try {
// 数组的键成为构造函数的命名参数
return new self(...$data);
} catch (\Error $ex) {
// 未知键、缺失键、非字符串的值……
throw new TaxException("The file [$databaseFilename] is incorrect ({$ex->getMessage()})", 21, $ex);
}
}
// 计算常量的列名:[常量名 => 列名]
public function constantColumns(): array
{
$columns = [];
foreach (self::CONSTANTS as $constant) {
// 常量 [halfShareQfCeiling] 所在的列保存在属性 [colHalfShareQfCeiling] 中
$columns[$constant] = $this->{"col" . ucfirst($constant)};
}
return $columns;
}
}
|
说明
- 第 9 行:与 [TaxAdminData] 一样,[Database] 类是不可变的,且不能被派生;
- 第 12–23 行:十个税款计算常量的名称。它们也是 [TaxAdminData] 类各属性的名称;
- 第 26–50 行:私有构造函数通过属性提升,为 [database.json] 文件中的每个键声明一个同名、类型为 [string] 的公共属性;
- 第 30 行:PHP 8.2 的属性 [#[\SensitiveParameter]] 将该参数标记为敏感。如果在构造函数执行期间抛出异常,密码值就不会出现在异常的调用栈(堆栈跟踪)中,而调用栈经常被写入日志文件:在那里它会被一个 [SensitiveParameterValue] 对象取代;
- 第 53–68 行:静态方法 [fromJsonFile] 根据 JSON 文件构造 [Database] 对象:
- 第 56 行:读取和解码 JSON 文件由 [Utilities] 类负责,稍后介绍。这些操作可能抛出 [TaxException] 异常;
- 第 58 行:
JSON 必须是一个对象,也就是关联数组,而不是列表;
- 第 63 行:[$data] 数组的键成为构造函数的命名参数。如果缺少某个键,PHP 会抛出 [ArgumentCountError] 错误;如果某个键未知,则抛出 [Error] 错误(“Unknown named parameter”);如果某个值不是字符串,则抛出 [TypeError] 错误。这三种错误都派生自 [Error] 类;
- 第 64–66 行:该错误被捕获并转换为代码为 21 的 [TaxException],同时把原始错误([$ex])保留为前一个异常。消息中包含的 PHP 错误信息准确指出了问题所在;
- 第 71–79 行:[constantColumns] 方法返回关联数组 [constant name => column name]。对于常量 [halfShareQfCeiling],列名位于属性 [colHalfShareQfCeiling] 中。[ucfirst] 函数将字符串的首字母大写,而语法 [$this->{"col" . ucfirst($constant)}] 引用的是这样的属性:其名称是花括号内表达式的值。该方法使我们不必在 [dao] 层中把几乎相同的代码写上十遍。
13.3.2.3. [Utilities] 类
版本 4 使用 [Utilities] 类来去除文本文件各行的行尾字符。我们现在只使用 JSON 文件:[Utilities] 类现在既处理 JSON 文件的读取,也处理其写入 [Utilities/Utilities.php]:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// 一个工具函数类:既不能被实例化,也不能被派生
final class Utilities
{
// 私有构造函数:该类不能被实例化
private function __construct()
{
}
// 读取 JSON 文件并返回其解码后的内容(JSON 对象变为关联数组)
public static function readJsonFile(string $fileName): mixed
{
// 获取文件内容
$contents = is_readable($fileName) ? file_get_contents($fileName) : false;
if ($contents === false) {
throw new TaxException("The file [$fileName] does not exist or cannot be read", 15);
}
// 解码 JSON
try {
return json_decode($contents, true, flags: JSON_THROW_ON_ERROR);
} catch (\JsonException $ex) {
throw new TaxException("The file [$fileName] does not contain valid JSON ({$ex->getMessage()})", 16, $ex);
}
}
// 将值以 JSON 格式保存到文本文件中(文件不存在则创建,存在则覆盖)
public static function writeJsonFile(string $fileName, mixed $data): void
{
// 带缩进的 JSON,重音字符不转义,浮点数始终带小数点写出(0.0)
$json = json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_PRESERVE_ZERO_FRACTION | JSON_THROW_ON_ERROR);
if (@file_put_contents($fileName, "$json\n") === false) {
throw new TaxException("Error while saving data to the file [$fileName]", 14);
}
}
}
|
说明
- 第 17–30 行:[readJsonFile] 方法读取 JSON 文件并返回其解码后的内容,该内容可以是任意类型([mixed]):JSON 对象返回关联数组,JSON 数组则返回列表。代码就是我们在版本 3 的 [TaxAdminData::fromJsonFile] 方法中所写的那段。错误由 [TaxException] 报告,代码为 15(文件不可读)或 16(JSON 无效);
- 第 33–40 行:[writeJsonFile] 方法将一个值以 JSON 格式写入文本文件。[json_encode] 的选项通过 [|] 运算符组合:
- [JSON_PRETTY_PRINT] 生成带缩进、易于阅读的 JSON;
- [JSON_UNESCAPED_UNICODE] 按原样写入带重音的字符(marié),而不是它们的编码(marié);
- [JSON_PRESERVE_ZERO_FRACTION] 将实数 0.0 写成 0.0 而不是 0:这样在输出文件中可以区分实数与整数;
- [JSON_THROW_ON_ERROR] 在值无法编码为 JSON 时触发 [JsonException] 异常。
13.3.3. [dao] 层
现在我们可以编写代码,把 JSON 文件 [taxadmindata.json] 中的数据传送到 MySQL 数据库 [dbtaxes-2019] 的 [tbbrackets, tbconstants] 表中。我们将使用如下架构:

[dao] 层将实现下面的 [InterfaceDao4TransferAdminData2Database] 接口:[Dao/InterfaceDao4TransferAdminData2Database.php]:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// 将税务数据传输到数据库的 [dao] 层接口
interface InterfaceDao4TransferAdminData2Database
{
// 将税务管理部门的数据保存到数据库
// 出错时抛出 [TaxException] 异常
public function transferAdminData2Database(): void;
}
|
- 第 13 行:[transferAdminData2Database] 方法负责将税务管理数据存入数据库。
[InterfaceDao4TransferAdminData2Database] 接口将由下面的 [DaoTransferAdminDataFromJsonFile2Database] 类实现:[Dao/DaoTransferAdminDataFromJsonFile2Database.php]:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// 将税务管理部门的数据从 JSON 文件传输到数据库
class DaoTransferAdminDataFromJsonFile2Database implements InterfaceDao4TransferAdminData2Database
{
// 目标数据库的描述
private readonly Database $database;
// 税务管理部门的数据
private readonly TaxAdminData $taxAdminData;
// 构造函数
public function __construct(string $databaseFilename, string $taxAdminDataFilename)
{
// 可能抛出 [TaxException] 异常
$this->database = Database::fromJsonFile($databaseFilename);
$this->taxAdminData = TaxAdminData::fromJsonFile($taxAdminDataFilename);
}
// 将税务数据传输到数据库
#[\Override]
public function transferAdminData2Database(): void
{
$database = $this->database;
try {
// 打开数据库连接
$connection = \PDO::connect($database->dsn, $database->id, $database->pwd);
// 开始一个事务
$connection->beginTransaction();
// 填充税率档表
$this->fillTableBrackets($connection);
// 填充常量表
$this->fillTableConstants($connection);
// 成功结束事务
$connection->commit();
} catch (\PDOException $ex) {
// 是否有正在进行的事务?
if (isset($connection) && $connection->inTransaction()) {
// 失败结束事务
$connection->rollBack();
}
// 将错误以 [TaxException] 异常的形式向上传递给调用代码
throw new TaxException("Database access error ({$ex->getMessage()})", 30, $ex);
}
// 变量 [$connection] 消失时(即方法结束时)连接自动关闭
}
|
说明
这里,我们应用在 MySQL 一章中学到的知识。
- 第 9 行:[DaoTransferAdminDataFromJsonFile2Database] 类实现 [InterfaceDao4TransferAdminData2Database] 接口;
- 第 12 行:属性 [$database] 是 [Database] 类型的对象,封装了文件 [database.json] 中的数据;
- 第 14 行:属性 [$taxAdminData] 是 [TaxAdminData] 类型的对象,封装了文件 [taxadmindata.json] 中的数据;
- 第 17–22 行:构造函数接收 [database.json, taxadmindata.json] 这两个文件的名称作为参数,并初始化两个属性。如果其中一个文件无效,则向调用代码抛出 [TaxException] 异常;
- 第 26 行:实现 [InterfaceDao4TransferAdminData2Database] 接口的唯一方法;
- 第 31 行:打开数据库连接。请注意写法 [\PDO],它指的是 PHP 的 [PDO] 类。事实上,由于我们处于 [Application] 命名空间中,如果只写 [PDO],这个相对名称就会被加上当前命名空间作为前缀,从而指向并不存在的类 [Application\PDO],。方法 [PDO::connect] 在这里返回 [Pdo\Mysql] 类型的对象,因为 DSN 以 [mysql:] 开头。这个类中没有任何内容依赖于 MySQL:决定所用 DBMS 的是从 [database.json] 文件中读取的 DSN;
- 第 33–39 行:[tbbrackets, tbconstants] 表在一个事务中被填充。一旦出现问题,方法 [fillTableBrackets] and [fillTableConstants] 就会触发 [PDOException] 。此时,执行继续进入 [catch] 子句,数据库保持其初始状态:不会出现 [tbbrackets] 表已填充而 [tbconstants] 表为空的风险;
- 第 40–47 行:代码抛出了异常的情形。如果有事务正在进行,则将其回滚。然后抛出一个代码为 30 的 [TaxException] 类型异常,并附带原始异常的消息,原始异常成为前一个异常。这样调用代码只需处理一种异常类型;
- 第 49 行:PHP 7 的做法是在 [finally] 子句中用 [$connection = NULL] 语句关闭连接。这是不必要的:局部变量 [$connection] 在方法结束时消失,连接也随之关闭。
[fillTableBrackets] 方法的代码如下:
| // 填充税率档表
private function fillTableBrackets(\PDO $connection): void
{
// 快捷方式
$database = $this->database;
$taxAdminData = $this->taxAdminData;
// 清空表,以防其中已有内容
$connection->exec("delete from $database->tableBrackets");
// 准备插入语句
$statement = $connection->prepare(
"insert into $database->tableBrackets ($database->colLimits, $database->colCoeffR, $database->colCoeffN)"
. " values (:limits, :coeffR, :coeffN)"
);
// 用每个税率档的值执行预处理语句
foreach ($taxAdminData->limits as $i => $limit) {
$statement->execute([
"limits" => $limit,
"coeffR" => $taxAdminData->coeffR[$i],
"coeffN" => $taxAdminData->coeffN[$i],
]);
}
}
|
说明
- 第 53 行:[fillTableBrackets] 方法接收一个已打开的连接作为参数。我们还知道,在该连接中已经开始了一个事务;
- 第 56–57 行:两个快捷方式,避免在整个代码中反复书写 [$this->database] 和 [$this->taxAdminData]。它们是对象引用的副本,而不是对象本身的副本;
- 第 59 行:删除“税率档次”表的当前内容。表名使用语法 ["$database->tableBrackets"] 插入字符串中:PHP 将该表达式替换为属性的值;
- 第 61–64 行:准备向表中插入行。这里使用的是属性 [$database] 提供的表名和列名。表名和列名不能作为预处理语句的参数,只有值可以。这就是为什么要把它们插入 SQL 语句文本中。它们来自配置文件而不是用户:不存在 SQL 注入的风险;
- 第 66–72 行:预处理的插入语句按需执行多次,每个税率档次一次。[$i] 是档次编号,用作数组 [coeffR] 和 [coeffN] 的索引。
[fillTableConstants] 方法的代码如下:
| // 填充常量表
private function fillTableConstants(\PDO $connection): void
{
// 快捷方式
$database = $this->database;
// 清空表,以防其中已有内容
$connection->exec("delete from $database->tableConstants");
// [常量名 => 列名]
$columns = $database->constantColumns();
// 预处理语句的参数以常量名命名::halfShareQfCeiling, ...
$parameters = array_map(fn(string $constant): string => ":$constant", array_keys($columns));
$statement = $connection->prepare(
"insert into $database->tableConstants (" . implode(", ", $columns) . ")"
. " values (" . implode(", ", $parameters) . ")"
);
// 参数的值:[常量名 => 常量的值]
$values = [];
foreach (array_keys($columns) as $constant) {
$values[$constant] = $this->taxAdminData->$constant;
}
// 执行预处理语句:插入一行
$statement->execute($values);
}
|
说明
- 第 76 行:[fillTableConstants] 方法同样接收一个已打开的、其中有事务正在进行的连接;
- 第 81 行:清空表 [tbconstants];
- 第 83 行:数组 [constant name => column name],例如 [["halfShareQfCeiling" => "halfShareQfCeiling", ...]];
- 第 85 行:预处理语句的参数名称:[[":halfShareQfCeiling", ...]]。它们是在常量名称前加上冒号;
- 第 86–89 行:准备 SQL 插入命令。[implode] 函数构造以逗号分隔的列列表和参数列表。由此得到命令 [insert into tbconstants (halfShareQfCeiling, ...) values (:halfShareQfCeiling, ...)]。PHP 7 课程把整条命令逐列写出,大约占了二十行;
- 第 91–94 行:[constant name => value] 形式的参数值表。语法 [$this->taxAdminData->$constant] 指定 [TaxAdminData] 对象的属性,其名称是变量 [$constant] 的值;
- 第 96 行:执行插入语句。只有一行需要插入。
13.3.4. 主脚本
主脚本 [Main/MainTransferAdminDataFromJsonFile2MySQLDatabase.php] 依靠 [dao] 层来完成数据传送:
| <?php
// 严格遵守所声明的函数参数和结果的类型
declare(strict_types=1);
// 命名空间
namespace Application;
// 引入数据传输所需的接口和类
require_once __DIR__ . "/../Entities/TaxException.php";
require_once __DIR__ . "/../Entities/TaxAdminData.php";
require_once __DIR__ . "/../Entities/Database.php";
require_once __DIR__ . "/../Utilities/Utilities.php";
require_once __DIR__ . "/../Dao/InterfaceDao4TransferAdminData2Database.php";
require_once __DIR__ . "/../Dao/DaoTransferAdminDataFromJsonFile2Database.php";
// 常量的定义
const DATABASE_CONFIG_FILENAME = __DIR__ . "/../Data/database.json";
const TAXADMINDATA_FILENAME = __DIR__ . "/../Data/taxadmindata.json";
try {
// 创建 [dao] 层
$dao = new DaoTransferAdminDataFromJsonFile2Database(DATABASE_CONFIG_FILENAME, TAXADMINDATA_FILENAME);
// 将数据传输到数据库
$dao->transferAdminData2Database();
print "The data of the tax administration have been transferred into the database\n";
} catch (TaxException $ex) {
// 我们显示错误
print "Error no. {$ex->getCode()}: {$ex->getMessage()}\n";
}
// 结束
print "Done\n";
|
说明
- 第 10–15 行:加载传送所需的类和接口。路径是相对于脚本所在文件夹([Main])的:[__DIR__ . "/../Entities"] 指的是相邻的文件夹 [Entities];
- 第 18–19 行:两个 JSON 文件的路径,同样是相对于脚本所在文件夹的。PHP 7 课程使用的是相对于当前文件夹的路径(["../Data/database.json"]):这样脚本只有在 [Main] 文件夹中运行时才能工作;
- 第 23 行:通过向构造函数传递两个 JSON 文件的名称来实例化 [dao] 层;
- 第 25 行:执行数据传送;
- 第 27–29 行:显示异常的代码和消息。PHP 7 课程在这里使用了 [utf8_encode] 函数,该函数自 PHP 8.2 起已被弃用,而且由于我们所有的消息都是 UTF-8,它也没有必要。
当我们在 [Main] 文件夹中打开的终端里运行该脚本时,得到如下结果:
| > php MainTransferAdminDataFromJsonFile2MySQLDatabase.php
The data of the tax administration have been transferred into the database
Done
|
数据库中有如下内容:
| > mysql -u admtaxes -ppwdtaxes dbtaxes-2019 -e "select * from tbbrackets"
mysql: [Warning] Using a password on the command line interface can be insecure.
+----+-----------+--------+----------+
| id | limits | coeffr | coeffn |
+----+-----------+--------+----------+
| 1 | 9964.00 | 0.00 | 0.00 |
| 2 | 27519.00 | 0.14 | 1394.96 |
| 3 | 73779.00 | 0.30 | 5798.00 |
| 4 | 156244.00 | 0.41 | 13913.69 |
| 5 | 0.00 | 0.45 | 20163.45 |
+----+-----------+--------+----------+
|
- 列 [id]:MySQL 分配给主键的值。编号从 1 开始。如果我们再次运行脚本,这些行会被删除然后重新插入,而 MySQL 会继续编号(6、7……):自增键的值绝不会被重用;
- 这些数字有两位小数,与各列的 [DECIMAL(10, 2)] 数据类型一致。
位于 SQL 命令末尾的选项 [\G] 以纵向方式显示每一行,每列占屏幕上的一行,这对于列很多的表来说更易于阅读:
| > mysql -u admtaxes -ppwdtaxes dbtaxes-2019 -e "select * from tbconstants\G"
mysql: [Warning] Using a password on the command line interface can be insecure.
*************************** 1. row ***************************
id: 1
halfShareQfCeiling: 1551.00
singleIncomeCeilingForReduction: 21037.00
coupleIncomeCeilingForReduction: 42074.00
halfShareReductionValue: 3797.00
singleDiscountCeiling: 1196.00
coupleDiscountCeiling: 1970.00
singleTaxCeilingForDiscount: 1595.00
coupleTaxCeilingForDiscount: 2627.00
tenPercentAllowanceMax: 12502.00
tenPercentAllowanceMin: 437.00
|
13.4. 税款计算
13.4.1. 架构
税款计算应用程序的版本 4 使用了分层架构:

[dao] 层实现 [InterfaceDao] 接口。版本 4 中的 [DaoTaxWithTaxAdminDataInJsonFile] 类从 JSON 文件中获取税务数据。我们将实现 [InterfaceDao] 接口,使用一个新类 [DaoTaxWithTaxAdminDataInDatabase],它将从 MySQL 数据库中获取税务机关的数据。[dao] 层与以前一样,会把结果和错误写入文本文件,并同样从文本文件中获取纳税人数据,只不过这次这些文本文件是 JSON 文件。此外,我们知道,只要继续遵守 [InterfaceDao] 接口,[business] 层就无需修改。

13.4.2. [TaxPayerData] 实体
版本 4 中的 [TaxPayerData] 类封装了纳税人的数据([married, children, salary])及其税款计算的结果([tax, surcharge, discount, reduction, rate])。它原样沿用。纳税人数据现在位于下面的 JSON 文件 [Data/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
}
]
|
JSON 对象的键是 [TaxPayerData] 类中各属性的名称。请注意以下几点:
- 第 8 行:1 号纳税人(编号从 0 开始)是错误的:他的三项数据全都无效;
- 第 14 行:2 号纳税人的子女数是以字符串形式给出的。我们将接受它;
- 其余十一名纳税人来自税务管理部门的官方测试,自版本 1 起一直在使用。
13.4.3. [dao] 层
13.4.3.1. [InterfaceDao] 接口
版本 4 的 [InterfaceDao] 接口原样纳入,不做修改 [Dao/InterfaceDao.php]:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// [dao] 层的接口
// 出现不可恢复的错误时,所有方法都会抛出 [TaxException] 异常
interface InterfaceDao
{
// 读取纳税人数据
// 不正确的行会报告到文本文件 [$errorsFilename] 中
/** @return TaxPayerData[] */
public function getTaxPayersData(string $taxPayersFilename, string $errorsFilename): array;
// 读取税务管理部门的数据(税率档和常量)
public function getTaxAdminData(): TaxAdminData;
// 保存结果
/** @param TaxPayerData[] $taxPayersData */
public function saveResults(string $resultsFilename, array $taxPayersData): void;
}
|
方法 [getTaxPayersData] 和 [saveResults] 接收文件名:并没有说明它们是普通文本文件还是 JSON 文件。因此该接口仍然有效。
13.4.3.2. [TraitDao] trait
[TraitDao] trait 实现了 [InterfaceDao] 接口的 [getTaxPayersData] 和 [saveResults] 方法。由于我们已从普通文本文件改用 JSON 文件,因此需要重写它 [Dao/TraitDao.php]:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// 实现 [InterfaceDao] 中处理 JSON 文件的方法
trait TraitDao
{
// 从 JSON 文件中读取纳税人数据
#[\Override]
public function getTaxPayersData(string $taxPayersFilename, string $errorsFilename): array
{
// 文件内容:由 {married, children, salary} 对象组成的数组
// 可能抛出 [TaxException] 异常
$taxpayers = Utilities::readJsonFile($taxPayersFilename);
if (!is_array($taxpayers) || !array_is_list($taxpayers)) {
throw new TaxException("The file [$taxPayersFilename] does not contain a JSON array", 17);
}
// 纳税人数据的数组
$taxPayersData = [];
// 错误的数组
$errors = [];
// 检查每一位纳税人
foreach ($taxpayers as $number => $taxpayer) {
$taxpayerErrors = $this->check($taxpayer);
if ($taxpayerErrors === []) {
// 又一位纳税人
$taxPayersData[] = new TaxPayerData(
strtolower(trim($taxpayer["married"])),
(int) $taxpayer["children"],
(int) $taxpayer["salary"]
);
} else {
// 又一个错误:记录 JSON 数组中不正确的纳税人的序号
$errors[] = ["number" => $number, "errors" => $taxpayerErrors];
}
}
// 将错误保存到 JSON 文件中
Utilities::writeJsonFile($errorsFilename, $errors);
// 函数的结果
return $taxPayersData;
}
// 检查一位纳税人的数据:返回不正确属性的列表
private function check(mixed $taxpayer): array
{
// 纳税人必须是 JSON 对象
if (!is_array($taxpayer)) {
return [["taxpayer" => $taxpayer]];
}
$errors = [];
// 婚姻状况必须是 yes 或 no
$married = $taxpayer["married"] ?? null;
if (!is_string($married) || !in_array(strtolower(trim($married)), ["yes", "no"], true)) {
$errors[] = ["married" => $married];
}
// 子女数和工资必须是正整数或零
// 可以是数字 (2),也可以是字符串 ("2")
foreach (["children", "salary"] as $key) {
$value = $taxpayer[$key] ?? null;
$valid = (is_int($value) && $value >= 0)
|| (is_string($value) && preg_match('/^\s*\d+\s*$/', $value) === 1);
if (!$valid) {
$errors[] = [$key => $value];
}
}
return $errors;
}
// 将结果保存到 JSON 文件中
#[\Override]
public function saveResults(string $resultsFilename, array $taxPayersData): void
{
// [TaxPayerData] 对象根据其公共属性转换为 JSON 对象
Utilities::writeJsonFile($resultsFilename, $taxPayersData);
}
}
|
说明
- 第 13–44 行:[getTaxPayersData] 方法接收以下参数:
- [$taxPayersFilename]:包含纳税人数据的 JSON 文件的名称 [taxpayersdata.json];
- [$errorsFilename]:包含错误的 JSON 文件的名称 [errors.json];
- 第 17 行:包含纳税人数据的 JSON 文件的内容被解码到 [$taxpayers] 数组中。如果该 JSON 文件被证明无法使用,则抛出 [TaxException] 异常;
- 第 18 行:内容必须是 JSON 数组,即 PHP 列表。否则抛出代码为 17 的异常;
- 第 22 行:数组 [$taxPayersData] 将包含封装在 [TaxPayerData] 类型对象中的纳税人数据;
- 第 24 行:错误将累积在数组 [$errors] 中;
- 第 26–39 行:构造数组 [$taxPayersData]。在被封装进 [TaxPayerData] 对象之前,数据先由 [check] 方法验证,该方法返回无效属性的列表——如果数据有效,则返回空列表:
- 第 30–34 行:数据有效的情形。创建一个新的 [TaxPayerData] 对象并将其添加到 [$taxPayersData] 数组中。婚姻状况被转换为小写,子女数和薪水被转换为整数:[(int) "2"] 得到 2;
- 第 37 行:数据无效的情形。错误消息包含错误纳税人在 JSON 数组中的编号,以便用户定位,然后将错误添加到数组 [$errors] 中;
- 第 41 行:遇到的错误被记录在 JSON 文件 [$errorsFilename] 中。PHP 7 课程错误地写入的是 JSON 字符串,每行一个:出现多个错误时,该文件不是有效的 JSON 文件。我们写入的是由这些错误组成的 JSON 数组;
- 第 43 行:返回所构造的 [TaxPayerData] 对象的数组:这正是该方法的目的;
- 第 47–70 行:私有方法 [check] 验证纳税人数据的有效性。参数 [$taxpayer] 的类型为 [mixed]:JSON 数组的元素可以是任何东西(对象、数字、字符串等)。该方法以 [incorrect attribute => value] 数组的形式,把无效属性汇总到 [$errors] 数组中:
- 第 50 行:该元素必须是 JSON 对象;
- 第 55 行:[??] 运算符(空合并)在 [$taxpayer["married"]] 存在且不为 [null] 时返回其值,否则返回 [null]。这样可以避免缺少键时触发的警告;
- 第 56–58 行:婚姻状况必须是表示“yes”或“no”的字符串,忽略大小写和空格;
- 第 61–68 行:子女数和薪水必须是正整数或零,以 JSON 数字(2)或字符串("2")的形式给出。字符串必须由数字组成,两侧可以带空格:这正是正则表达式 [/^\s*\d+\s*$/] 所检查的内容。请注意比较 [preg_match(...) === 1]:[preg_match] 函数在字符串匹配模式时返回 1,不匹配时返回 0,出错时返回 [false];
- 第 74–78 行:实现 [saveResults] 方法,它属于 [InterfaceDao] 接口。[TaxPayerData] 对象的数组被直接以 JSON 格式存储:[json_encode] 函数将对象转换为 JSON 对象,其键是对象公共属性的名称。PHP 7 课程是“手工”根据数组构造 JSON 字符串的:把各对象的 JSON 字符串用逗号连接起来,再加上方括号。
13.4.3.3. [DaoTaxWithTaxAdminDataInDatabase] 类
[DaoTaxWithTaxAdminDataInDatabase] 类按如下方式实现 [InterfaceDao] 接口:[Dao/DaoTaxWithTaxAdminDataInDatabase.php]:
| <?php
declare(strict_types=1);
// 命名空间
namespace Application;
// 在数据库中查找税务管理部门数据的 [dao] 层
class DaoTaxWithTaxAdminDataInDatabase implements InterfaceDao
{
// 该 trait 实现了接口的 [getTaxPayersData] 和 [saveResults] 方法
use TraitDao;
// 数据库的描述
private readonly Database $database;
// 包含税务管理部门数据的 [TaxAdminData] 类型的对象
private readonly TaxAdminData $taxAdminData;
// 构造函数
public function __construct(string $databaseFilename)
{
// 数据库的描述 - 可能抛出 [TaxException] 异常
$this->database = Database::fromJsonFile($databaseFilename);
$database = $this->database;
try {
// 打开数据库连接
// 读取的行将以关联数组 [列 => 值] 的形式返回
$connection = \PDO::connect(
$database->dsn,
$database->id,
$database->pwd,
[\PDO::ATTR_DEFAULT_FETCH_MODE => \PDO::FETCH_ASSOC]
);
// 开始一个事务
$connection->beginTransaction();
// 读取税率档表
$brackets = $this->getBrackets($connection);
// 读取常量表
$constants = $this->getConstants($connection);
// 成功结束事务
$connection->commit();
} catch (\PDOException $ex) {
// 是否有正在进行的事务?
if (isset($connection) && $connection->inTransaction()) {
// 失败结束事务
$connection->rollBack();
}
// 将错误以 [TaxException] 异常的形式向上传递给调用代码
throw new TaxException("Database access error ({$ex->getMessage()})", 30, $ex);
}
// 构建 [TaxAdminData] 对象:对读取的数据进行检查
$this->taxAdminData = TaxAdminData::fromArray([...$brackets, ...$constants]);
}
|
说明
- 第 6 行:我们保留应用程序中其他类已经使用的命名空间;
- 第 9 行:类 [DaoTaxWithTaxAdminDataInDatabase] 实现接口 [InterfaceDao];
- 第 12 行:导入 [TraitDao] trait。我们知道这个 trait 实现了接口的一部分。剩下唯一需要实现的方法是 [getTaxAdminData] 方法,它只是返回私有属性 [$taxAdminData]。由此可以推断,构造函数需要初始化这个属性。这就是它唯一的目的;
- 第 20 行:构造函数接收 JSON 文件名 [database.json], 作为其唯一参数,该文件定义了 MySQL 数据库 [dbtaxes-2019];
- 第 23 行:利用该 JSON 文件创建一个 [Database] 类型的对象,并存放在属性 [$database] 中。如果 JSON 文件无法被正确处理,则抛出 [TaxException] 异常;
- 第 28–33 行:打开数据库连接。第四个参数设置读取行的默认模式:[column => value] 形式的关联数组;
- 第 35 行:开始一个事务。严格来说这并非必需,因为只会执行两条 SQL 命令,而且这些命令不会修改数据库。不过这样做是为了把程序与数据库的其他用户隔离开:即使另一个程序同时修改这两个表,这两个表也是在同一状态下被读取的;
- 第 37 行:使用私有方法 [getBrackets] 读取税率档次表 [tbbrackets]。该方法返回数组 [["limits" => [...], "coeffR" => [...], "coeffN" => [...]]];
- 第 39 行:计算常量表 [tbconstants] 由私有方法 [getConstants] 读取。它返回数组 [constant name => value];
- 第 41 行:如果执行到这一行,说明一切顺利。因此我们提交事务;
- 第 42–49 行:如果执行到这里,说明发生了异常。因此,如果有事务正在进行,就将其回滚。然后,为了保证异常的一致性,我们将该错误重新抛出为代码为 30 的 [TaxException] 类型异常;
- 第 52 行:表达式 [[...$brackets, ...$constants]] 将两个关联数组合并为一个数组,它恰好具有 [TaxAdminData::fromArray] 方法所期望的十三个键。该方法会像验证来自 JSON 文件的数据一样验证从数据库读取的数据,并将其转换为实数。PHP 7 课程是逐个属性地初始化 [TaxAdminData] 对象的,需要十次调用 setter。
[getBrackets] 方法如下:
| // 读取税率档表
// 返回数组 ["limits" => [...], "coeffR" => [...], "coeffN" => [...]]
private function getBrackets(\PDO $connection): array
{
// 快捷方式
$database = $this->database;
// 准备并执行 SELECT 查询
$statement = $connection->prepare(
"select $database->colLimits, $database->colCoeffR, $database->colCoeffN"
. " from $database->tableBrackets order by $database->colId"
);
$statement->execute();
// 一次取回所有行:由关联数组组成的数组
$brackets = $statement->fetchAll();
// 提取结果的每一列
return [
"limits" => array_column($brackets, $database->colLimits),
"coeffR" => array_column($brackets, $database->colCoeffR),
"coeffN" => array_column($brackets, $database->colCoeffN),
];
}
|
说明
- 第 57 行:该方法接收一个已打开的、其中有事务正在进行的连接作为参数;
- 第 62–65 行:准备并执行 SELECT 语句。针对主键的 [order by] 子句确保税率档次按插入的顺序读回。PHP 7 的命令没有这个子句,依赖的是 MySQL 返回行的顺序,而这一顺序是无法保证的;
- 第 68 行:一次性读取结果的所有行。得到一个由关联数组组成的数组,例如 [[["limits" => "9964.00", "coeffr" => "0.00", "coeffn" => "0.00"], ...]]。请注意,[DECIMAL] 类型列中的值是以字符串形式返回的:PHP 没有精确的十进制类型,而驱动程序也不会把它们转换为 [float],因为那会导致精度损失。转换将由 [TaxAdminData::fromArray] 方法完成;
- 第 70–74 行:[array_column] 函数从关联数组组成的数组中提取一列:[array_column($brackets, "limits")] 返回 [["9964.00", "27519.00", ...]]。
私有方法 [getConstants] 如下:
| // 读取计算常量表
// 返回数组 [常量名 => 值]
private function getConstants(\PDO $connection): array
{
// [常量名 => 列名]
$columns = $this->database->constantColumns();
// 准备并执行 SELECT 查询
$statement = $connection->prepare(
"select " . implode(", ", $columns) . " from {$this->database->tableConstants}"
);
$statement->execute();
// 使用结果 - 这里只有 1 行 - 表为空时为 [false]
$row = $statement->fetch() ?: [];
// [常量名 => 其所在列的值](表为空时为 null)
return array_map(fn(string $column): mixed => $row[$column] ?? null, $columns);
}
|
说明
- 第 82 行:数组 [constant name => column name];
- 第 84–86 行:准备并执行针对这十列的 SELECT 命令。请注意 [{$this->database->tableConstants}] 中的花括号:没有它们,PHP 只会把字符串中的 [$this->database] 当作变量解释;
- 第 89 行:该表只有一行,由 [fetch] 方法读取。如果没有行,该方法返回 [false] 。运算符 [?:] 在其左操作数求值为真时返回左操作数,否则返回右操作数:因此,如果表为空,[$row] 的值为空数组;
- 第 91 行:对每个常量,我们在 [$row] 中查找其所在列的值。[array_map] 函数作用于单个数组时会保留其键:我们得到数组 [constant name => value]。如果表为空,所有值都是 [null],而 [TaxAdminData::fromArray] 方法将报告无效值。
请注意,该类并不依赖于 MySQL DBMS。决定所用 DBMS 的是 [database.json] 文件,它通过数据库的 DSN 来指定。
13.4.4. [business] 层

- 我们刚刚实现了 [dao] 层 [3];
- 由于我们遵守了 [InterfaceDao] 接口,[business] 层 [2] 可以保持不变。然而,PHP 7 课程不得不修改它,因为当时各层之间交换的实体也发生了变化:[executeBatchTaxes] 方法使用了版本 4 中 [TaxPayerData] 类的 setter,而这些 setter 已被移除。这里,实体没有变化。
因此,版本 4 的 [InterfaceBusiness] 接口和 [Business] 类原样纳入 [Business] 文件夹,不做任何修改。回顾一下 [executeBatchTaxes] 方法:
| // 批处理模式下的税款计算
// --------------------------------------------------------------------------
#[\Override]
public function executeBatchTaxes(string $taxPayersFileName, string $resultsFileName, string $errorsFileName): void
{
// 我们让来自 [dao] 层的异常向上传递
// 我们获取纳税人数据
$taxPayersData = $this->dao->getTaxPayersData($taxPayersFileName, $errorsFileName);
// 我们计算每位纳税人的税款
$results = array_map(
fn(TaxPayerData $taxPayerData): TaxPayerData => $taxPayerData->withResults(
$this->calculateTax($taxPayerData->married, $taxPayerData->children, $taxPayerData->salary)
),
$taxPayersData
);
// 保存结果
$this->dao->saveResults($resultsFileName, $results);
}
}
|
- 第 192 行:[business] 层并不知道纳税人数据现在来自 JSON 文件:它向 [dao] 层请求数据,并像版本 4 中一样收到一个 [TaxPayerData] 对象的数组;
- 第 201 行:同样,它也不知道结果是以 JSON 格式保存的。
13.4.5. 主脚本

- 我们刚刚实现了 [dao] [3] 和 [business] [2] 层;
- 我们还需要编写主脚本 [1]。
主脚本 [Main/MainCalculateTaxWithTaxAdminDataInMySQLDatabase.php] 与版本 4 中的类似:
| <?php
// 严格遵守所声明的函数参数和结果的类型
declare(strict_types=1);
// 命名空间
namespace Application;
// 引入这些接口和类
require_once __DIR__ . "/../Entities/TaxException.php";
require_once __DIR__ . "/../Entities/TaxAdminData.php";
require_once __DIR__ . "/../Entities/TaxPayerData.php";
require_once __DIR__ . "/../Entities/Database.php";
require_once __DIR__ . "/../Utilities/Utilities.php";
require_once __DIR__ . "/../Dao/InterfaceDao.php";
require_once __DIR__ . "/../Dao/TraitDao.php";
require_once __DIR__ . "/../Dao/DaoTaxWithTaxAdminDataInDatabase.php";
require_once __DIR__ . "/../Business/InterfaceBusiness.php";
require_once __DIR__ . "/../Business/Business.php";
// 常量的定义
const DATABASE_CONFIG_FILENAME = __DIR__ . "/../Data/database.json";
const TAXPAYERSDATA_FILENAME = __DIR__ . "/../Data/taxpayersdata.json";
const RESULTS_FILENAME = __DIR__ . "/../Data/results.json";
const ERRORS_FILENAME = __DIR__ . "/../Data/errors.json";
try {
// 创建 [dao] 层
$dao = new DaoTaxWithTaxAdminDataInDatabase(DATABASE_CONFIG_FILENAME);
// 创建 [business] 层
$business = new Business($dao);
// 批处理模式下的税款计算
$business->executeBatchTaxes(TAXPAYERSDATA_FILENAME, RESULTS_FILENAME, ERRORS_FILENAME);
print "The results have been saved in the file [results.json]\n";
} catch (TaxException $ex) {
// 我们显示错误
print "Error no. {$ex->getCode()}: {$ex->getMessage()}\n";
}
// 结束
print "Done\n";
|
说明
- 第 10–19 行:加载计算税款所需的所有文件;
- 第 22–25 行:应用程序中各个 JSON 文件的名称;
- 第 29 行:构造 [dao] 层;
- 第 31 行:构造 [business] 层;
- 第 33 行:调用 [executeBatchTaxes] 方法,该方法属于 [business] 层。
结果
| > php MainCalculateTaxWithTaxAdminDataInMySQLDatabase.php
The results have been saved in the file [results.json]
Done
|
应用程序在 [Data] 文件夹中生成两个 JSON 文件:
- [results.json]:各项税款计算的结果;
- [errors.json]:报告在 JSON 文件 [taxpayersdata.json] 中发现的错误。
[errors.json] 文件如下:
| [
{
"number": 1,
"errors": [
{
"married": "yesx"
},
{
"children": "2x"
},
{
"salary": "55555x"
}
]
}
]
|
这表示在 [taxpayersdata.json] 中,纳税人表的 1 号条目是错误的,并说明了原因。结果文件 [results.json] 如下:
| [
{
"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
}
]
|
请注意,文件 [taxpayersdata.json] 中的 2 号纳税人,其子女数是字符串 "2",在结果中列出的子女数为 2(第 14 行):该字符串已被 [dao] 层转换为整数。这些结果与版本 4 的结果一致。
13.5. [PHPUnit] 测试
与版本 4 一样,我们将为版本 5 编写 [PHPUnit] 测试。它们位于 [version-05/Tests] 文件夹中。
13.5.1. [dao] 层测试
[Tests/DaoTest.php] 测试如下:
| <?php
// 严格遵守所声明的函数参数和结果的类型
declare(strict_types=1);
// 测试的命名空间
namespace Application\Tests;
// 被测试的类
use Application\DaoTaxWithTaxAdminDataInDatabase;
use Application\DaoTransferAdminDataFromJsonFile2Database;
use Application\TaxException;
use Application\InterfaceDao;
use Application\TaxAdminData;
use Application\TaxPayerData;
// PHPUnit 的类
use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\TestCase;
// 加载 [dao] 层的类
require_once __DIR__ . "/../Entities/TaxException.php";
require_once __DIR__ . "/../Entities/TaxAdminData.php";
require_once __DIR__ . "/../Entities/TaxPayerData.php";
require_once __DIR__ . "/../Entities/Database.php";
require_once __DIR__ . "/../Utilities/Utilities.php";
require_once __DIR__ . "/../Dao/InterfaceDao.php";
require_once __DIR__ . "/../Dao/TraitDao.php";
require_once __DIR__ . "/../Dao/DaoTaxWithTaxAdminDataInDatabase.php";
require_once __DIR__ . "/../Dao/InterfaceDao4TransferAdminData2Database.php";
require_once __DIR__ . "/../Dao/DaoTransferAdminDataFromJsonFile2Database.php";
final class DaoTest extends TestCase
{
// 版本 5 的数据文件夹
private const string DATA = __DIR__ . "/../Data";
// 被测试的 [dao] 层
private InterfaceDao $dao;
// 用于错误的临时文件
private string $errorsFilename;
// 在每个测试之前执行
#[\Override]
protected function setUp(): void
{
// 创建 [dao] 层
$this->dao = new DaoTaxWithTaxAdminDataInDatabase(self::DATA . "/database.json");
// 一个临时文件
$this->errorsFilename = tempnam(sys_get_temp_dir(), "errors");
}
// 在每个测试之后执行
#[\Override]
protected function tearDown(): void
{
// 删除临时文件
unlink($this->errorsFilename);
}
// 从数据库读取的税务管理部门数据
public function testTaxAdminData(): void
{
$taxAdminData = $this->dao->getTaxAdminData();
// 计算常量
$this->assertSame(1551.0, $taxAdminData->halfShareQfCeiling);
$this->assertSame(21037.0, $taxAdminData->singleIncomeCeilingForReduction);
$this->assertSame(42074.0, $taxAdminData->coupleIncomeCeilingForReduction);
$this->assertSame(3797.0, $taxAdminData->halfShareReductionValue);
$this->assertSame(1196.0, $taxAdminData->singleDiscountCeiling);
$this->assertSame(1970.0, $taxAdminData->coupleDiscountCeiling);
$this->assertSame(1595.0, $taxAdminData->singleTaxCeilingForDiscount);
$this->assertSame(2627.0, $taxAdminData->coupleTaxCeilingForDiscount);
$this->assertSame(12502.0, $taxAdminData->tenPercentAllowanceMax);
$this->assertSame(437.0, $taxAdminData->tenPercentAllowanceMin);
// 税率档
$this->assertSame([9964.0, 27519.0, 73779.0, 156244.0, 0.0], $taxAdminData->limits);
$this->assertSame([0.0, 0.14, 0.30, 0.41, 0.45], $taxAdminData->coeffR);
$this->assertSame([0.0, 1394.96, 5798.0, 13913.69, 20163.45], $taxAdminData->coeffN);
}
// 将 JSON 文件传输到数据库,然后重新读取数据库
public function testTransfer(): void
{
// 传输
(new DaoTransferAdminDataFromJsonFile2Database(self::DATA . "/database.json", self::DATA . "/taxadmindata.json"))
->transferAdminData2Database();
// 通过新的 [dao] 层重新读取数据库
$dao = new DaoTaxWithTaxAdminDataInDatabase(self::DATA . "/database.json");
// 数据库包含 JSON 文件的数据
$this->assertEquals(TaxAdminData::fromJsonFile(self::DATA . "/taxadmindata.json"), $dao->getTaxAdminData());
}
// 不正确的数据库描述
public static function invalidDatabases(): array
{
// [文件名, 预期的错误代码]
return [
"non-existent file" => ["nonexistent.json", 15],
"missing key" => ["database-incomplete.json", 21],
"wrong password" => ["database-wrong-pwd.json", 30],
];
}
#[DataProvider("invalidDatabases")]
public function testInvalidDatabases(string $file, int $code): void
{
// 我们期望得到带特定代码的 [TaxException] 异常
$this->expectException(TaxException::class);
$this->expectExceptionCode($code);
// 使用不正确的数据库描述构建 [dao] 层
new DaoTaxWithTaxAdminDataInDatabase(__DIR__ . "/data/$file");
}
// 从 JSON 文件读取的纳税人数据
public function testTaxPayersData(): void
{
$taxPayersData = $this->dao->getTaxPayersData(self::DATA . "/taxpayersdata.json", $this->errorsFilename);
// 11 位正确的纳税人
$this->assertCount(11, $taxPayersData);
$this->assertContainsOnlyInstancesOf(TaxPayerData::class, $taxPayersData);
// 第一位和最后一位
$this->assertEquals(new TaxPayerData("yes", 2, 55555), $taxPayersData[0]);
$this->assertEquals(new TaxPayerData("yes", 3, 200000), $taxPayersData[10]);
// JSON 文件中的 1 号纳税人不正确
$errors = json_decode(file_get_contents($this->errorsFilename), true);
$this->assertSame([
["number" => 1, "errors" => [["married" => "yesx"], ["children" => "2x"], ["salary" => "55555x"]]],
], $errors);
}
// 不存在的纳税人文件
public function testNonExistentTaxPayersData(): void
{
$this->expectException(TaxException::class);
$this->expectExceptionCode(15);
$this->dao->getTaxPayersData(self::DATA . "/nonexistent.json", $this->errorsFilename);
}
}
|
说明
- 第 21–30 行:定义测试环境。我们加载版本 5 中两个 [dao] 层的文件:传送层和税款计算层;
- 第 43–49 行:每个测试之前,我们像主脚本那样,使用 [dao] 层和 [Data/database.json] 文件来构造它;
- 第 60 行:[testTaxAdminData] 方法与版本 4 中的相同。不过这一次,被测试的数据是从数据库读取的;
- 第 81–90 行:我们测试将 JSON 文件传送到数据库,然后使用一个新的 [dao] 层再次读取数据库。得到的 [TaxAdminData] 对象必须与根据 JSON 文件构造的对象相等([assertEquals])。这个测试假定传送已成功把文件 [taxadmindata.json] 中的数据载入数据库:它不会修改其他测试所期望的数据;
- 第 93–101 行:三个不正确的数据库描述:一个不存在的文件(代码 15)、一个名为 [database-incomplete.json] 且缺少键 [colCoeffN] 的文件(代码 21),以及一个名为 [database-wrong-pwd.json] 且密码不正确的文件(代码 30)。后两个文件位于 [Tests/data] 文件夹中;
- 第 104–111 行:我们验证,使用不正确的描述创建的名为 [dao] 的层会抛出带有正确错误代码的 [TaxException] 异常;
- 第 114–128 行:从 JSON 文件读取纳税人数据。我们验证所获取的纳税人数量以及第一条和最后一条记录的内容,然后验证错误文件的确切内容;
- 第 131 行:不存在的纳税人文件应当触发代码为 15 的异常。
13.5.2. [business] 层的测试
[Tests/BusinessTest.php] 测试与版本 4 相对应。只有测试环境发生了变化:
| <?php
// 严格遵守所声明的函数参数和结果的类型
declare(strict_types=1);
// 测试的命名空间
namespace Application\Tests;
// 被测试的类
use Application\DaoTaxWithTaxAdminDataInDatabase;
use Application\InterfaceBusiness;
use Application\Business;
// PHPUnit 的类
use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\TestCase;
// 加载 [dao] 层和 [business] 层的类
require_once __DIR__ . "/../Entities/TaxException.php";
require_once __DIR__ . "/../Entities/TaxAdminData.php";
require_once __DIR__ . "/../Entities/TaxPayerData.php";
require_once __DIR__ . "/../Entities/Database.php";
require_once __DIR__ . "/../Utilities/Utilities.php";
require_once __DIR__ . "/../Dao/InterfaceDao.php";
require_once __DIR__ . "/../Dao/TraitDao.php";
require_once __DIR__ . "/../Dao/DaoTaxWithTaxAdminDataInDatabase.php";
require_once __DIR__ . "/../Business/InterfaceBusiness.php";
require_once __DIR__ . "/../Business/Business.php";
final class BusinessTest extends TestCase
{
// 版本 5 的数据文件夹
private const string DATA = __DIR__ . "/../Data";
// 被测试的 [business] 层
private InterfaceBusiness $business;
// 在每个测试之前执行
#[\Override]
protected function setUp(): void
{
// 创建 [dao] 层
$dao = new DaoTaxWithTaxAdminDataInDatabase(self::DATA . "/database.json");
// 创建 [business] 层
$this->business = new Business($dao);
}
|
- 第 10 行:所用 [dao] 层的类;
- 第 18–27 行:加载的文件,即来自主脚本 [MainCalculateTaxWithTaxAdminDataInMySQLDatabase] 的文件;
- 第 41 行:[business] 层构建在读取数据库的 [dao] 层之上。
数据提供者 [taxpayers] 和方法 [testCalculateTax] 与版本 4 中的相同。
13.5.3. 运行测试
必须启动 MySQL DBMS([Laragon] / Start All)。测试在 [php8-oct-2026] 文件夹中打开的终端里运行:
| > php vendor/bin/phpunit scripts-console/tax/version-05/Tests --testdox
PHPUnit 12.5.37 by Sebastian Bergmann and contributors.
Runtime: PHP 8.5.11
Configuration: .../php8-oct-2026/phpunit.xml
.................. 18 / 18 (100%)
Time: 00:00.035, Memory: 16.00 MB
Business (Application\Tests\Business)
✔ 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"
Dao (Application\Tests\Dao)
✔ Tax admin data
✔ Transfer
✔ Invalid databases with data set "non-existent file"
✔ Invalid databases with data set "missing key"
✔ Invalid databases with data set "wrong password"
✔ Tax payers data
✔ Non existent tax payers data
OK (18 tests, 49 assertions)
|
全部 18 个测试通过:[dao] 层的 7 个测试(其中 [invalidDatabases] 提供者占 3 个)和 [business] 层的 11 个测试。