Skip to content

11. 应用练习——版本 4

税款计算应用程序现在将实现如下的分层结构:

Image

我们将复用版本 3 中的组件,并修改它们以适应应用程序的新架构。这称为“重构”(reworking the code)。这里,我们假定应用程序所需的数据存储在文本文件中。[dao] 层将处理与这些文件的交互。

11.1. 脚本目录结构

版本 4 位于 [scripts-console/tax/version-04] 文件夹中:

version-04
├── Tests
│   ├── data
│   │   ├── missing-key.json
│   │   ├── negative-value.json
│   │   └── syntax.json
│   ├── BusinessTest.php
│   └── DaoTest.php
├── Business.php
├── DaoTaxWithTaxAdminDataInJsonFile.php
├── errors.txt
├── InterfaceBusiness.php
├── InterfaceDao.php
├── main.php
├── results.txt
├── taxadmindata.json
├── TaxAdminData.php
├── TaxException.php
├── TaxPayerData.php
├── taxpayersdata.txt
├── TraitDao.php
└── Utilities.php

[Tests] 文件夹包含版本 4 的自动化测试,我们将在本章末尾介绍。

11.2. 层与层之间交换的对象

我们原样保留版本 3 中的某些元素:

  • [TaxException] 异常是 [dao] 层在遇到数据访问问题或数据性质问题(数据不正确)时抛出的异常;
  • [Utilities] 类包含对管理文本文件有用的方法(这里只有一个方法 [cutNewLineChar]);
  • [readonly] 类 [TaxAdminData] 封装了税务机关的数据。它通过静态方法 [TaxAdminData::fromJsonFile($taxAdminDataFilename)] (或 [TaxAdminData::fromArray($data)])获得,该方法验证数据,并在数据无效时抛出 [TaxException] 异常。

我们新增一个类 [TaxPayerData], 它封装纳税人的数据及其税款计算结果([TaxPayerData.php]):

<?php

declare(strict_types=1);

// 命名空间
namespace Application;

// 纳税人的数据及其税款计算的结果:一个不可变对象
final readonly class TaxPayerData
{
    public function __construct(
        // 计算纳税人税款所需的数据
        public string $married,
        public int $children,
        public int $salary,
        // 税款计算的结果(在税款尚未计算之前为 null)
        public ?int $tax = null,
        public ?int $surcharge = null,
        public ?int $discount = null,
        public ?int $reduction = null,
        public ?float $rate = null,
    ) {
    }

    // 返回补充了税款计算结果的对象副本
    // $results:由 [business] 层返回的数组 [tax, surcharge, discount, reduction, rate]
    public function withResults(array $results): static
    {
        return clone($this, [
            "tax" => $results["tax"],
            "surcharge" => $results["surcharge"],
            "discount" => $results["discount"],
            "reduction" => $results["reduction"],
            "rate" => $results["rate"],
        ]);
    }

    // 对象的 JSON 字符串
    public function __toString(): string
    {
        return json_encode(get_object_vars($this), JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
    }
}

说明

  • 第 9 行:与 [TaxAdminData] 一样,[TaxPayerData] 类是不可变的:它的对象在层与层之间传递,不用担心在途中被修改;
  • 第 13–15 行:计算纳税人税款所需的纳税人数据;
  • 第 17–21 行:税款计算的结果。这些是可空字段([?int]、[?float]),默认值为 [null]:[TaxPayerData] 对象首先由 [dao] 层创建,只包含来自 [new TaxPayerData("yes", 2, 55555)] 的纳税人数据,因为税款尚未计算。属性名与版本 3 结果文件中 JSON 键的名称相同:因此 [results.txt] 文件将保持相同的格式;
  • 第 27–36 行:由于对象是不可变的,计算结果无法添加到其中。方法 [withResults] 返回补充了结果的对象的 副本 。它使用 PHP 8.5 的 [clone] 运算符,该运算符接受一个数组作为第二个参数,数组中是要在副本中修改的属性(参见类一章)。PHP 7 课程使用的是带有八个 getter 和八个 setter 的可修改对象;
  • 第 39–42 行:[__toString] 方法返回对象的 JSON 字符串。它将用于写入结果文件。

11.3. [dao] 层

这里我们关注应用程序的 [1] 层:

Image

11.3.1. [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;
}

说明

  • 规格如下:
    • 纳税人数据存储在文本文件中;
    • 税款计算的结果保存在文本文件中;
    • 所有错误都保存在文本文件中;
    • 税务机关的数据以何种格式提供是未知的。对于每种新格式,都必须由新的类来实现 [InterfaceDao] 接口;
    • 在访问数据时遇到致命错误的接口方法,必须抛出 [TaxException] 异常;
  • 第 15 行:获取纳税人数据 [marital status, number of children, annual salary] 的方法:
    • 第一个参数是包含这些数据的文本文件的名称;
    • 第二个参数是用于记录所遇到的任何错误的文本文件的名称;
  • 第 14 行:类型 [array] 并未说明数组包含什么。[/** @return TaxPayerData[] */] (PHPDoc 语法)的文档注释指明它是 [TaxPayerData] 对象的数组。PHP 会忽略它,但 [PHP Intelephense] 扩展(属于 [VS Code] )会使用它:这样它就知道数组元素的类型,并能在输入数据时提示其属性;
  • 第 18 行:获取税务机关数据的方法。不向它传递任何参数,因为我们不知道这些数据是如何存储的;
  • 第 22 行:把税款计算结果保存到文本文件的方法,文件名作为参数传入。

在编写 [InterfaceDao] 接口时,我们知道,根据税务机关数据的存储方式,会有不同的方式来实现 [getTaxAdminData] 方法。因此 [InterfaceDao] 接口将由不同的类来实现,每个类处理这些数据的一种特定存储方式(JSON 文件、数据库、Web 服务)。不过,这些类会共享公共代码:[getTaxPayersData] 和 [saveResults] 方法的实现。正如我们在 trait 一章中所见,这种用例可以用两种方式实现:

  • 我们创建一个抽象类 C,其中包含派生类共有的代码。类 C 实现接口 I,但某些方法(必须在派生类中定义)在类 C 中被声明为抽象方法,因此类 C 本身也是抽象的。然后我们创建派生自 C 的类 C1 和 C2,它们各自以自己的方式实现其父类 C 的抽象方法;
  • 我们创建一个 trait T,它与上一种方案中的抽象类 C 几乎完全相同。该 trait 不实现接口 I,因为在语法上它做不到。然后我们创建类 C1 和 C2,它们实现接口 I 并使用 trait T。这些类剩下要做的,就是实现接口 I 中未由它们所导入的 trait T 实现的那些方法。

在这个示例中,我们将使用 trait [TraitDao]。版本 3 使用的是抽象类。

11.3.2. trait [TraitDao]

trait [TraitDao] 的代码如下:[TraitDao.php]:

<?php

declare(strict_types=1);

// 命名空间
namespace Application;

// 实现 [InterfaceDao] 中处理文本文件的方法
trait TraitDao
{
    // 纳税人文件中一行的字段分隔符(trait 常量,PHP 8.2)
    private const string SEPARATOR = ",";

    // 读取纳税人数据
    #[\Override]
    public function getTaxPayersData(string $taxPayersFilename, string $errorsFilename): array
    {
        // 纳税人数据的数组
        $taxPayersData = [];
        // 错误的数组
        $errors = [];
        // 打开纳税人数据文件
        $taxPayersFile = is_readable($taxPayersFilename) ? fopen($taxPayersFilename, "r") : false;
        if ($taxPayersFile === false) {
            throw new TaxException("Unable to open the taxpayers' declarations [$taxPayersFilename] for reading", 12);
        }
        // 文件已打开:无论发生什么,我们都必须关闭它
        try {
            // 我们处理纳税人数据文件的当前行
            // 其格式为婚姻状况、子女数、年薪
            $num = 0;  // 当前行的编号
            while (($line = fgets($taxPayersFile, 100)) !== false) {
                // 多了一行
                $num++;
                // 我们删除可能存在的行尾标记
                $line = Utilities::cutNewLineChar($line);
                // 我们忽略空行
                if (trim($line) === "") {
                    continue;
                }
                // 该行必须有 3 个字段 married,children,salary
                $fields = array_map(trim(...), explode(self::SEPARATOR, $line));
                $error = count($fields) !== 3;
                if (!$error) {
                    [$married, $children, $salary] = $fields;
                    // 婚姻状况必须是 yes 或 no
                    $married = strtolower($married);
                    // 子女数和工资必须是正整数或零
                    $error = !in_array($married, ["yes", "no"], true)
                        || !preg_match('/^\d+$/', $children)
                        || !preg_match('/^\d+$/', $salary);
                }
                // 出错?
                if ($error) {
                    $errors[] = "line [$num] of the file [$taxPayersFilename] is incorrect";
                } else {
                    // 我们存储纳税人的数据
                    $taxPayersData[] = new TaxPayerData($married, (int) $children, (int) $salary);
                }
            }
            // 到文件末尾了吗?
            if (!feof($taxPayersFile)) {
                // 我们因读取错误而退出了循环
                throw new TaxException("Error while reading the line no. [" . ($num + 1) . "] of the file [$taxPayersFilename]", 13);
            }
        } finally {
            // 我们关闭文件
            fclose($taxPayersFile);
        }
        // 我们将错误保存到文本文件中
        $this->saveLines($errorsFilename, $errors);
        // 函数的结果
        return $taxPayersData;
    }

    // 保存结果
    #[\Override]
    public function saveResults(string $resultsFilename, array $taxPayersData): void
    {
        // 每个 [TaxPayerData] 元素通过其 [__toString] 方法转换为 JSON 字符串
        $this->saveLines($resultsFilename, array_map(strval(...), $taxPayersData));
    }

    // 将行数组保存到文本文件中
    private function saveLines(string $fileName, array $lines): void
    {
        // 如果文本文件 [$fileName] 不存在,则创建它,否则覆盖它
        $data = implode("", array_map(fn(string $line): string => "$line\n", $lines));
        if (@file_put_contents($fileName, $data) === false) {
            throw new TaxException("Error while saving data to the text file [$fileName]", 14);
        }
    }
}

说明

  • 第 9 行:这里我们定义的是 trait,而不是类;
  • 第 12 行:一个字段分隔符常量(PHP 8.2),带类型(PHP 8.3):纳税人文件中一行的字段分隔符。它成为使用该 trait 的类的常量,并以 [self::SEPARATOR] 的写法使用;
  • 第 15 行:从 PHP 8.3 开始,trait 方法上可以使用属性 [#[\Override]] 。这会在使用该 trait 的类中得到验证:这里,该方法必须对应于该类所实现的 [InterfaceDao] 接口的某个方法;
  • 第 16–74 行:方法 [getTaxPayersData] 实现 [InterfaceDao] 接口中的同名方法。它从名为 [$taxPayersFilename] 的文本文件中获取纳税人的数据 [marital status, number of children, annual salary]。它以包含 [$taxPayersData] 类型元素 [TaxPayerData] 的数组的形式返回这些数据(第 58 行);
  • 方法 [getTaxPayersData] 与版本 3 中的方法 [AbstractBaseTax::executeBatchTaxes] 非常相似,区别如下:
    • [getTaxPayersData] 方法只获取纳税人数据。它不执行任何税款计算:那是 [business] 层的职责;
    • 与 [executeBatchTaxes] 方法一样,它会标出有错误的行。这里,错误首先存储在名为 [$errors] 的数组中,该数组在处理结束时写入文本文件(第 71 行)。视情况不同,这个数组可能为空,也可能不为空。错误的行不再触发异常:由调用方代码来查阅错误文件;
    • 发生致命错误时,会抛出 [TaxException] 异常(第 25 行、第 64 行);
  • 第 23–26 行:文件是先于[try / finally] 结构而打开的。如果打开文件失败,就抛出异常,而且没有需要关闭的东西。如果成功,[finally] 子句(第 66–69 行)会确保无论是否发生异常,文件都会被关闭。这种做法避免了版本 3 中的“文件是否已打开?”检查;
  • 第 62–65 行:请注意退出读取循环时所做的处理。函数 [fgets] 有个缺点:当读取到达文件末尾时,以及因错误而读取失败时,它都会返回 [false] 。为了区分这两种情况,我们使用函数 [feof] 检查是否已到达文件末尾。如果没有,就说明发生了错误,于是抛出异常;
  • 第 78–82 行:[saveResults] 方法的实现,该方法属于 [InterfaceDao] 接口。数组中的每个 [TaxPayerData] 元素都由函数 [strval] 转换为字符串,该函数会调用对象的 [__toString] 方法:由此得到它的 JSON 字符串。[strval(...)] 引用 [strval] 函数本身(一等可调用对象,PHP 8.1);
  • 第 85–92 行:私有方法 [saveLines] 把一个由行组成的数组写入文本文件,每行以行尾字符 \n 结束;
  • 第 89 行:PHP 函数 [file_put_contents] 把字符串写入文本文件。它打开文件,写入字符串,然后关闭文件。如果发生错误,它返回 [false] 。此时 PHP 还会发出一个警告。[@] 运算符会抑制这个警告:错误通过下一行抛出的异常来报告,其消息更清晰。

trait [TraitDao] 已经实现了 [InterfaceDao] 接口的两个方法:[getTaxPayersData] 和 [saveResults]。我们还需要实现 [getTaxAdminData] 方法,它用于获取税务机关的数据。

11.3.3. [DaoTaxWithTaxAdminDataInJsonFile] 类

[DaoTaxWithTaxAdminDataInJsonFile] 类按如下方式实现 [InterfaceDao] 接口:

<?php

declare(strict_types=1);

// 命名空间
namespace Application;

// 从 JSON 文件中获取税务管理部门数据的 [dao] 层
class DaoTaxWithTaxAdminDataInJsonFile implements InterfaceDao
{
    // 该 trait 实现了接口的 [getTaxPayersData] 和 [saveResults] 方法
    use TraitDao;

    // 包含税务管理部门数据的 [TaxAdminData] 类型的对象
    private readonly TaxAdminData $taxAdminData;

    // 构造函数
    public function __construct(string $taxAdminDataFilename)
    {
        // 可能抛出 [TaxException] 异常
        $this->taxAdminData = TaxAdminData::fromJsonFile($taxAdminDataFilename);
    }

    // 返回用于计算税款的数据
    #[\Override]
    public function getTaxAdminData(): TaxAdminData
    {
        return $this->taxAdminData;
    }
}

说明

  • 第 9 行:类 [DaoTaxWithTaxAdminDataInJsonFile] 实现接口 [InterfaceDao];
  • 第 12 行:该类使用 [TraitDao] trait,我们知道它实现了 [getTaxPayersData] 和 [saveResults] 方法,这两个方法属于 [InterfaceDao] 接口。该类剩下要做的,就是实现 [getTaxAdminData] 方法,它用于获取税务机关的数据;
  • 第 15 行:类型为 [TaxAdminData] 的属性,由 [getTaxAdminData] 方法返回。它由构造函数初始化;
  • 第 21 行:税务机关的数据从 JSON 文件中读取。如果文件缺失或无效,就会向调用方代码抛出 [TaxException] 异常。

至此我们完成了应用程序的 [dao] 层:我们有了一个完整实现我们自己定义的 [InterfaceDao] 接口的类。现在可以转向 [business] 层了。

11.4. [business] 层

现在我们来实现架构中的 [2] 层:

Image

11.4.1. [InterfaceBusiness] 接口

[business] 层的接口如下:[InterfaceBusiness.php]:

<?php

declare(strict_types=1);

// 命名空间
namespace Application;

// [business] 层的接口
interface InterfaceBusiness
{
    // 计算一位纳税人的税款
    // 返回数组 [tax, surcharge, discount, reduction, rate]
    public function calculateTax(string $married, int $children, int $salary): array;

    // 批处理模式下的税款计算
    // 可能抛出来自 [dao] 层并向上传递的 [TaxException] 异常
    public function executeBatchTaxes(string $taxPayersFileName, string $resultsFileName, string $errorsFileName): void;
}

说明

  • 第 13 行:只要给出以下信息:婚姻状况、子女数和年薪,[business] 层就可以计算特定纳税人的税额。[calculateTax] 方法纯粹是“业务”方法:它不关心所用数据的来源。它不使用 [dao] 层,因此不会抛出异常;
  • 第 17 行:[business] 层还可以计算一组纳税人的税额,这些纳税人的数据汇集在名为 [$taxPayersFileName] 的文本文件中。它把结果写入名为 [$resultsFileName] 的文本文件。非致命错误记录在名为 [$errorsFileName] 的文本文件中。方法 [executeBatchTaxes] 必须调用负责文件系统访问的 [dao] 层。这样异常就可能从 [dao] 层传播出来:[executeBatchTaxes] 方法不会捕获它们,而是让它们传播到主脚本。

11.4.2. [Business] 类

[Business] 类按如下方式实现 [InterfaceBusiness] 接口:

<?php

declare(strict_types=1);

// 命名空间
namespace Application;

// [business] 层
class Business implements InterfaceBusiness
{
    // 税务管理部门的数据
    private readonly TaxAdminData $taxAdminData;

    // [dao] 层由构造函数注入
    public function __construct(private readonly InterfaceDao $dao)
    {
        // 我们获取用于计算税款的数据
        // [getTaxAdminData] 方法可能抛出 [TaxException] 异常
        // 我们随后让它向上传递给调用代码
        $this->taxAdminData = $this->dao->getTaxAdminData();
    }

    // 税款计算
    // --------------------------------------------------------------------------
    #[\Override]
    public function calculateTax(string $married, int $children, int $salary): array
    {
        // $married:是、否
        // $children:子女数
        // $salary:年薪
        // $this->taxAdminData:税务管理部门的数据
        //
        // 计算有子女时的税款
        $result1 = $this->calculateTax2($married, $children, $salary);
        $tax1 = $result1["tax"];
        // 计算没有子女时的税款
        if ($children !== 0) {
            $result2 = $this->calculateTax2($married, 0, $salary);
            $tax2 = $result2["tax"];
            // 应用家庭系数上限
            $halfShareCeiling = $this->taxAdminData->halfShareQfCeiling;
            if ($children < 3) {
                // 前 2 个子女适用 halfShareQfCeiling 欧元
                $tax2 = $tax2 - $children * $halfShareCeiling;
            } else {
                // 前 2 个子女适用 halfShareQfCeiling 欧元,之后的子女加倍
                $tax2 = $tax2 - 2 * $halfShareCeiling - ($children - 2) * 2 * $halfShareCeiling;
            }
        } else {
            $tax2 = $tax1;
            $result2 = $result1;
        }
        // 我们取较高的税款及其对应的税率和速算扣除数
        if ($tax1 > $tax2) {
            $tax = $tax1;
            $rate = $result1["rate"];
            $surcharge = $result1["surcharge"];
        } else {
            $surcharge = $tax2 - $tax1 + $result2["surcharge"];
            $tax = $tax2;
            $rate = $result2["rate"];
        }
        // 计算可能的减免
        $discount = $this->getDiscount($married, $salary, $tax);
        $tax -= $discount;
        // 计算可能的税额减免
        $reduction = $this->getReduction($married, $salary, $children, $tax);
        $tax -= $reduction;
        // 结果
        return [
            "tax" => (int) floor($tax),
            "surcharge" => (int) $surcharge,
            "discount" => (int) $discount,
            "reduction" => (int) $reduction,
            "rate" => $rate,
        ];
    }

说明

  • 第 9 行:[Business] 类实现 [InterfaceBusiness] 接口,即 [calculateTax] 和 [executeBatchTaxes] 方法;
  • 第 12 行:类型为 [TaxAdminData], 的对象,封装税务管理数据。业务方法 [calculateTax] 需要这些数据;
  • 第 15–21 行:构造函数初始化该类的两个属性:
    • 属性 [$dao],即对 [dao] 层的引用,通过构造函数参数提升来初始化。这是必要的,这样 [business] 层在需要外部数据时才知道该找谁。请注意,该参数的类型是 [InterfaceDao] 接口的类型,从而使 [Business] 类能够与任何实现该接口的类协同工作。PHP 7 课程还提供了 [setDao] setter:现在已不再有它,因为 [dao] 层由构造函数一次性注入;
    • [$taxAdminData] 属性通过调用 [getTaxAdminData] 方法来初始化,该方法属于 [dao] 层;
  • 我们得出结论:当方法 [calculateTax] 和 [executeBatchTaxes] 执行时,属性 [$dao] 和 [$taxAdminData] 都已初始化。版本 3 中的 [$this->taxAdminData ??= $this->getTaxAdminData()] 测试已不再必要;
  • 第 26–77 行:这段代码来自版本 3 中的 [AbstractBaseTax::calculateTax] 方法。私有方法 [calculateTax2], [getTaxableIncome], [getDiscount] 和 [getReduction]也是如此,这里不再重复列出。

方法 [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);
    }
}

说明

  • 第 188 行:该方法必须对名为 [$taxPayersFileName] 的文本文件中的每位纳税人,重复调用 [calculateTax] 方法,并把结果写入名为 [$resultsFileName] 的文本文件。遇到的任何非致命错误都记录在名为 [$errorsFileName] 的文本文件中。该方法本身不抛出任何异常,而是让 [dao] 层抛出的异常继续传播;
  • 第 192 行:向 [dao] 层请求纳税人数据。该层返回 [TaxPayerData] 类型元素的数组。如果这里发生异常,由于没有被 [catch] 捕获,它会自动传播给调用方代码,方法的其余部分不会被执行;
  • 第 194–199 行:函数 [array_map] 对数组 [$taxPayersData] 的每个元素应用一个函数,并返回结果数组。所应用的函数是一个箭头函数,它计算纳税人 [$taxPayerData] 的税款,并返回填入了计算结果的 [$taxPayerData] 的副本(第 195 行)。请注意,箭头函数使用了 [$this]:箭头函数会自动捕获其上下文中的变量,包括 [$this];
  • 第 201 行:为所有纳税人计算出税款后,结果被保存到文本文件中。这项任务由 [dao] 层执行。

总的来说,[business] 层写起来相当简单,因为它与 [dao] 层通信,而数据访问及相关的错误处理都由后者负责。

11.5. 主脚本

现在我们来编写架构中 [3] 层的脚本:

Image

主脚本如下:[main.php]:

<?php

// 严格遵守所声明的函数参数和结果的类型
declare(strict_types=1);

// 命名空间
namespace Application;

// 引入这些接口和类
require_once __DIR__ . "/TaxException.php";
require_once __DIR__ . "/Utilities.php";
require_once __DIR__ . "/TaxAdminData.php";
require_once __DIR__ . "/TaxPayerData.php";
require_once __DIR__ . "/InterfaceDao.php";
require_once __DIR__ . "/TraitDao.php";
require_once __DIR__ . "/DaoTaxWithTaxAdminDataInJsonFile.php";
require_once __DIR__ . "/InterfaceBusiness.php";
require_once __DIR__ . "/Business.php";

// 常量的定义
const TAXPAYERSDATA_FILENAME = "taxpayersdata.txt";
const RESULTS_FILENAME = "results.txt";
const ERRORS_FILENAME = "errors.txt";
const TAXADMINDATA_FILENAME = "taxadmindata.json";

try {
    // 创建 [dao] 层
    $dao = new DaoTaxWithTaxAdminDataInJsonFile(TAXADMINDATA_FILENAME);
    // 创建 [business] 层
    $business = new Business($dao);
    // 批处理模式下的税款计算
    $business->executeBatchTaxes(TAXPAYERSDATA_FILENAME, RESULTS_FILENAME, ERRORS_FILENAME);
    print "The results have been saved in the file [" . RESULTS_FILENAME . "]\n";
} catch (TaxException $ex) {
    // 我们显示错误
    print "Error no. {$ex->getCode()}: {$ex->getMessage()}\n";
}
// 结束
print "Done\n";

说明

  • 第 10–18 行:加载应用程序的类、接口和 trait。trait 必须先于使用它的类加载;
  • 第 21 行:纳税人数据文件的名称;
  • 第 22 行:结果文件的名称;
  • 第 23 行:错误文件的名称;
  • 第 24 行:包含税务机关数据的 JSON 文件的名称;
  • 第 28 行:创建 [dao] 层;
  • 第 30 行:基于 [dao] 层创建 [business] 层;
  • 第 32 行:执行 [business] 层的 [executeBatchTaxes] 方法;
  • 第 34–37 行:正如我们所见,[dao] 层和 [business] 层都可能抛出异常。这些异常在这里被拦截。

11.6. 可视化测试

11.6.1. 测试 1

在 [version-04] 文件夹中打开的终端窗口里运行脚本 [main.php] :

1
2
3
> php main.php
The results have been saved in the file [results.txt]
Done

使用版本 3 的纳税人文件 [taxpayersdata.txt] :

yes,2,55555
yes,2,50000
yes,3,50000
no,2,100000
no,3x,100000
no,3,100000
yes,3,100000
yes,5,100000x
yes,5,100000
no,0,100000
yes,2,30000
no,0,200000
yes,3,200000

会生成如下错误文件 [errors.txt]:

line [5] of the file [taxpayersdata.txt] is incorrect
line [8] of the file [taxpayersdata.txt] is incorrect

以及如下结果文件 [results.txt]:

{"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}
{"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}

这些就是版本 3 的结果。

11.6.2. 测试 2

在主脚本中,我们给纳税人文件指定一个不存在的文件名:

const TAXPAYERSDATA_FILENAME = "taxpayersdata2.txt";

控制台中显示的结果如下:

1
2
3
> php main.php
Error no. 12: Unable to open the taxpayers' declarations [taxpayersdata2.txt] for reading
Done

只显示 [dao] 层抛出的异常消息。在 PHP 7 课程中,对不存在的文件调用了函数 [fopen] :PHP 解释器随后在异常消息之前显示了一条警告:

Warning: fopen(taxpayersdata2.txt): failed to open stream: No such file or directory in ...

PHP 7 课程通过 [ini_set("display_errors", "0")] 语句指示 PHP 不显示错误,从而抑制了这条消息。这对生产服务器来说是正确的配置(错误随后被写入日志文件),但在开发期间,需要看到 PHP 的所有消息。因此我们宁可不触发这个警告:[dao] 层在打开文件之前,使用 [is_readable] 函数验证该文件是否可读。

11.7. [PHPUnit] 测试

可视化测试远远不够:

  • 我们通常只做几个测试;
  • 在这种目视检查中我们可能没有仔细留意,细节可能会从眼皮底下溜走。

在真实的专业开发中,测试是以代码形式编写的,并且常常在每次代码改动后自动运行。目标是让测试尽可能全面。为此,我们使用测试框架。

这里我们将使用 [PHPUnit] [https://phpunit.de/],PHP 中的标准测试框架。PHP 7 课程使用的是 [Codeception] 框架,选择它是因为它与 NetBeans IDE 集成,顺便说一句,它在幕后也使用了 PHPUnit。我们只会用到 PHPUnit 功能的一小部分。目的是在应用练习的每个新版本完成之后,有一种快速的方式来验证它能否工作。通过的测试让开发者对自己写的代码有信心。这是一个重要因素。

11.7.1. 安装 [PHPUnit]

与许多 PHP 库一样,[PHPUnit] 通过 [Composer] 安装,Composer 是 PHP 的依赖管理器,包含在 [Laragon] 中。包含课程代码的 [php8-oct-2026] 文件夹中有一个名为 [composer.json] 的文件,列出了课程所用的库。PHPUnit 出现在其 [require-dev] 部分,该部分包含仅用于开发的库:

1
2
3
    "require-dev": {
        "phpunit/phpunit": "^12.0"
    },

如果你还没有这样做,只需在 [php8-oct-2026] 文件夹中打开终端,并输入下面的命令:

composer install

[Composer] 随后会把 [composer.json] 中列出的所有库下载到 [vendor] 文件夹中,该文件夹位于 [php8-oct-2026] 内。PHPUnit 连同它的可执行文件 [vendor/bin/phpunit] 都安装在那里。在尚未安装 PHPUnit 的项目中,可以使用 [composer require --dev phpunit/phpunit] 命令添加它,该命令会下载它并把它登记到 [require-dev] 部分,该部分位于 [composer.json] 文件中。

PHPUnit 12 版本需要 PHP 8.3 或更高版本。其文档见 [https://docs.phpunit.de/]。

11.7.2. 配置文件 [phpunit.xml]

[php8-oct-2026] 文件夹中还包含 PHPUnit 的配置文件 [phpunit.xml]。从这个文件夹启动 PHPUnit 时,它会自动使用这个文件:

<?xml version="1.0" encoding="UTF-8"?>
<!-- PHPUnit configuration for all the tests of the course:
     php vendor/bin/phpunit scripts-console/tax/version-04/Tests -->
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
         colors="false"
         failOnDeprecation="true"
         failOnPhpunitDeprecation="true"
         failOnNotice="true"
         failOnWarning="true"
         displayDetailsOnTestsThatTriggerDeprecations="true"
         displayDetailsOnTestsThatTriggerNotices="true"
         displayDetailsOnTestsThatTriggerWarnings="true"
         cacheDirectory=".phpunit.cache">
    <source ignoreSuppressionOfDeprecations="true">
        <include>
            <directory>scripts-console</directory>
            <directory>scripts-web</directory>
        </include>
    </source>
</phpunit>

说明

  • 第 5 行:XML 模式,它描述该文件的语法。[VS Code] 用它来验证文件并提示可用的属性;
  • 第 6 行:结果显示中不使用颜色。你可以使用 [true] 在终端中以绿色显示成功的测试,以红色显示失败的测试;
  • 第 7–10 行:触发 PHP 弃用提示、通知或警告的测试被视为失败,即使它的断言得到验证。这是强制要求编写干净的 PHP 8 代码的一种方式:例如,使用在 PHP 8.5 中已弃用的特性会导致测试失败;
  • 第 11–13 行:在这些情况下,PHPUnit 会显示来自 PHP 的消息的详细信息;
  • 第 14 行:PHPUnit 存储两次运行之间的信息的文件夹(例如失败的测试,以便下次优先运行);
  • 第 15–20 行:包含被测源代码的文件夹。[ignoreSuppressionOfDeprecations] 表示即使弃用提示被运算符 [@] 抑制,也会被报告。

11.7.3. [dao] 层的测试

版本 4 的测试位于 [version-04/Tests] 文件夹中。PHPUnit 测试类:

  • 继承类 [PHPUnit\Framework\TestCase];
  • 名称以 [Test] 结尾,位于同名文件中:PHPUnit 就是这样在文件夹中找到测试类的;
  • 具有名称以 [test] 开头的公共测试方法;
  • 可以有一个名为 [setUp] 的方法,在每个测试方法之前执行,以及一个 名为 [tearDown] 的方法,在每个测试方法之后执行。它们用于搭建测试环境,然后清理它。这样,每个测试方法都在一个全新的环境中运行,彼此独立。

在测试方法中,使用从 [TestCase] 继承的断言方法来验证结果,例如:

断言
验证
[assertSame($expected, $actual)]
两个值相同([===]:类型相同且值相同)
[assertEquals($expected, $actual)]
两个值相等([==])
[assertEqualsWithDelta($expected, $actual, $delta)]
两个数字在 [$delta] 的范围内相等
[assertTrue($actual)], [assertFalse($actual)], [assertNull($actual)]
值为 [true]、[false]、[null]
[assertCount($n, $array)]
数组有 [$n] 个元素
[assertStringContainsString($substring, $string)]
字符串包含该子串
[expectException($class)]
随后的代码抛出指定类的异常

为构建应用练习某个版本的测试,我们使用与该版本的主脚本 [main.php] 相同的环境:加载相同的文件,并以相同的方式构建相同的层。

测试类 [DaoTest] 如下:[Tests/DaoTest.php]:

<?php

// 严格遵守所声明的函数参数和结果的类型
declare(strict_types=1);

// 测试的命名空间
namespace Application\Tests;

// 被测试的类
use Application\DaoTaxWithTaxAdminDataInJsonFile;
use Application\TaxException;
use Application\InterfaceDao;
use Application\TaxPayerData;
// PHPUnit 的类
use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\TestCase;

// 加载 [dao] 层的类
require_once __DIR__ . "/../TaxException.php";
require_once __DIR__ . "/../Utilities.php";
require_once __DIR__ . "/../TaxAdminData.php";
require_once __DIR__ . "/../TaxPayerData.php";
require_once __DIR__ . "/../InterfaceDao.php";
require_once __DIR__ . "/../TraitDao.php";
require_once __DIR__ . "/../DaoTaxWithTaxAdminDataInJsonFile.php";

final class DaoTest extends TestCase
{
    // 版本 4 的文件夹
    private const string ROOT = __DIR__ . "/..";
    // 被测试的 [dao] 层
    private InterfaceDao $dao;
    // 用于错误的临时文件
    private string $errorsFilename;

    // 在每个测试之前执行
    #[\Override]
    protected function setUp(): void
    {
        // 创建 [dao] 层
        $this->dao = new DaoTaxWithTaxAdminDataInJsonFile(self::ROOT . "/taxadmindata.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);
    }

    // 不正确的税务数据文件
    public static function invalidFiles(): array
    {
        // [文件名, 预期的错误代码]
        return [
            "non-existent file" => ["nonexistent.json", 1],
            "invalid JSON" => ["syntax.json", 2],
            "missing key" => ["missing-key.json", 4],
            "negative value" => ["negative-value.json", 6],
        ];
    }

    #[DataProvider("invalidFiles")]
    public function testInvalidTaxAdminData(string $file, int $code): void
    {
        // 我们期望得到带特定代码的 [TaxException] 异常
        $this->expectException(TaxException::class);
        $this->expectExceptionCode($code);
        // 使用不正确的文件构建 [dao] 层
        new DaoTaxWithTaxAdminDataInJsonFile(__DIR__ . "/data/$file");
    }

    // 纳税人的数据
    public function testTaxPayersData(): void
    {
        $taxPayersData = $this->dao->getTaxPayersData(self::ROOT . "/taxpayersdata.txt", $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]);
        // 2 个不正确的行:第 5 行和第 8 行
        $errors = file($this->errorsFilename, FILE_IGNORE_NEW_LINES);
        $this->assertCount(2, $errors);
        $this->assertStringContainsString("line [5]", $errors[0]);
        $this->assertStringContainsString("line [8]", $errors[1]);
    }

    // 不存在的纳税人文件
    public function testNonExistentTaxPayersData(): void
    {
        $this->expectException(TaxException::class);
        $this->expectExceptionCode(12);
        $this->dao->getTaxPayersData(self::ROOT . "/nonexistent.txt", $this->errorsFilename);
    }
}

说明

  • 第 7 行:测试类位于 [Application\Tests] 命名空间中,它与应用程序的命名空间不同;
  • 第 10–16 行:用 [use] 语句导入所用的类。应用程序的类位于 [Application] 命名空间中,而 PHPUnit 的类位于 [PHPUnit\Framework] 中;
  • 第 19–25 行:加载 [dao] 层的文件,如同在 [main.php] 中一样。路径相对于测试文件所在的文件夹([__DIR__]):无论从哪个文件夹启动 PHPUnit,也无论 [php8-oct-2026] 文件夹位于磁盘上的什么位置,测试都能运行。PHP 7 课程使用的是作者机器特有的绝对路径([C:/Data/...])。而 PHPUnit 中的类则由 [Composer] 的加载器自动加载,该加载器由 PHPUnit 初始化;
  • 第 27 行:测试类继承 [TestCase];
  • 第 30 行:版本 4 的文件夹,数据文件就位于其中;
  • 第 38–44 行:在每个测试之前,按 [dao] 层在 [main.php], 中的构建方式来构建该层,并为错误创建一个临时文件。函数 [tempnam] 在系统的临时文件夹(由 [sys_get_temp_dir] 返回)中创建一个名称唯一的文件。PHP 7 课程是在测试类的构造函数中完成这项任务的:从 PHPUnit 10 起,不再需要重新定义 [TestCase] 的构造函数;
  • 第 48–52 行:每个测试之后,删除临时文件;
  • 第 55–73 行:测试税务管理数据。我们验证 [TaxAdminData] 对象(由 [dao] 层返回)的内容与预期一致。这里使用的是 [assertSame] 方法:[assertSame(1551.0, ...)] 验证该值是实数 1551.0;[assertSame(1551, ...)] 会失败,因为整数 1551 与实数 1551.0 不相同。对于数组,[assertSame] 验证两个数组具有相同的键、相同的顺序和相同的值;
  • 第 76–85 行:一个数据提供者。这是一个返回数据集数组的静态公共方法。每个数据集是要传递给某个测试方法的参数数组。每个数据集的键(“non-existent file”等)给它一个名称,该名称会出现在测试结果中;
  • 第 87 行:PHP 8 属性 [#[DataProvider]] 表示测试方法 [testInvalidTaxAdminData] 必须针对来自提供者 [invalidFiles] 的每个数据集执行一次。PHPUnit 10 之前的版本使用注释中的注解:从 PHPUnit 12 起,注解不再被识别;
  • 第 88–95 行:验证用错误的税务数据文件构建的层会抛出带有正确错误代码的异常。方法 [expectException] 和 [expectExceptionCode] 必须调用先于抛出异常的代码:如果抛出异常,测试通过;否则测试失败。错误的文件位于 [Tests/data] 文件夹中:一个格式错误的 JSON 文件(缺少逗号)、一个缺少 [coupleDiscountCeiling] 键的文件,以及一个含负值的文件;
  • 第 98–112 行:读取纳税人数据的测试。版本 4 的 [taxpayersdata.txt] 文件包含 11 行正确的行和 2 行错误的行。我们验证获取的纳税人数量、其类型([assertContainsOnlyInstancesOf])、第一条和最后一条记录的内容,然后验证错误文件的内容。为了比较两个 [TaxPayerData] 对象,我们使用 [assertEquals]:两个不同的对象永远不会相同([===]),但如果它们的属性相等,它们就是相等的([==]);
  • 第 115–120 行:不存在的纳税人文件必须触发代码为 12 的异常。

11.7.4. 运行测试

测试在 [php8-oct-2026] 文件夹中打开的终端里运行,把测试文件夹传给 PHPUnit:

> php vendor/bin/phpunit scripts-console/tax/version-04/Tests
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.020, Memory: 16.00 MB

OK (18 tests, 52 assertions)
  • 第 5 行:PHPUnit 找到并使用了配置文件 [phpunit.xml];
  • 第 7 行:每个成功的测试一个点。这 18 个测试来自两个测试类 [DaoTest] 和 [BusinessTest] (后者在下一段中介绍):使用数据提供者运行的测试,有多少个数据集就算多少个测试;
  • 第 11 行:结果:所有测试都通过了。

[--testdox] 选项提供更具描述性的显示,其中每个测试由一个句子来描述,该句子由其方法名和其数据集名称组成:

> php vendor/bin/phpunit --testdox scripts-console/tax/version-04/Tests
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.006, 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
 ✔ Invalid tax admin data with data set "non-existent file"
 ✔ Invalid tax admin data with data set "invalid JSON"
 ✔ Invalid tax admin data with data set "missing key"
 ✔ Invalid tax admin data with data set "negative value"
 ✔ Tax payers data
 ✔ Non existent tax payers data

OK (18 tests, 52 assertions)

现在我们来看一个失败的测试。在 [BusinessTest] 类中,我们在第二位纳税人的预期减免额中引入一个错误(346 而不是 347)。运行测试后得到如下结果:

> php vendor/bin/phpunit scripts-console/tax/version-04/Tests
PHPUnit 12.5.37 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.5.11
Configuration: .../php8-oct-2026/phpunit.xml

.F................                                                18 / 18 (100%)

Time: 00:00.008, Memory: 16.00 MB

There was 1 failure:

1) Application\Tests\BusinessTest::testCalculateTax@couple, 2 children, 50000 with data ('yes', 2, 50000, 1385, [1384, 0, 384, 346, 0.14])
Failed asserting that two arrays are identical.
--- Expected
+++ Actual
@@ @@
     'tax' => 1384,
     'surcharge' => 0,
     'discount' => 384,
-    'reduction' => 346,
+    'reduction' => 347,
     'rate' => 0.14,
 ]

.../php8-oct-2026/scripts-console/tax/version-04/Tests/BusinessTest.php:84

FAILURES!
Tests: 18, Assertions: 52, Failures: 1.
  • 第 7 行:字母 F(Failure)表示失败的测试;
  • 第 13 行:失败的测试,以及其数据集的名称和内容;
  • 第 14–24 行:失败的断言([assertSame])以及预期数组(-)与实际数组(+)之间的差异;
  • 第 26 行:失败断言所在的文件和行号;
  • 第 28–29 行:摘要。

当某个测试甚至无法运行(例如,因为找不到由 [require_once] 加载的文件)时,PHPUnit 会显示相应的 PHP 错误,就像运行标准 PHP 脚本那样。

11.7.5. [business] 层测试

测试类 [BusinessTest] 遵循与类 [DaoTest] 相同的构建规则:[Tests/BusinessTest.php]:

<?php

// 严格遵守所声明的函数参数和结果的类型
declare(strict_types=1);

// 测试的命名空间
namespace Application\Tests;

// 被测试的类
use Application\DaoTaxWithTaxAdminDataInJsonFile;
use Application\InterfaceBusiness;
use Application\Business;
// PHPUnit 的类
use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\TestCase;

// 加载 [dao] 层和 [business] 层的类
require_once __DIR__ . "/../TaxException.php";
require_once __DIR__ . "/../Utilities.php";
require_once __DIR__ . "/../TaxAdminData.php";
require_once __DIR__ . "/../TaxPayerData.php";
require_once __DIR__ . "/../InterfaceDao.php";
require_once __DIR__ . "/../TraitDao.php";
require_once __DIR__ . "/../DaoTaxWithTaxAdminDataInJsonFile.php";
require_once __DIR__ . "/../InterfaceBusiness.php";
require_once __DIR__ . "/../Business.php";

final class BusinessTest extends TestCase
{
    // 版本 4 的文件夹
    private const string ROOT = __DIR__ . "/..";
    // 被测试的 [business] 层
    private InterfaceBusiness $business;

    // 在每个测试之前执行
    #[\Override]
    protected function setUp(): void
    {
        // 创建 [dao] 层
        $dao = new DaoTaxWithTaxAdminDataInJsonFile(self::ROOT . "/taxadmindata.json");
        // 创建 [business] 层
        $this->business = new Business($dao);
    }

    // 官方数据表中的纳税人
    public static function taxpayers(): array
    {
        // [married, children, salary, 官方税款, 算法的预期结果]
        return [
            "couple, 2 children, 55555" => ["yes", 2, 55555, 2815,
                ["tax" => 2814, "surcharge" => 0, "discount" => 0, "reduction" => 0, "rate" => 0.14]],
            "couple, 2 children, 50000" => ["yes", 2, 50000, 1385,
                ["tax" => 1384, "surcharge" => 0, "discount" => 384, "reduction" => 347, "rate" => 0.14]],
            "couple, 3 children, 50000" => ["yes", 3, 50000, 0,
                ["tax" => 0, "surcharge" => 0, "discount" => 720, "reduction" => 0, "rate" => 0.14]],
            "single, 2 children, 100000" => ["no", 2, 100000, 19884,
                ["tax" => 19884, "surcharge" => 4480, "discount" => 0, "reduction" => 0, "rate" => 0.41]],
            "single, 3 children, 100000" => ["no", 3, 100000, 16782,
                ["tax" => 16782, "surcharge" => 7176, "discount" => 0, "reduction" => 0, "rate" => 0.41]],
            "couple, 3 children, 100000" => ["yes", 3, 100000, 9200,
                ["tax" => 9200, "surcharge" => 2180, "discount" => 0, "reduction" => 0, "rate" => 0.3]],
            "couple, 5 children, 100000" => ["yes", 5, 100000, 4230,
                ["tax" => 4230, "surcharge" => 0, "discount" => 0, "reduction" => 0, "rate" => 0.14]],
            "single, 0 children, 100000" => ["no", 0, 100000, 22986,
                ["tax" => 22986, "surcharge" => 0, "discount" => 0, "reduction" => 0, "rate" => 0.41]],
            "couple, 2 children, 30000" => ["yes", 2, 30000, 0,
                ["tax" => 0, "surcharge" => 0, "discount" => 0, "reduction" => 0, "rate" => 0.0]],
            "single, 0 children, 200000" => ["no", 0, 200000, 64211,
                ["tax" => 64210, "surcharge" => 7498, "discount" => 0, "reduction" => 0, "rate" => 0.45]],
            "couple, 3 children, 200000" => ["yes", 3, 200000, 42843,
                ["tax" => 42842, "surcharge" => 17283, "discount" => 0, "reduction" => 0, "rate" => 0.41]],
        ];
    }

    // 对数据提供者中的每一位纳税人各执行一次的测试
    #[DataProvider("taxpayers")]
    public function testCalculateTax(string $married, int $children, int $salary, int $officialTax, array $expected): void
    {
        // 税款计算
        $result = $this->business->calculateTax($married, $children, $salary);
        // 税款与官方模拟器的结果相差在 1 欧元以内
        $this->assertEqualsWithDelta($officialTax, $result["tax"], 1);
        // 结果与预期完全一致(键、值、类型都相同)
        $this->assertSame($expected, $result);
    }
}

说明

  • 第 18–26 行:加载 [dao] 层和 [business] 层的文件。测试环境与 [main.php] 的相同;
  • 第 37–43 行:实例化 [dao] 层和 [business] 层,如同在 [main.php] 中一样;
  • 第 46–73 行:数据提供者:官方数据表中的十一位纳税人。每个数据集包含纳税人的数据、税务机关官方模拟器 [https://www3.impots.gouv.fr/simulateur/calcul_impot/2019/simplifie/index.htm] 给出的税额,以及文档中所述算法的预期结果;
  • 第 76 行:方法 [testCalculateTax] 将执行十一次,每位纳税人一次。PHP 7 课程最初包含十一个几乎相同的测试方法,从 [test1] 到 [test11];数据提供者消除了这种重复;
  • 第 80 行:税款计算由 [business] 层执行;
  • 第 82 行:我们验证计算出的税款与官方模拟器的结果相差不超过 1 欧元。我们已经看到,由于舍入问题,文档中的算法产生的结果与官方结果最多相差 1 欧元;
  • 第 84 行:我们验证结果数组 [tax, surcharge, discount, reduction, rate] 与预期完全一致,包括数据类型:金额为整数,税率为实数。这就是为什么第 9 位纳税人的税率写成 0.0 而不是 0。这种精确的验证可以防止未来版本中对算法的任何意外改动。

运行这些测试的结果就是上一段中所示的结果:[business] 层的全部 11 个测试都通过了。

11.7.6. VS Code 中的 PHPUnit

在 [VS Code] 中运行测试最简单的方法是使用其内置终端(“终端”菜单 / “新建终端”):它会在项目的 [php8-oct-2026] 文件夹中打开,你在其中输入命令 [php vendor/bin/phpunit scripts-console/tax/version-04/Tests]。键盘上的向上箭头可以调出上一条命令:修改代码后重新运行测试,只需按一个键。

[phpunit] 命令的一些有用选项:

  • [--testdox]:把测试显示为句子;
  • [--filter testCalculateTax]:只运行名称包含指定文本的测试;
  • [--stop-on-failure]:在第一次失败时停止。

还有一些 [VS Code] 扩展,把 PHPUnit 集成到编辑器的测试资源管理器中(例如“PHPUnit Test Explorer”扩展):它们允许你一键运行测试,并在代码旁边显示结果。它们实际上执行的是我们在终端中输入的同一条 [phpunit] 命令。

11.7.7. 后续版本的测试

今后,[dao] 和 [business] 层的测试将与版本 4 中的相同。唯一会变的是测试环境:所加载的文件,以及 [dao] 和 [business] 层的构建方式。因此我们只介绍这一点和测试结果。