Skip to content

8. 实践练习——版本 3

我们将重温前面做过的练习(版本 1 和版本 2),并用使用类的 PHP 代码来解决它。我们将把前三章所学的内容付诸实践:

  • 一个(不可变的)[readonly] 类,用来表示税务机关的数据;
  • 一个接口、一个部分实现该接口的抽象类,以及一个补全它的派生类;
  • 单一的异常类型 [TaxException],用来报告应用程序的所有错误;
  • 在所有实现接口方法或重写父类方法的方法上使用 [#[\Override]] 属性。

8.1. 脚本目录结构

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

version-03
├── AbstractBaseTax.php
├── errors.txt
├── InterfaceTax.php
├── main.php
├── results.txt
├── taxadmindata.json
├── TaxAdminData.php
├── TaxException.php
├── taxpayersdata.txt
├── TaxWithTaxAdminDataInJsonFile.php
├── test-taxadmindata.php
└── Utilities.php

每个类或接口都放在以其名称命名的文件中。这是 PHP 中普遍遵循的约定(自动加载标准 PSR-4 甚至强制要求这样做,我们将在 [Composer] 中遇到它)。

8.2. [TaxException] 异常

在版本 3 中,当类的构造函数或方法遇到错误时,会抛出 [TaxException] 异常:

<?php

declare(strict_types=1);

// 命名空间
namespace Application;

// 税款计算应用程序的各个类抛出的异常
class TaxException extends \RuntimeException
{
    // 没有代码:从 [\RuntimeException] 继承的构造函数就足够了
    // __construct(string $message = "", int $code = 0, ?\Throwable $previous = null)
}

说明

  • 第 6 行:类 [TaxException] 位于 [Application] 命名空间中。税款计算应用程序中的所有类和接口都将位于这个命名空间中;
  • 第 9 行:类 [TaxException] 继承 PHP 预定义类 [RuntimeException]。正如我们在异常一章中看到的,异常主要由其类型来定义:正是类型使它可以被 [catch (TaxException $ex)] 子句捕获;
  • 第 11–12 行:PHP 7 课程定义了一个构造函数 [__construct(string $message, int $code = 0)] ,它只是调用父类的构造函数。这是不必要的:该类从 [RuntimeException] 继承了构造函数,它接受一条消息、一个错误代码和可选的前一个异常。我们将使用最后这个参数,把低层异常(例如 [JsonException], )封装到 [TaxException] 中。

8.3. [TaxAdminData] 类

在版本 2 中,税务机关的数据被整合:

  • 首先放入一个 JSON 文件;
  • 然后从这个 JSON 文件读入一个关联数组。

我们曾指出这种方案的一个缺陷:无法保证关联数组包含所有预期的键,也无法保证相应的值是数字。在版本 3 中,税务机关的数据仍然保存在文件 [taxadmindata.json] 中,但属性名不同,按照类属性名的 camelCase 约定书写:

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

在版本 2 中,这个文件用于初始化一个关联数组。在版本 3 中,它将用于初始化下面这个类的对象:[TaxAdminData]:

<?php

declare(strict_types=1);

// 命名空间
namespace Application;

// 税务管理部门的数据:一个不可变对象
final readonly class TaxAdminData
{
    // 数据中预期的数组和常量的名称
    private const array ARRAYS = ["limits", "coeffR", "coeffN"];
    private const array CONSTANTS = [
        "halfShareQfCeiling",
        "singleIncomeCeilingForReduction",
        "coupleIncomeCeilingForReduction",
        "halfShareReductionValue",
        "singleDiscountCeiling",
        "coupleDiscountCeiling",
        "coupleTaxCeilingForDiscount",
        "singleTaxCeilingForDiscount",
        "tenPercentAllowanceMax",
        "tenPercentAllowanceMin",
    ];

    // 私有构造函数:必须通过 [from...] 方法
    private function __construct(
        // 税率档
        public array $limits,
        public array $coeffR,
        public array $coeffN,
        // 税款计算常量
        public float $halfShareQfCeiling,
        public float $singleIncomeCeilingForReduction,
        public float $coupleIncomeCeilingForReduction,
        public float $halfShareReductionValue,
        public float $singleDiscountCeiling,
        public float $coupleDiscountCeiling,
        public float $coupleTaxCeilingForDiscount,
        public float $singleTaxCeilingForDiscount,
        public float $tenPercentAllowanceMax,
        public float $tenPercentAllowanceMin,
    ) {
    }

    // 从 JSON 文件构建
    public static function fromJsonFile(string $taxAdminDataFilename): self
    {
        // 我们获取税务数据文件的内容
        $fileContents = is_readable($taxAdminDataFilename) ? file_get_contents($taxAdminDataFilename) : false;
        // 出错?
        if ($fileContents === false) {
            throw new TaxException("The data file [$taxAdminDataFilename] does not exist", 1);
        }
        // 我们将 JSON 解码为关联数组
        try {
            $data = json_decode($fileContents, true, flags: JSON_THROW_ON_ERROR);
        } catch (\JsonException $ex) {
            throw new TaxException("The JSON data file [$taxAdminDataFilename] could not be processed correctly", 2, $ex);
        }
        // JSON 必须是对象 {...}
        if (!is_array($data)) {
            throw new TaxException("The JSON data file [$taxAdminDataFilename] does not contain a JSON object", 3);
        }
        // 从关联数组构建对象
        return self::fromArray($data);
    }

    // 从关联数组 [名称 => 值] 构建
    public static function fromArray(array $data): self
    {
        // 存在的键必须恰好是预期的键
        $expected = [...self::ARRAYS, ...self::CONSTANTS];
        $missing = array_first(array_diff($expected, array_keys($data)));
        if ($missing !== null) {
            throw new TaxException("The attribute [$missing] of [TaxAdminData] has not been initialized", 4);
        }
        $unknown = array_first(array_diff(array_keys($data), $expected));
        if ($unknown !== null) {
            throw new TaxException("The attribute [$unknown] does not exist in [TaxAdminData]", 5);
        }
        // 我们检查并转换每个值
        $values = [];
        foreach (self::ARRAYS as $key) {
            // 由实数 >= 0 组成的非空数组
            if (!is_array($data[$key]) || !array_is_list($data[$key]) || count($data[$key]) === 0) {
                throw new TaxException("The value of attribute [$key] is invalid", 6);
            }
            $values[$key] = array_map(fn(mixed $value): float => self::check($key, $value), $data[$key]);
        }
        // 三个数组的大小必须相同
        $size = count($values["limits"]);
        if (count($values["coeffR"]) !== $size || count($values["coeffN"]) !== $size) {
            throw new TaxException("The arrays [limits, coeffR, coeffN] do not have the same size", 7);
        }
        foreach (self::CONSTANTS as $key) {
            // 实数 >= 0
            $values[$key] = self::check($key, $data[$key]);
        }
        // 构建对象:数组的键成为命名参数
        return new self(...$values);
    }

    // 检查值是否为正实数或零,并将其作为 [float] 返回
    private static function check(string $key, mixed $value): float
    {
        // 我们接受 1551、1551.78、"1551",但不接受 "xx"、true、null、-3……
        if ((is_int($value) || is_float($value) || (is_string($value) && is_numeric($value)))
            && (float) $value >= 0) {
            return (float) $value;
        }
        throw new TaxException("The value of attribute [$key] is invalid", 6);
    }

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

说明

  • 第 9 行:该类是 [readonly] 的:它的所有属性都是只读的。一旦创建,[TaxAdminData] 对象就不能再被修改:它可以在应用程序的各个部分之间安全地共享。它同时还是 [final] 的:不能被继承;
  • 第 12–24 行:两个私有类常量列出了数据中预期的属性名。从 PHP 8.3 起,类常量可以带类型(这里是 [array]);
  • 第 27–43 行:构造函数使用参数提升:每个参数都成为同名同类型的公共属性。这些属性与 JSON 文件中的键同名。这一点很重要,正如我们将看到的,它极大地简化了代码编写。税率档次是数组([array]),计算常量是实数([float])。在 PHP 7 中,属性不能带类型(如 PHP 7 课程中所述);从 PHP 7.4 起可以为属性指定类型;
  • 第 27 行:构造函数是 private 的;[new TaxAdminData(...)] 不能在类外部编写。[TaxAdminData] 对象只能通过静态方法 [fromJsonFile] 和 [fromArray] 获得,这两个方法会验证数据的有效性。这就确保每个 [TaxAdminData] 对象都包含有效数据。在 PHP 中,一个类只能有一个构造函数。构造对象的静态方法——有时称为“命名构造函数”——使得构造对象可以有多种方式。PHP 7 课程使用的是在空对象上调用的实例方法 [setFromJsonFile] :[(new TaxAdminData())->setFromJsonFile(...)]。这对于不可变对象是不可能的;
  • 第 47–67 行:[fromJsonFile] 方法根据传给它的 JSON 文件名,构造一个 [TaxAdminData] 对象。它的返回类型 [self], 指的是类本身;
  • 第 50–53 行:读取文件内容。如果无法读取,则抛出 [TaxException] 异常。该异常将一直传播到主脚本;
  • 第 56–60 行:对文件内容(JSON)进行解码。使用选项 [JSON_THROW_ON_ERROR] (PHP 7.3)时,当 JSON 无效,[json_decode] 函数会抛出 [JsonException] 异常,而不是悄悄地返回 [null]。请注意命名参数 [flags:], 它使我们不必为 [depth] 的第三个参数 [json_decode]赋值。异常 [JsonException] 被封装在 [TaxException] 中:调用方代码只需处理一种异常类型,但可以通过 [$ex->getPrevious()] 确定原始原因;
  • 第 62–64 行:例如,只包含数字 12 的文件是有效的 JSON;必须验证确实得到了数组;
  • 第 66 行:其余工作委托给 [fromArray] 方法。该方法是公共的:在未来的版本中,如果税务机关数据来自数据库,也可以使用它;
  • 第 73–81 行:我们验证数组 [$data] 中的键恰好就是预期的名称。[[...self::ARRAYS, ...self::CONSTANTS]] 创建一个包含两个数组所有元素的数组。函数 [array_diff] 返回第一个数组中不在第二个数组中的元素,而函数 [array_first](PHP 8.5)返回数组的第一个元素,如果数组为空则返回 [null] 。这样可以先检测缺失的键,再检测未知的键。这是最常见的错误:[taxadmindata.json] 文件中属性名拼写错误。在 PHP 7 课程中,循环 [$this->$key = $value] 会悄悄地创建一个名称错误的动态属性。自 PHP 8.2 起,创建动态属性已被弃用,并且在 [readonly] 类中是被禁止的;
  • 第 84–90 行:三个数组中的每一个都必须是非空列表(函数 [array_is_list],PHP 8.1),其元素全部为正实数或零。函数 [array_map] 对每个元素应用方法 [check] ;
  • 第 92–95 行:三个税率档次数组的大小必须相同;
  • 第 96–99 行:每个计算常量都必须是正实数或零;
  • 第 101 行:数组 [$values] 以构造函数的参数名作为键。运算符 [...], 应用于带字符串键的数组时,会把每个元素转换为命名参数(PHP 8.1):这一行等价于 [new self(limits: $values["limits"], coeffR: $values["coeffR"], ...)]。正是在这里,为 JSON 键和类属性选择相同的名称简化了代码;
  • 第 105–113 行:方法 [check] 检查一个类型未知([mixed])的值 [$value] 是否为正数或零。根据 JSON 文件中的信息,读取到的值可以是整数(1551)、浮点数(1551.78)、可转换为数字的字符串("1551")、不可转换的字符串("xx")、布尔值等等。函数 [is_numeric] 对表示数字的字符串返回 [true] 。PHP 7 课程使用正则表达式执行这项检查,并返回一个指示是否发生错误的 [stdClass] 对象。这里,错误会触发异常,而该方法只需以 [float] 的形式返回该数字;
  • 第 116 行:[__toString] 方法返回包含对象属性的 JSON 字符串。[get_object_vars] 函数返回一个 [attribute name => value] 关联数组。

8.3.1. 为什么不再有 getter 和 setter?

PHP 7 课程把属性声明为私有,并为每个属性编写了一个 getter 和一个 setter(共 26 个方法),由 NetBeans IDE 自动生成。这些 setter 是“流式”的:它们返回 [$this] 对象,从而允许链式调用 [$data->setLimits($limits)->setCoeffR($coeffR)]。

在 PHP 8 中,这些代码不再是必需的:

  • getter 用于读取私有属性。[readonly] 属性可以放心地设为公共,因为它们无法被修改:我们写 [$taxAdminData->halfShareQfCeiling] ,而不是 [$taxAdminData->getHalfShareQfCeiling()];
  • setter 用于初始化对象,并允许对值进行验证。不可变对象由其构造函数一次性初始化,验证则由方法 [fromJsonFile] 和 [fromArray] 执行;
  • 带类型的属性保证了值的类型。PHP 7 课程指出,语句 [$this->halfShareQfCeiling = 'abcd'] 是可行的:而对于 [float] 属性并使用 [declare(strict_types=1)],它会导致 [TypeError] 错误。

脚本 [test-taxadmindata.php] 验证类 [TaxAdminData] 的功能:

<?php

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

// 命名空间
namespace Application;

// 引入这些类
require_once __DIR__ . "/TaxException.php";
require_once __DIR__ . "/TaxAdminData.php";

// 一个有效的对象
$taxAdminData = TaxAdminData::fromJsonFile("taxadmindata.json");
print "$taxAdminData\n";
print "halfShareQfCeiling=" . $taxAdminData->halfShareQfCeiling . "\n";
// 对象是不可变的
try {
    $taxAdminData->halfShareQfCeiling = 2000;
} catch (\Error $ex) {
    print $ex::class . ": " . $ex->getMessage() . "\n";
}
// 构造函数是私有的
try {
    $taxAdminData = new TaxAdminData([], [], []);
} catch (\Error $ex) {
    print $ex::class . ": " . $ex->getMessage() . "\n";
}

// 不正确的数据
$valid = json_decode(file_get_contents("taxadmindata.json"), true, flags: JSON_THROW_ON_ERROR);
$tests = [
    // 不存在的文件
    fn() => TaxAdminData::fromJsonFile("xx.json"),
    // 不是 JSON 的文件
    fn() => TaxAdminData::fromJsonFile("taxpayersdata.txt"),
    // 缺失的键
    fn() => TaxAdminData::fromArray(array_diff_key($valid, ["halfShareQfCeiling" => 0])),
    // 未知的键(拼写错误)
    fn() => TaxAdminData::fromArray(["halfShareQFCeiling" => 1551] + $valid),
    // 非数值
    fn() => TaxAdminData::fromArray(["halfShareQfCeiling" => "xx"] + $valid),
    // 数组中的负值
    fn() => TaxAdminData::fromArray(["coeffR" => [0, 0.14, -0.3, 0.41, 0.45]] + $valid),
    // 大小不同的数组
    fn() => TaxAdminData::fromArray(["limits" => [9964, 27519, 73779, 0]] + $valid),
];
foreach ($tests as $test) {
    try {
        $test();
    } catch (TaxException $ex) {
        print "TaxException no. {$ex->getCode()}: {$ex->getMessage()}\n";
    }
}
// 值 "1551" 被接受并转换为实数
$taxAdminData = TaxAdminData::fromArray(["halfShareQfCeiling" => "1551"] + $valid);
var_dump($taxAdminData->halfShareQfCeiling);

说明

  • 第 14 行:根据 [taxadmindata.json] 文件构造一个有效的 [TaxAdminData] 对象;
  • 第 15 行:把对象插入字符串:会调用它的 [__toString] 方法;
  • 第 19 行:尝试修改只读属性;
  • 第 25 行:尝试使用私有构造函数;
  • 第 31 行:有效数据的关联数组;
  • 第 32–47 行:一个箭头函数数组,每个函数都根据无效数据构造一个 [TaxAdminData] 对象。无效数据是通过修改 [$valid] 数组的副本得到的。对两个数组应用 [+] 运算符时,若有相同的键,则左侧数组的元素优先。函数 [array_diff_key] 从第一个数组中删除第二个数组中存在的键;
  • 第 48–54 行:执行每个函数,并显示预期的异常;
  • 第 56 行:数字字符串被接受并转换为实数。

结果:

> php test-taxadmindata.php
{"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}
halfShareQfCeiling=1551
Error: Cannot modify readonly property Application\TaxAdminData::$halfShareQfCeiling
Error: Call to private Application\TaxAdminData::__construct() from global scope
TaxException no. 1: The data file [xx.json] does not exist
TaxException no. 2: The JSON data file [taxpayersdata.txt] could not be processed correctly
TaxException no. 4: The attribute [halfShareQfCeiling] of [TaxAdminData] has not been initialized
TaxException no. 5: The attribute [halfShareQFCeiling] does not exist in [TaxAdminData]
TaxException no. 6: The value of attribute [halfShareQfCeiling] is invalid
TaxException no. 6: The value of attribute [coeffR] is invalid
TaxException no. 7: The arrays [limits, coeffR, coeffN] do not have the same size
float(1551)
  • 第 2 行:对象的 JSON 字符串。请注意,没有小数部分的实数(1551.0)被 [json_encode] 函数写成不带小数部分的形式(1551);
  • 第 4–5 行:由修改 [readonly] 属性和调用私有构造函数所导致的两个 [Error] 错误。这些是编程错误,而不是数据错误:它们不会被转换为 [TaxException];
  • 第 6–12 行:所有不正确的数据都被检测到,每个都带有不同的消息和错误代码;
  • 第 13 行:字符串 "1551" 已被转换为浮点数。

8.4. [InterfaceTax] 接口

现在我们定义下面的 [InterfaceTax] 接口:[InterfaceTax.php]:

<?php

declare(strict_types=1);

// 命名空间
namespace Application;

interface InterfaceTax
{
    // 获取用于计算税款的税务管理部门数据
    // 可能抛出 TaxException 异常
    public function getTaxAdminData(): TaxAdminData;

    // 该接口知道如何计算税款
    public function calculateTax(string $married, int $children, int $salary): array;

    // 该接口知道如何处理文本文件中的数据
    // $taxPayersFileName:纳税人数据文件,格式为婚姻状况、子女数、年薪
    // $resultsFileName:结果文件,格式为婚姻状况、子女数、年薪、税款……
    // $errorsFileName:遇到的错误的文件
    // 可能抛出 TaxException 异常
    public function executeBatchTaxes(string $taxPayersFileName, string $resultsFileName, string $errorsFileName): void;
}

说明

  • 第 8 行:税款计算接口。它同样位于 [Application] 命名空间中;
  • 第 12 行:方法 [getTaxAdminData] 将把税务机关的数据读取到我们刚介绍的 [TaxAdminData] 类型的对象中。由于这些数据可能存储在文件、数据库甚至网络上,方法 [getTaxAdminData] 可能无法取得数据。此时,它会抛出 [TaxException] 类型的异常。这是面向对象编程中用来报告方法或构造函数中遇到的错误的标准做法;
  • 第 15 行:[calculateTax] 方法将计算纳税人的税款;
  • 第 22 行:方法 [executeBatchTaxes] 计算多个纳税人的税款;
    • [$taxPayersFileName] 是包含纳税人数据的文本文件的名称;
    • [$resultsFileName] 是包含这些纳税人税款金额的文本文件的名称;
    • [$errorsFileName] 是包含处理这些文件时遇到的错误的文本文件的名称。

纳税人文本文件 [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

请注意,第 5 行和第 8 行包含不正确的条目。其余十一行对应于官方数据表中列出的十一位纳税人。

8.5. 类 [Utilities]

我们还在名为 [Utilities.php] 的文件中定义一个名为 [Utilities] 的类:

<?php

declare(strict_types=1);

// 命名空间
namespace Application;

// 一个工具函数类:既不能被实例化,也不能被派生
final class Utilities
{
    // 私有构造函数:该类不能被实例化
    private function __construct()
    {
    }

    public static function cutNewLineChar(string $line): string
    {
        // 如果 $line 存在行尾标记,则将其删除
        // (Windows 上是 \r\n,Unix 上是 \n)
        return rtrim($line, "\r\n");
    }
}

说明

  • 第 9 行:类 [Utilities] 同样位于 [Application] 命名空间中。它只包含静态方法:没有理由实例化或继承它。PHP 7 课程把它声明为抽象类以防止实例化,并遗憾 PHP 拒绝把它同时声明为 [final] 和 [abstract]。现在仍然如此。当前的做法是把它声明为 [final] (不可继承),并给它一个私有构造函数(这样无法从外部实例化);
  • 第 16 行:方法 [cutNewLineChar] 从作为参数传给它的文本中删除所有行尾字符。它是静态方法,也就是说将以 [Utilities::cutNewLineChar($line)] 的形式调用。它的代码与版本 2 中同名函数的代码相同。

8.6. 抽象类 [AbstractBaseTax]

[InterfaceTax] 接口将由下面的抽象类 [AbstractBaseTax] [AbstractBaseTax.php] 实现:

<?php

declare(strict_types=1);

// 命名空间
namespace Application;

// 实现 [InterfaceTax] 接口的抽象类
abstract class AbstractBaseTax implements InterfaceTax
{
    // 税务管理部门的数据
    private ?TaxAdminData $taxAdminData = null;

    // 计算税款所需的数据:派生类知道到哪里去找它们
    #[\Override]
    abstract public function getTaxAdminData(): TaxAdminData;

    // 税款计算
    // --------------------------------------------------------------------------
    #[\Override]
    public function calculateTax(string $married, int $children, int $salary): array
    {
        // $married:是、否
        // $children:子女数
        // $salary:年薪
        // $this->taxAdminData:税务管理部门的数据
        //
        // 如果尚未获取,则获取税务管理部门的数据
        $this->taxAdminData ??= $this->getTaxAdminData();
        // 计算有子女时的税款
        $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 行:类 [AbstractBaseTax] 实现接口 [InterfaceTax];
  • 第 12 行:税务机关的数据将存储在私有属性 [$taxAdminData]中。它的类型 [?TaxAdminData], 表示“一个 [TaxAdminData] 对象或值 [null]”。其初始值为 [null];
  • 第 16 行:接口的 [getTaxAdminData] 方法。我们现在还不知道如何定义它:我们见过税务机关数据从 JSON 文件中读取的情形(版本 2);我们还会看到数据从数据库中读取的另一种情形。方法 [getTaxAdminData] 的内容将由派生类来定义。因此该方法被声明为抽象方法,这要求类本身也声明为抽象类。这一声明是可选的:实现接口的抽象类不必重新声明它没有实现的方法。不过,这样写使代码更易读。属性 [#[\Override]] (PHP 8.3)表明该方法属于某个接口或父类:如果名称不正确,PHP 会报告错误;
  • 第 21–73 行:税款计算函数,我们在版本 1 和 2 中已经见过。它的参数已发生变化:版本 2 以关联数组 [$taxAdminData] 作为第一个参数,而版本 3 使用属性 [$this->taxAdminData]。这两种方案的第一个区别在于税务数据可见性的不同:
    • 在版本 2 中,关联数组 [$taxAdminData] 不具有全局可见性。因此它被作为参数传递给所有税款计算函数;
    • 在版本 3 中,属性 [$this->taxAdminData] 在类的所有方法中都可见。因此它不再作为参数传递;
  • 第二个区别源于版本 3 用类方法取代了函数。现在每次方法调用都使用表达式 [$this->method(...)] (第 31 行、第 61 行);
  • 第 29 行:第三个区别是,当 [calculateTax] 方法开始工作时,它并不知道自己所需的 [$taxAdminData] 属性是否已初始化。事实上,该类没有用于初始化它的构造函数。因此要由 [calculateTax] 方法使用 [getTaxAdminData] 方法来完成这一步。运算符 [??=] (PHP 7.4)仅当左侧变量等于 [null] 时,才把右侧的值赋给它。这一行等价于 [if ($this->taxAdminData === null) { $this->taxAdminData = $this->getTaxAdminData(); }];
  • 第 38 行:税务机关的数据直接从对象 [TaxAdminData] 的只读公共属性中读取;
  • 除了这些区别之外,税款计算方法与之前的版本保持一致。

计算税款的私有方法如下:

    // --------------------------------------------------------------------------
    private function calculateTax2(string $married, int $children, float $salary): array
    {
        // 份数
        $nbShares = match ($married) {
            "yes" => $children / 2 + 2,
            "no" => $children / 2 + 1,
        };
        // 从第 3 个子女起每个子女 1 份
        if ($children >= 3) {
            // 从第 3 个子女起每个子女再加半份
            $nbShares += 0.5 * ($children - 2);
        }
        // 应纳税所得额
        $taxableIncome = $this->getTaxableIncome($salary);
        // 附加额
        $surcharge = floor($taxableIncome - 0.9 * $salary);
        // 为了处理舍入问题
        if ($surcharge < 0) {
            $surcharge = 0;
        }
        // 家庭系数
        $quotient = $taxableIncome / $nbShares;
        // 税率档(对象中数组的副本)
        $limits = $this->taxAdminData->limits;
        $coeffR = $this->taxAdminData->coeffR;
        $coeffN = $this->taxAdminData->coeffN;
        // 放在 limits 数组末尾,以终止后面的循环
        $limits[count($limits) - 1] = $quotient;
        // 计算税款
        $i = 0;
        while ($quotient > $limits[$i]) {
            $i++;
        }
        // 现在我们可以计算税款了
        $tax = floor($taxableIncome * $coeffR[$i] - $nbShares * $coeffN[$i]);
        // 结果
        return ["tax" => $tax, "surcharge" => $surcharge, "rate" => $coeffR[$i]];
    }

    // taxableIncome=annualSalary-allowance
    // 扣除额有下限和上限
    private function getTaxableIncome(float $salary): float
    {
        // 按工资的 10% 扣除,受最小值和最大值的限制
        $allowance = 0.1 * $salary;
        $allowance = min($allowance, $this->taxAdminData->tenPercentAllowanceMax);
        $allowance = max($allowance, $this->taxAdminData->tenPercentAllowanceMin);
        // 应纳税所得额
        $taxableIncome = $salary - $allowance;
        // 结果
        return floor($taxableIncome);
    }

    // 计算可能的减免
    private function getDiscount(string $married, float $salary, float $taxes): float
    {
        // 开始时,减免为零
        $discount = 0;
        // 可获得减免的税款最高金额
        $taxCeilingForDiscount = $married === "yes"
            ? $this->taxAdminData->coupleTaxCeilingForDiscount
            : $this->taxAdminData->singleTaxCeilingForDiscount;
        if ($taxes < $taxCeilingForDiscount) {
            // 减免的最高金额
            $discountCeiling = $married === "yes"
                ? $this->taxAdminData->coupleDiscountCeiling
                : $this->taxAdminData->singleDiscountCeiling;
            // 理论减免额
            $discount = $discountCeiling - 0.75 * $taxes;
            // 减免额不能超过税款金额
            if ($discount > $taxes) {
                $discount = $taxes;
            }
            // 减免额不得小于 0
            if ($discount < 0) {
                $discount = 0;
            }
        }
        // 结果
        return ceil($discount);
    }

    // 计算可能的减税
    private function getReduction(string $married, float $salary, int $children, float $taxes): float
    {
        // 有资格享受 20% 减税的收入上限
        $incomeCeilingForReduction = $married === "yes"
            ? $this->taxAdminData->coupleIncomeCeilingForReduction
            : $this->taxAdminData->singleIncomeCeilingForReduction;
        $incomeCeilingForReduction += $children * $this->taxAdminData->halfShareReductionValue;
        if ($children > 2) {
            $incomeCeilingForReduction += ($children - 2) * $this->taxAdminData->halfShareReductionValue;
        }
        // 应纳税所得额
        $taxableIncome = $this->getTaxableIncome($salary);
        // 减税
        $reduction = 0;
        if ($taxableIncome < $incomeCeilingForReduction) {
            // 20% 减税
            $reduction = 0.2 * $taxes;
        }
        // 结果
        return ceil($reduction);
    }

说明

  • 第 80–83 行:表达式 [match] (PHP 8.0)是对版本 2 中 [if / else] 的更好替代。它使用相等运算符 [===] 将 [$married] 的值与各分支的值进行比较,并返回匹配分支的值。如果没有分支匹配,则抛出错误 [UnhandledMatchError]:除“yes”或“no”之外的婚姻状况不会被忽略;
  • 第 100–102 行:税率档次数组被复制到局部变量中。在 PHP 中,对数组赋值会创建副本:第 104 行对 [$limits] 的修改不会影响 [readonly] 对象 [TaxAdminData] 的属性(顺便说一句,那样做会产生错误);
  • 第 122–123 行:函数 [min] 和 [max] 取代了版本 2 中的两个 [if] 函数:扣除额不能超过 [tenPercentAllowanceMax] 也不能低于 [tenPercentAllowanceMin];
  • 其余代码与版本 2 相同,其中表达式 [$taxAdminData["COUPLE_DISCOUNT_CEILING"]] 已变为 [$this->taxAdminData->coupleDiscountCeiling]。属性名中的拼写错误现在在代码写出时就会被 [VS Code] 编辑器([PHP Intelephense] 扩展)标出,而数组键中的拼写错误则不会。

[executeBatchTaxes] 方法如下:

    // 批处理模式下的税款计算
    // --------------------------------------------------------------------------
    #[\Override]
    public function executeBatchTaxes(string $taxPayersFileName, string $resultsFileName, string $errorsFileName): void
    {
        // 这三个文件尚未打开
        $errors = $results = $data = false;
        // 一旦处理文件,就可能发生不少错误
        try {
            // 打开错误文件
            $errors = fopen($errorsFileName, "w");
            if ($errors === false) {
                throw new TaxException("Unable to create the errors file [$errorsFileName]", 10);
            }
            // 打开结果文件
            $results = fopen($resultsFileName, "w");
            if ($results === false) {
                throw new TaxException("Unable to create the results file [$resultsFileName]", 11);
            }
            // 打开纳税人数据文件
            $data = is_readable($taxPayersFileName) ? fopen($taxPayersFileName, "r") : false;
            if ($data === false) {
                throw new TaxException("Unable to open the taxpayers' declarations [$taxPayersFileName] for reading", 12);
            }
            // 我们处理纳税人数据文件的当前行
            // 其格式为婚姻状况、子女数、年薪
            $num = 0;         // 当前行的编号
            $nbErrors = 0;    // 遇到的错误数
            while (($line = fgets($data, 100)) !== false) {
                // 多了一行
                $num++;
                // 我们删除可能存在的行尾标记
                $line = Utilities::cutNewLineChar($line);
                // 我们忽略空行
                if (trim($line) === "") {
                    continue;
                }
                // 该行必须有 3 个字段 married,children,salary
                $fields = array_map(trim(...), explode(",", $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) {
                    fputs($errors, "line [$num] of the file [$taxPayersFileName] is incorrect\n");
                    $nbErrors++;
                    continue;
                }
                // 我们计算税款
                $result = $this->calculateTax($married, (int) $children, (int) $salary);
                // 我们把结果写入结果文件
                $result = ["married" => $married, "children" => (int) $children, "salary" => (int) $salary] + $result;
                fputs($results, json_encode($result, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR) . "\n");
            }
            // 有错误吗?
            if ($nbErrors > 0) {
                throw new TaxException("There were $nbErrors incorrect line(s): see the file [$errorsFileName]", 15);
            }
        } finally {
            // 我们关闭已打开的文件
            foreach ([$data, $results, $errors] as $file) {
                if ($file !== false) {
                    fclose($file);
                }
            }
        }
    }

代码说明

  • 第 185 行:该方法接受三个参数:
    • [$taxPayersFileName]:包含纳税人数据的文本文件的名称。每行文本包含一位纳税人的数据,格式如下:婚姻状况(yes/no)、子女数、年薪;例如 [yes,2,55555];
    • [$resultsFileName]:将包含结果的文本文件的名称。每行文本将是表示一位纳税人结果的 JSON 字符串,例如 [{"married":"yes","children":2,"salary":50000,"tax":1384,"surcharge":0,"discount":384,"reduction":347,"rate":0.14}];
    • [$errorsFileName]:包含错误的文本文件的名称,例如 [line [5] of the file [taxpayersdata.txt] is incorrect];
  • 第 188 行:三个文件的变量都初始化为 [false] (文件未打开)。这样就可以在 [finally] 子句中确定哪些文件已被打开;
  • 第 190 行:由于许多操作都可能抛出异常,因此用一个 [try / finally] 结构包住整个方法的代码;
  • 第 192–204 行:打开三个文件。一旦某个打开操作失败,就抛出异常,每种情况使用不同的错误代码;
  • 第 210 行:逐行读取 [$data] 文件中的行,每次最多读取 100 个字符(所有行的长度都不到 100 个字符);
  • 第 214 行:使用静态方法 [Utilities::cutNewLineChar] 删除任何行尾字符;
  • 第 216–218 行:忽略空行(例如文件末尾的空行);
  • 第 220 行:该行按逗号拆分,并去除每个字段两侧的空格。[trim(...)] 是“一等可调用对象”(first-class callable,PHP 8.1)的语法:它引用 [trim] 函数本身而不调用它;
  • 第 221 行:该行必须恰好有三个字段。PHP 7 课程直接写了 [list($married, $children, $salary) = explode(",", $line)]:如果某一行只有两个字段,PHP 8 会发出“Undefined array key 2”警告;
  • 第 227–229 行:检查三个元素的有效性:婚姻状况必须是“yes”或“no”,子女数和年薪必须是正整数或零(一串数字,正则表达式 [/^\d+$/])。[true] 是 [in_array] 的第三个参数,它要求使用严格比较 [===];
  • 第 232–236 行:如果该行无效,不会抛出异常;而是把一条错误消息写入文本文件 [$errors], 然后程序继续处理下一行;
  • 第 238 行:如果读取的行有效,就计算税款。结果以关联数组 [tax, surcharge, discount, reduction, rate] 的形式返回;
  • 第 240 行:键 [married, children, salary] 被添加到结果的开头;
  • 第 241 行:结果以其 JSON 字符串的形式写入文本文件 [$results] 。选项 [JSON_THROW_ON_ERROR] 使函数 [json_encode] 在编码失败时抛出异常 [JsonException] ,而不是返回 [false] ;
  • 第 244–246 行:处理完 [$data] 文件后,检查遇到的错误行数。如果至少有一行错误,就抛出异常;
  • 第 247–254 行:无论方法如何结束执行(正常结束或通过异常),子句 [finally] 都会被执行:所有已打开的文件都会被关闭。PHP 7 课程使用的是 [try / catch / finally] 结构,其 [catch] 子句只是重新抛出异常。这是不必要的:不带 [try / finally] 结构的 [catch] ,能让异常在 [finally] 子句执行之后继续传播。此外,PHP 7 课程在没有验证三个文件是否已打开的情况下就关闭它们:在 PHP 8 中,[fclose(false)] 会导致 [TypeError] 错误。

8.7. [TaxWithTaxAdminDataInJsonFile] 类

抽象类 [AbstractBaseTax] 没有实现 [getTaxAdminData] 方法,该方法属于 [InterfaceTax] 接口。因此我们必须在派生类中定义它。我们在下面的派生类 [TaxWithTaxAdminDataInJsonFile] 中完成这件事:

<?php

declare(strict_types=1);

// 命名空间
namespace Application;

// 从 JSON 文件获取税务管理部门数据的类
class TaxWithTaxAdminDataInJsonFile extends AbstractBaseTax
{
    // 税务管理部门的数据
    private readonly TaxAdminData $taxAdminData;

    // 构造函数
    public function __construct(string $jsonFileName)
    {
        // 我们用 JSON 文件初始化 $this->taxAdminData
        // 可能抛出 TaxException 异常
        $this->taxAdminData = TaxAdminData::fromJsonFile($jsonFileName);
    }

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

说明

  • 第 9 行:[TaxWithTaxAdminDataInJsonFile] 类继承抽象类 [AbstractBaseTax]。它必须定义其父类没有定义的 [getTaxAdminData] 方法;
  • 第 12 行:属性 [$taxAdminData] 将包含税务机关的数据。它是只读的:由构造函数一次性初始化。请注意,父类也有一个私有属性 [$taxAdminData]:这两个属性是不同的,因为私有属性只在声明它的类内部可见;
  • 第 15–20 行:构造函数只接收一个参数,即包含税务数据的 JSON 文件的名称;
  • 第 19 行:根据 JSON 文件创建一个 [TaxAdminData] 类型的对象。此操作可能抛出 [TaxException] 类型的异常。该异常将一直传播到主脚本 [main.php];
  • 第 23–27 行:为父类没有定义的 [getTaxAdminData] 方法提供了方法体。这里只需确保属性 [$this->taxAdminData] 已由构造函数初始化即可。

8.8. 脚本 [main.php]

这些类和接口由下面的脚本 [main.php]使用:

<?php

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

// 命名空间
namespace Application;

// 引入这些接口和类
require_once __DIR__ . "/TaxException.php";
require_once __DIR__ . "/TaxAdminData.php";
require_once __DIR__ . "/Utilities.php";
require_once __DIR__ . "/InterfaceTax.php";
require_once __DIR__ . "/AbstractBaseTax.php";
require_once __DIR__ . "/TaxWithTaxAdminDataInJsonFile.php";

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

try {
    // 我们创建一个 [TaxWithTaxAdminDataInJsonFile] 对象
    $tax = new TaxWithTaxAdminDataInJsonFile(TAXADMINDATA_FILENAME);
    // 我们执行税款批处理
    $tax->executeBatchTaxes(TAXPAYERSDATA_FILENAME, RESULTS_FILENAME, ERRORS_FILENAME);
} catch (TaxException $ex) {
    // 我们显示错误
    print "Error no. {$ex->getCode()}: {$ex->getMessage()}\n";
}
// 结束
print "Done\n";

说明

  • 第 4 行:强制严格遵守函数参数的类型;
  • 第 7 行:脚本 [main.php] 同样位于 [Application] 命名空间中;
  • 第 10–15 行:加载脚本所用的类文件和接口文件。请注意,这里我们没有使用 [use] 语句来声明脚本所用类的完整名称。这是不必要的,因为脚本和这些类位于同一个命名空间 [Application] 中。还要注意加载顺序:父类或接口必须先于继承它或实现它的类加载;
  • 第 18–21 行:脚本中使用的文件名。这些名称是相对的:文件在当前目录(即执行脚本的目录)中查找;
  • 第 25 行:创建一个 [TaxWithTaxAdminDataInJsonFile] 对象。如果 JSON 文件缺失或不正确,这可能抛出异常;
  • 第 27 行:调用 [executeBatchTaxes] 方法,它将为 [TAXPAYERSDATA_FILENAME] 文件中的所有纳税人计算税款。结果将写入文件 [RESULTS_FILENAME], 任何错误将写入文件 [ERRORS_FILENAME];
  • 第 28–31 行:如果发生错误,则显示错误代码和消息。表达式 [{$ex->getCode()}] 可以把方法调用的结果插入字符串中。

8.9. 结果

在 [version-03] 文件夹中打开的终端里运行脚本:

1
2
3
> php main.php
Error no. 15: There were 2 incorrect line(s): see the file [errors.txt]
Done

使用上面显示的纳税人文件 [taxpayersdata.txt] ,会生成如下错误文件 [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}

为十一条正确的行计算出的税款(2814、1384、0、19884、16782、9200、4230、22986、0、64210、42842)与版本 1 和 2 中的相同。

8.10. 结论

版本 3 与版本 2 功能相同,但更善于处理错误:不完整或不正确的税务数据、纳税人文件中的错误行,或文件缺失。每个错误都由包含消息和特定代码的 [TaxException] 异常来标示。

然而,[AbstractBaseTax] 类把两类代码混在了一起:一方面是税款计算,另一方面是文件的读写。在后续章节中,我们将看到如何把这两个关注点分离到不同的层中。