Skip to content

7. 异常与错误

当类的某个方法遇到无法恢复的错误(文件不存在、数据库未连接、网络连接中断)时,它不会在控制台上显示错误(文件、数据库),而是抛出异常。异常继承自 [\Exception] 类。除了异常之外,PHP 的内部运行也会抛出错误,其基类是 [\Error]。这两个类都实现了 [\Throwable] 接口。

PHP 8 从根本上改变了错误处理方式:许多在 PHP 7 中只产生一条警告(且往往得到荒谬结果)的情况,现在会抛出可被捕获的错误。我们将在后面的示例中看到这一点。

7.1. 脚本目录结构

本章的脚本位于 [scripts-console/exceptions] 文件夹中:

1
2
3
4
5
6
php8-oct-2026/scripts-console/exceptions
├── exceptions-01.php
├── exceptions-02.php
├── ...
├── exceptions-11.php
└── throwables.php

7.2. [\Throwable] 接口

[\Throwable] 接口如下(参见文档):

interface Throwable extends Stringable
{
    public function getMessage(): string;
    public function getCode(): int;
    public function getFile(): string;
    public function getLine(): int;
    public function getTrace(): array;
    public function getTraceAsString(): string;
    public function getPrevious(): ?Throwable;
    public function __toString(): string;
}

该接口各方法的作用如下:

方法
用途
[getMessage]
返回错误消息
[getCode]
返回错误代码(整数)
[getFile]
返回创建该对象的文件名
[getLine]
返回创建该对象的行号
[getTrace]
以数组形式返回函数调用栈
[getTraceAsString]
以字符串形式返回调用栈
[getPrevious]
返回前一个(被封装的)[Throwable] 对象,或 [null]
[__toString]
返回对象的字符串表示

请注意,[Throwable] 接口扩展了类章节中讨论过的 [Stringable] 接口。类不能直接实现 [Throwable] 接口;它必须继承 [\Exception] 或 [\Error]。

7.3. PHP 8 中预定义的异常和错误

下面的 [throwables.php] 脚本显示所有实现 [Throwable] 接口的预定义类的树形结构。我们用它来获得一份准确的列表(即 PHP 8.5 的列表),而不是从文档中抄录。读者即使不去理解它的代码也不会错过什么,该代码使用了 PHP 的反射 API([ReflectionClass] 类允许你向 PHP 查询某个类的信息:名称、所属的原始扩展、实现的接口等)和一个递归函数:

<?php

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

// 显示实现 [Throwable] 接口的预定义类的树
// 我们只限于 PHP 8.5 中始终存在的扩展:
// 核心(Core)、标准库、SPL 库、JSON 和 Random
$extensions = ["Core", "standard", "SPL", "json", "random"];

// 这些扩展中实现 [Throwable] 的预定义类
$classes = array_filter(
    get_declared_classes(),
    function (string $class) use ($extensions): bool {
        $reflection = new ReflectionClass($class);
        return $reflection->isInternal()
            && $reflection->implementsInterface(Throwable::class)
            && in_array($reflection->getExtensionName(), $extensions, true);
    }
);
sort($classes);

// 递归显示类 [$parent] 的子类
function display(?string $parent, array $classes, string $indentation): void
{
    // [$parent] 的直接子类
    $children = array_values(array_filter(
        $classes,
        fn(string $class): bool => (get_parent_class($class) ?: null) === $parent
    ));
    foreach ($children as $i => $child) {
        $last = $i === count($children) - 1;
        print $indentation . ($last ? "└── " : "├── ") . $child . "\n";
        display($child, $classes, $indentation . ($last ? "    " : "│   "));
    }
}

print "Throwable\n";
display(null, $classes, "");

结果:

> php throwables.php
Throwable
├── Error
│   ├── ArithmeticError
│   │   └── DivisionByZeroError
│   ├── AssertionError
│   ├── CompileError
│   │   └── ParseError
│   ├── FiberError
│   ├── Random\RandomError
│   │   └── Random\BrokenRandomEngineError
│   ├── TypeError
│   │   └── ArgumentCountError
│   ├── UnhandledMatchError
│   └── ValueError
└── Exception
    ├── ClosedGeneratorException
    ├── ErrorException
    ├── JsonException
    ├── LogicException
    │   ├── BadFunctionCallException
    │   │   └── BadMethodCallException
    │   ├── DomainException
    │   ├── InvalidArgumentException
    │   ├── LengthException
    │   └── OutOfRangeException
    ├── Random\RandomException
    ├── RequestParseBodyException
    └── RuntimeException
        ├── OutOfBoundsException
        ├── OverflowException
        ├── RangeException
        ├── UnderflowException
        └── UnexpectedValueException

说明

  • 第 13 行:函数 [get_declared_classes] 返回此时已知的所有类的列表,无论是预定义的还是自定义的;
  • 第 16–18 行:只保留预定义(内部)类,即那些实现了 [Throwable] 接口且属于 PHP 8.5 中始终存在的扩展的类(第 9 行)。其他扩展会添加它们自己的异常(例如用于数据库访问的 [PDOException] ,我们稍后会遇到);
  • 第 24–36 行:一个递归函数,显示类 [$parent] 的直接子类,然后是其中每个子类的子类,依此类推。对于没有父类的类,函数 [get_parent_class] 返回 [false] :运算符 [?:] 随后把 [false] 转换为 [null];
  • 第 29 行:箭头函数(PHP 7.4),匿名函数的简写形式,只包含一个表达式;
  • 第 39 行:我们从没有父类的类开始:[Error] 和 [Exception]。

结果显示了两个家族:

  • [Exception] 家族:这是由库和应用程序代码抛出的异常。它包括:
    • [ErrorException],它把 PHP 的警告转换为异常(我们将在本章末尾用到它);
    • [JsonException] (PHP 7.3),在使用 [json_encode] 和 [json_decode] 并带有 [JSON_THROW_ON_ERROR] 选项时抛出;
    • [Random\RandomException] (PHP 8.2),由随机数生成函数引发;
    • 来自 SPL 库(Standard PHP Library,标准 PHP 库)的异常,SPL 是一组旨在解决开发人员经常遇到的问题的类和接口。它们构成两个子家族:
    • [LogicException] 及其派生类:通过修正代码即可解决的编程错误:无效参数([InvalidArgumentException])、值超出预期范围([DomainException])、不存在的方法([BadMethodCallException])等;
    • [RuntimeException] 及其变体:只能在运行时检测到的错误:索引越界([OutOfBoundsException])、意外的值([UnexpectedValueException])、容量溢出([OverflowException])等;
  • [Error] 家族:这是由 PHP 引擎本身抛出的错误。它们包括:
    • [TypeError]:值不是预期的类型(函数参数、带类型的属性、返回值、运算符的操作数等)。其派生类 [ArgumentCountError], 表示实参数量不足;
    • [ValueError] (PHP 8.0):值的类型正确但取值无效(例如长度为负数或零);
    • [ArithmeticError] 及其派生类 [DivisionByZeroError]:算术运算中的错误;
    • [UnhandledMatchError] (PHP 8.0):表达式 [match] 没有任何分支匹配;
    • [AssertionError]:[assert] 断言失败;
    • [CompileError] 及其派生类 [ParseError]:由 [require] 或 [include]加载的文件中存在语法错误;
    • [FiberError] (PHP 8.1)和 [Random\RandomError] (PHP 8.2):与纤程和随机数生成器相关的错误,我们不会用到。

这两个家族互不相关:[catch (\Exception $e)] 子句不会拦截 [Error] 错误。只有 [Throwable] 接口把它们联系在一起。

7.4. 示例 1

第一个示例 [exceptions-01.php],同时展示了 PHP 警告和错误:

<?php

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

// 显示所有错误
error_reporting(E_ALL);
ini_set("display_errors", "1");
// 代码
$var = [];
// 未知键
print $var["abcd"];
// 除以零
$var = 7 / 0;
var_dump($var);
// 固定边界的数组
$array = new \SplFixedArray(5);
$array[1] = 2;
$array[4] = "foo";
// 索引越界
$array[5] = 8;

说明

  • 第 7 行:指示 PHP 报告所有错误。[error_reporting] 函数的参数是错误报告级别,它是下列常量(主要的几个)的组合:
常量
含义
[E_ERROR]
致命的运行时错误:脚本终止
[E_WARNING]
警告:脚本继续执行
[E_PARSE]
编译期间检测到的语法错误
[E_NOTICE]
注意:可能是错误的情况
[E_DEPRECATED]
使用了已弃用的特性,该特性将在未来版本中移除
[E_USER_WARNING], [E_USER_NOTICE], [E_USER_DEPRECATED]
相同的级别,由使用 [trigger_error] 函数的代码触发
[E_ALL]
所有级别
  • 常量 [E_STRICT]自 PHP 8.0 起不再对应任何消息,并自 PHP 8.4 起被弃用,在 [E_USER_ERROR] 级别与 [trigger_error] 一起使用的做法同样已被弃用:要报告致命错误,代码应抛出异常;
  • 第 8 行:代码被设置为在控制台上显示错误。在生产环境中则相反:错误被写入日志文件而不显示;
  • 第 12 行:尝试访问数组 [$var]中不存在的元素;
  • 第 14 行:发生了除以零;
  • 第 17 行:创建了 SPL 库中 [SplFixedArray] 类的一个实例。该类允许创建带固定边界、以整数为索引的数组;
  • 第 21 行:尝试访问该数组中不存在的元素。

结果:

1
2
3
4
5
6
7
8
> php exceptions-01.php

Warning: Undefined array key "abcd" in .../php8-oct-2026/scripts-console/exceptions/exceptions-01.php on line 12

Fatal error: Uncaught DivisionByZeroError: Division by zero in .../php8-oct-2026/scripts-console/exceptions/exceptions-01.php:14
Stack trace:
#0 {main}
  thrown in .../php8-oct-2026/scripts-console/exceptions/exceptions-01.php on line 14

结果说明

  • 第 3 行:访问数组中不存在的键会触发 [E_WARNING] 级别的警告(在 PHP 7 中只是一个简单的通知 [E_NOTICE] )。这不会中断脚本的执行;
  • 第 5–8 行:在 PHP 7 中,一个数字除以零会触发 [E_WARNING] 警告,并返回值 [INF] (无穷大)。在 PHP 8 中,运算符 [/] 会触发 [DivisionByZeroError] 类型的错误。由于它没有被捕获,因此会中断脚本的执行:这是一个致命错误(Fatal error: Uncaught...)。消息显示了错误发生时的调用栈(Stack trace);
  • 除法之后的代码不会被执行:对数组 [SplFixedArray] 中不存在的索引的访问并未发生。我们会在后面的示例中再次看到这一点。

7.5. 处理异常

脚本 [exceptions-02.php] 演示了如何处理异常:

<?php

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

// 我们显示所有错误
error_reporting(E_ALL);
ini_set("display_errors", "1");
// 我们用 try / catch 包围代码
try {
    $var = [];
    // 未知键
    print $var["abcd"];
    // 除以零
    $var = 7 / 0;
    var_dump($var);
    // 固定边界的数组
    $array = new \SplFixedArray(5);
    $array[1] = 2;
    $array[4] = "foo";
    // 索引越界
    $array[5] = 8;
    // 检查
    print "this message will not be displayed\n";
} catch (\Throwable $ex) {
    // \Throwable 是所有错误和异常实现的接口
    // 我们显示异常
    print "error, message: " . $ex->getMessage() . ", type: " . $ex::class . "\n";
}

说明

  • 该脚本就是上一段介绍的脚本。不过,我们现在把可能引发错误的代码放在了 [try / catch] 结构中:如果第 11–24 行的代码引发(抛出)异常或错误,它将由第 25–29 行的 [catch] 子句处理;
  • 第 25 行:[catch] 子句的参数是要处理的异常或错误的类型。把类型设为 [\Throwable](它是一个接口),表示我们想处理实现了 [\Throwable] 接口的任何类实例。由于所有错误类和异常类都实现了该接口,因此这里的 [catch] 子句处理所有错误和异常;
  • 第 15 行:触发错误的语句。异常一旦发生,控制权就转移到 [catch] 子句。因此 [try] 中后面的代码不会被执行;
  • 第 28 行:写法 [$ex::class] 返回对象 [$ex]的类名。

结果:

1
2
3
4
> php exceptions-02.php

Warning: Undefined array key "abcd" in .../php8-oct-2026/scripts-console/exceptions/exceptions-02.php on line 13
error, message: Division by zero, type: DivisionByZeroError

结果说明

  • 第 3 行:我们看到了 [E_WARNING] 级别的警告。警告不是异常,因此不会被 [catch] 子句处理。我们将在本章末尾看到如何把警告转换为异常;
  • 第 4 行:错误消息是在 [catch] 子句中写出的。这意味着发生了派生自 [\Exception] 的异常或派生自 [\Error] 的错误。这里我们看到它是类 [DivisionByZeroError]。脚本正常结束。

7.6. [catch] 子句的参数

我们来看下面的 [exceptions-03.php] 脚本:

<?php

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

// 我们显示所有错误
error_reporting(E_ALL);
ini_set("display_errors", "1");

// 一个固定边界的数组
$array = new \SplFixedArray(5);
try {
    // 索引越界
    $array[5] = 8;
} catch (\Throwable $ex) {
    // 显示错误消息
    print "Error 1: " . $ex->getMessage() . " (" . $ex::class . ")\n";
}

try {
    // 索引越界
    $array[5] = 8;
} catch (\Exception $ex) {
    // 显示错误消息
    print "Error 2: " . $ex->getMessage() . "\n";
}

try {
    // 索引越界
    $array[5] = 8;
} catch (\RuntimeException $ex) {
    // 显示错误消息
    print "Error 3: " . $ex->getMessage() . "\n";
}

try {
    // 索引越界
    $array[5] = 8;
} catch (\OutOfBoundsException $ex) {
    // 显示错误消息
    print "Error 4: " . $ex->getMessage() . "\n";
}

try {
    // 除以 0
    intdiv(5, 0);
} catch (\Throwable $ex) {
    // 显示错误消息
    print "Error 5: " . $ex->getMessage() . " (" . $ex::class . ")\n";
}

try {
    // 除以 0
    intdiv(5, 0);
} catch (\DivisionByZeroError $ex) {
    // 显示错误消息
    print "Error 6: " . $ex->getMessage() . "\n";
}

try {
    // 除以 0
    intdiv(5, 0);
} catch (\ArithmeticError $ex) {
    // 显示错误消息
    print "Error 7: " . $ex->getMessage() . "\n";
}

try {
    // 除以 0
    intdiv(5, 0);
} catch (\Error $ex) {
    // 显示错误消息
    print "Error 8: " . $ex->getMessage() . "\n";
}

try {
    // 除以 0
    intdiv(5, 0);
} catch (\Exception $ex) {
    // 显示错误消息
    print "Error 9: " . $ex->getMessage() . "\n";
}

说明

  • 第 11–41 行:处理因对 [\SplFixedArray] 类使用错误索引而产生的异常的四种不同方式。执行结果表明,该错误产生 [OutOfBoundsException] 类型的异常(结果的第 2 行)。在 PHP 7 课程中(以及 PHP 8.3 中),它是 [RuntimeException] 异常。这一变化并未破坏现有代码,因为 [OutOfBoundsException] 类派生自 [RuntimeException] 类;
    • 第 15 行:处理 [\Throwable] 类型的错误。这是有效的,因为类型 [OutOfBoundsException] 派生自类型 [\Exception],而后者实现了接口 [\Throwable];
    • 第 23 行:处理 [\Exception] 类型的错误。这是有效的,因为类型 [OutOfBoundsException] 派生自类型 [\Exception];
    • 第 31 行:处理 [\RuntimeException] 类型的错误。这是有效的,因为类型 [OutOfBoundsException] 派生自类型 [\RuntimeException]。这是个好选择:无论 PHP 是哪个版本,代码都能工作;
    • 第 39 行:处理所产生异常的确切类型;
  • 第 46–81 行:处理函数 [intdiv] 在被传入等于 0 的除数时所产生错误的 5 种不同方式。函数 [intdiv(int $dividend, int $divisor): int] 执行整数除法 [$dividend / $divisor]。当除数为零时,会抛出错误 [\DivisionByZeroError];
    • 第 47 行:捕获任何实现了 [\Throwable] 接口的错误。这是有效的;
    • 第 55 行:拦截错误的确切类型;这是首选的方法;
    • 第 63 行:捕获类型 [\ArithmeticError]。这是有效的,因为类 [DivisionByZeroError] 继承了类 [ArithmeticError];
    • 第 71 行:拦截类型 [\Error]。这是有效的,因为类 [DivisionByZeroError] 派生自类 [Error];
    • 第 79 行:拦截类型 [\Exception]。这是无效的,因为类 [DivisionByZeroError] 与类 [\Exception]没有任何关系。

结果:

> php exceptions-03.php
Error 1: Index invalid or out of range (OutOfBoundsException)
Error 2: Index invalid or out of range
Error 3: Index invalid or out of range
Error 4: Index invalid or out of range
Error 5: Division by zero (DivisionByZeroError)
Error 6: Division by zero
Error 7: Division by zero
Error 8: Division by zero

Fatal error: Uncaught DivisionByZeroError: Division by zero in .../php8-oct-2026/scripts-console/exceptions/exceptions-03.php:78
Stack trace:
#0 .../php8-oct-2026/scripts-console/exceptions/exceptions-03.php(78): intdiv(5, 0)
#1 {main}
  thrown in .../php8-oct-2026/scripts-console/exceptions/exceptions-03.php on line 78

结果的第 11–15 行表明,错误 [DivisionByZeroError] 没有被最后一个子句 [catch (\Exception $ex)]捕获:这是一个致命错误。

7.7. 子句 [finally]

结构 [try / catch] 可以有第三个部分,成为 [try / catch / finally] 结构。子句 [finally] 中的代码在以下两种情况下执行:

  • [try] 子句没有抛出异常。此时它被完整执行,然后转到 [finally] 子句,并完整执行该子句;
  • 子句 [try] 抛出了异常。此时它执行到抛出异常的语句为止。然后转到子句 [catch],并完整执行它。接着转到子句 [finally], 并完整执行它。

最后,子句 [finally] 中的代码仍然会被执行。这种机制在以下情形中很有用:

  • 在 [try] 子句中,代码获取了资源(文件、数据库、网络连接、队列)。这些资源通常开销很大,因此必须尽快释放(通常称为“关闭”);
  • 如果资源是在 [try] 中获取的,它们的释放将在 [finally] 中处理。这样就能确保在任何情况下(无论是否发生错误),所获取的资源都会归还给系统。

下面的脚本 [exceptions-04.php],演示了 [finally] 子句在各种情况下的工作方式:

<?php

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

// 我们创建一个异常实例
$e = new \Exception("Error...");

// 第一个测试
try {
    print "First test\n";
    throw $e;
} catch (\Exception $ex1) {
    print $ex1->getMessage() . "\n";
} finally {
    print "Done\n";
}

// 第二个测试
try {
    print "Second test\n";
} catch (\Exception $ex1) {
    print $ex1->getMessage() . "\n";
} finally {
    print "Done\n";
}

// 第三个测试
try {
    print "Third test\n";
    return;
} catch (\Exception $ex1) {
    print $ex1->getMessage() . "\n";
} finally {
    print "Done\n";
}

代码说明

  • 第 7 行:[$e] 是预定义类 [\Exception] 的一个实例。我们将在不同的位置实例化它;
  • 第 11–12 行:异常 [$e] 在 [try] 中由语句 [throw] 抛出;
  • 第 13 行:捕获 [\Exception] 异常,并把其错误消息写到控制台;
  • 第 15–16 行:[finally] 子句写出一条消息。根据前面所述,无论 [try] 中是否有错误,这条消息都应该被写出;
  • 第 21 行:[try] 中没有错误。这里同样,程序应转到 [finally];
  • 第 31 行:[try] 子句中有一条 [return] 语句,且没有错误。这就引出一个问题:脚本是否会转到 [finally] 子句。执行表明会。在函数之外使用时,[return] 语句会终止脚本。

结果:

1
2
3
4
5
6
7
8
> php exceptions-04.php
First test
Error...
Done
Second test
Done
Third test
Done

我们来看另一种情况 [exceptions-05.php]:

<?php

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

// 第四个测试
try {
    print "Fourth test\n";
    exit;
} finally {
    print "Done\n";
}

说明

  • 第 9 行:语句 [exit] 立即终止脚本的执行:子句 [finally] 不会被执行;
  • 第 7–12 行:一个不带 [try / finally] 而无 [catch] 子句的示例。这是允许的。

结果:

> php exceptions-05.php
Fourth test

7.8. 创建自己的异常类

在规模较大的项目中,通过把各种错误封装到不同的异常类中来区分它们是很有用的。在前面的脚本中,我们看到任何异常都可以被 [catch (\Throwable $ex)] 子句捕获。如果你不清楚被拦截的错误是什么,并且对所有错误的处理方式都相同,建议这样做。有时确实如此,但通常需要根据错误的确切类型来调整处理方式。这时就需要区分不同的错误。

我们来看下面的 [exceptions-06.php] 脚本:

<?php

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

// 我们定义自己的异常族
class Exception1 extends \RuntimeException
{
}

class Exception2 extends \RuntimeException
{
}

// 我们使用我们的异常
$e1 = new Exception1("Error1...");
var_dump($e1);
$e2 = new Exception2("Error2...", 2);

// 第一个测试
print "first test\n";
try {
    // 我们抛出 Exception1 类型的异常
    throw $e1;
} catch (Exception1 $ex1) {
    print "Exception 1\n";
    print $ex1->getMessage() . "\n";
} catch (Exception2 $ex2) {
    print "Exception 2\n";
    print $ex2->getMessage() . "\n";
}

// 第二个测试
print "second test\n";
try {
    // 我们抛出 Exception2 类型的异常
    throw $e2;
} catch (Exception1 $ex1) {
    print "Exception 1\n";
    print $ex1->getMessage() . "\n";
} catch (Exception2 $ex2) {
    print "Exception 2\n";
    print $ex2->getMessage() . "\n";
}

// 第三个测试
print "third test\n";
try {
    // 我们抛出 Exception1 类型的异常
    throw $e1;
} catch (Exception1 | Exception2 $ex) {
    print "Exception 1 or 2\n";
    print $ex->getMessage() . "\n";
}

// 第四个测试
print "fourth test\n";
try {
    // 我们抛出 Exception2 类型的异常
    throw $e2;
} catch (Exception1 | Exception2 $ex) {
    print "Exception 1 or 2: " . $ex::class . "\n";
    // 异常携带的信息
    print "message: " . $ex->getMessage() . "\n";
    print "code: " . $ex->getCode() . "\n";
    print "file: " . basename($ex->getFile()) . "\n";
    print "line: " . $ex->getLine() . "\n";
}

说明

  • 第 7–9 行:我们定义了两个类 *[Exception1] 和 *[Exception2],它们都派生自预定义类 ***[\\RuntimeException]***。这些类的主体是空的。换句话说,它们只因其类型而被使用:正因为它们的类型不同,我们才能在 [catch] 子句中区分这两个异常;
  • 第 16–18 行:我们定义了两个变量 [$e1] 和 [$e2], 它们的类型分别是 [Exception1] 和 [Exception2], 。所用的构造函数是 [Exception] 类的构造函数,其签名为 [__construct(string $message = "", int $code = 0, ?Throwable $previous = null)]。对于 [$e2],指定了一个错误代码;
  • 第 21–31 行:这里有一个 [try / catch / catch] 结构。它允许用不同的 [catch] 子句处理不同类型的异常。第一个类型匹配的子句会被执行,其余的被忽略;
  • 第 25 行:拦截 [Exception1] 类型的异常;
  • 第 28 行:拦截 [Exception2] 类型的异常;
  • 第 51 行:拦截 [Exception1] 或([|])[Exception2] 类型的异常。这种语法自 PHP 7.1 起可用;
  • 第 62 行:被拦截异常的类名;
  • 第 64–67 行:异常中包含的信息,通过 [Throwable] 接口的方法获得。[basename] 函数返回不含文件夹路径的文件名。

结果:

> php exceptions-06.php
object(Exception1)#1 (7) {
  ["message":protected]=>
  string(9) "Error1..."
  ["string":"Exception":private]=>
  string(0) ""
  ["code":protected]=>
  int(0)
  ["file":protected]=>
  string(76) ".../php8-oct-2026/scripts-console/exceptions/exceptions-06.php"
  ["line":protected]=>
  int(16)
  ["trace":"Exception":private]=>
  array(0) {
  }
  ["previous":"Exception":private]=>
  NULL
}
first test
Exception 1
Error1...
second test
Exception 2
Error2...
third test
Exception 1 or 2
Error1...
fourth test
Exception 1 or 2: Exception2
message: Error2...
code: 2
file: exceptions-06.php
line: 18

结果说明

  • 第 2–18 行:异常的“内容”,由 [var_dump] 显示:
    • 第 3–4 行:错误消息;
    • 第 7–8 行:错误代码;
    • 第 9–10 行:引发异常的文件名。所示的长度(string(76))是完整文件路径的长度:它取决于脚本所在的文件夹;
    • 第 11–12 行:引发异常的行;
    • 第 13–15 行:引发异常时的调用栈。这里它是空的,因为异常是在主脚本而不是在函数内部引发的;
    • 第 16–17 行:前一个异常。一个异常可以封装另一个异常,从而定义出异常栈。[previous] 属性可用于分析这个栈;
  • 第 29–33 行:请注意,异常的文件和行号是由 [new] 创建它时(第 18 行)的文件和行号,而不是由 [throw] 抛出它时的。

7.9. 重新抛出异常

一个异常可以被多次抛出,如下面的脚本 [exceptions-07.php]所示:

<?php

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

try {
    try {
        // 我们抛出一个异常
        throw new \Exception("test");
    } catch (\Exception $ex) {
        // 我们重新抛出捕获到的异常
        throw $ex;
    } finally {
        // 我们确实会经过 finally
        print "finally 1\n";
    }
} catch (\Exception $ex2) {
    // 我们确实取回了最初的异常
    print $ex2->getMessage() . " in outer try / catch / finally\n";
} finally {
    // 我们确实会经过 finally
    print "finally 2\n";
}

说明

  • 第 9 行:抛出一个异常;
  • 第 10 行:捕获该异常;
  • 第 12 行:重新抛出该异常。随后它被传递给上一层的 [try / catch / finally] 结构。这种情形很常见:代码拦截异常以进行本地处理(写日志、回滚事务等),然后重新抛出,以便调用方代码也得到通知;
  • 第 17 行:它再次被拦截;
  • 第 13–15 行:执行结果表明,即使在第 12 行的 [throw] 之后,程序确实仍会转到内层 [finally] 子句,即内部的 [try / catch / finally] 结构。

结果:

1
2
3
4
> php exceptions-07.php
finally 1
test in outer try / catch / finally
finally 2

7.10. 处理异常栈

一个异常可以封装另一个异常,后者又可以封装其他异常,最终形成异常栈。下面是一个示例:[exceptions-08.php]:

<?php

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

// 我们定义自己的异常族
class Exception1 extends \RuntimeException
{
}

class Exception2 extends \RuntimeException
{
}

class Exception3 extends \RuntimeException
{
}

// 我们使用我们的异常
$e1 = new Exception1("Error 1...", 1, new Exception2("Error 2...", 2, new Exception3("Error 3...")));
var_dump($e1);
// 使用异常栈
$e = $e1;
do {
    // 当前异常的错误消息
    print $e::class . ": " . $e->getMessage() . "\n";
    // 我们转到前一个异常(如果没有则为 null)
    $e = $e->getPrevious();
} while ($e !== null);

说明

  • 第 7–15 行:定义三个派生自预定义异常 [RuntimeException] 的异常类;
  • 第 20 行:[Exception3] 类的一个实例被封装在 [Exception2] 类的一个实例中,而后者本身又被封装在 [Exception1] 类的一个实例中。这里使用的构造函数是 [Exception] 类的构造函数:[__construct(string $message = "", int $code = 0, ?Throwable $previous = null)]。构造函数的第三个参数允许封装一个异常。这在以下场景中会很有用:
    • 定义了一个方法 M,它可以抛出 [Exception1] 类型的异常——并且只能是该类型——这是出于兼容性的原因,例如为了与某个接口保持一致;
    • 然而,方法 M 内部可能发生其他类型的异常。为了把错误传回调用方法 M 的代码,这些异常会被封装为 [Exception1] 类型,然后再抛出。这样可以确保被封装的异常(即错误的原始原因)所包含的信息不会丢失;
  • 第 24–29 行:演示如何遍历嵌套在某个异常中的异常栈。方法 [getPrevious] 返回被封装的异常,如果没有则返回 [null] 。[do ... while] 循环至少执行一次其循环体,然后在条件为真时继续执行。

结果:

> php exceptions-08.php
object(Exception1)#1 (7) {
  ["message":protected]=>
  string(10) "Error 1..."
  ["string":"Exception":private]=>
  string(0) ""
  ["code":protected]=>
  int(1)
  ["file":protected]=>
  string(76) ".../php8-oct-2026/scripts-console/exceptions/exceptions-08.php"
  ["line":protected]=>
  int(20)
  ["trace":"Exception":private]=>
  array(0) {
  }
  ["previous":"Exception":private]=>
  object(Exception2)#2 (7) {
    ["message":protected]=>
    string(10) "Error 2..."
    ["string":"Exception":private]=>
    string(0) ""
    ["code":protected]=>
    int(2)
    ["file":protected]=>
    string(76) ".../php8-oct-2026/scripts-console/exceptions/exceptions-08.php"
    ["line":protected]=>
    int(20)
    ["trace":"Exception":private]=>
    array(0) {
    }
    ["previous":"Exception":private]=>
    object(Exception3)#3 (7) {
      ["message":protected]=>
      string(10) "Error 3..."
      ["string":"Exception":private]=>
      string(0) ""
      ["code":protected]=>
      int(0)
      ["file":protected]=>
      string(76) ".../php8-oct-2026/scripts-console/exceptions/exceptions-08.php"
      ["line":protected]=>
      int(20)
      ["trace":"Exception":private]=>
      array(0) {
      }
      ["previous":"Exception":private]=>
      NULL
    }
  }
}
Exception1: Error 1...
Exception2: Error 2...
Exception3: Error 3...
  • 第 2–50 行:异常 [$e1] 在其属性 [previous], 中包含异常 [Exception2](第 17–49 行),而它本身又包含异常 [Exception3] (第 32–48 行);
  • 第 51–53 行:异常的调用栈跟踪。

7.11. PHP 7 中的警告在 PHP 8 中变成了错误

我们已经看到,除以零在 PHP 7 中产生警告,而在 PHP 8 中触发错误。这不是个别情况:PHP 8 把许多警告——此前它们会带着错误的结果继续执行——转换成了错误。脚本 [exceptions-09.php] 演示了其中几种:

<?php

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

// 显示错误的类型和消息
function display(int $n, \Throwable $ex): void
{
    print "$n - " . $ex::class . ": " . $ex->getMessage() . "\n";
}

// 一个带两个参数的函数
function sum(int $a, int $b): int
{
    return $a + $b;
}

// 1 - 未定义的变量:只是一个警告(PHP 7 中为 Notice,PHP 8 中为 Warning)
print "1 - [" . $unknown . "]\n";
// 2 - 对零取模:PHP 7 中是警告加错误结果,PHP 8 中是错误
try {
    print 1 % 0;
} catch (\DivisionByZeroError $ex) {
    display(2, $ex);
}
// 3 - 对数组进行算术运算
try {
    print [] + 1;
} catch (\TypeError $ex) {
    display(3, $ex);
}
// 4 - 对非数值字符串进行算术运算
try {
    print "abc" * 2;
} catch (\TypeError $ex) {
    display(4, $ex);
}
// 5 - 预定义函数的参数类型错误
try {
    print strlen([1, 2]);
} catch (\TypeError $ex) {
    display(5, $ex);
}
// 6 - 参数类型正确但值无效
try {
    print_r(array_chunk([1, 2, 3], 0));
} catch (\ValueError $ex) {
    display(6, $ex);
}
// 7 - 参数不足
try {
    print sum(1);
} catch (\ArgumentCountError $ex) {
    display(7, $ex);
}
// 8 - [match] 表达式没有匹配的分支(PHP 8.0)
try {
    $day = 8;
    print match ($day) {
        6, 7 => "weekend",
        1, 2, 3, 4, 5 => "weekday",
    };
} catch (\UnhandledMatchError $ex) {
    display(8, $ex);
}
// 9 - 对 null 调用方法
try {
    $object = null;
    $object->method();
} catch (\Error $ex) {
    display(9, $ex);
}
// 10 - nullsafe 运算符 ?-> 避免了上述错误:结果为 null
var_dump($object?->method());

结果:

> php exceptions-09.php

Warning: Undefined variable $unknown in .../php8-oct-2026/scripts-console/exceptions/exceptions-09.php on line 19
1 - []
2 - DivisionByZeroError: Modulo by zero
3 - TypeError: Unsupported operand types: array + int
4 - TypeError: Unsupported operand types: string * int
5 - TypeError: strlen(): Argument #1 ($string) must be of type string, array given
6 - ValueError: array_chunk(): Argument #2 ($length) must be greater than 0
7 - ArgumentCountError: Too few arguments to function sum(), 1 passed in .../php8-oct-2026/scripts-console/exceptions/exceptions-09.php on line 52 and exactly 2 expected
8 - UnhandledMatchError: Unhandled match case 8
9 - Error: Call to a member function method() on null
NULL

说明

  • 第 19 行:使用未定义的变量仍然只是一个警告,但级别为 [E_WARNING](在 PHP 7 中是 [E_NOTICE] 通知)。该变量被设为 [null], 脚本继续执行(结果的第 2–4 行);
  • 第 22 行:除以零触发错误 [DivisionByZeroError] (第 5 行)。这在 PHP 7 中就已如此:当时只有使用 [/] 运算符做除以零才只产生一个简单的警告;
  • 第 28 行:对数组进行算术运算会导致 [TypeError] 错误(第 6 行);
  • 第 34 行:在 PHP 7 中,对非数字字符串进行算术运算会触发警告“A non-numeric value encountered”,并且该字符串被当作 0。在 PHP 8 中,这是 [TypeError] 错误(第 7 行)。数字字符串(["12" * 2])仍然被接受;
  • 第 40 行:在 PHP 7 中,向预定义函数传递类型错误的参数会触发警告,并且函数返回 [null]。在 PHP 8 中,所有预定义函数都会像开发者编写的函数一样抛出 [TypeError] 错误(第 8 行)。消息通过参数的序号和名称来标识该参数;
  • 第 46 行:参数类型正确([int])但值无效(长度必须为正数):这是错误 [ValueError],PHP 8.0 新增(第 9 行)。在 PHP 7 中,这是一个警告;
  • 第 52 行:[sum] 函数需要两个实参但只收到一个:错误 [ArgumentCountError] (第 10 行);
  • 第 59–62 行:表达式 [match] 没有对应值 8 的分支,也没有 [default] 分支:错误 [UnhandledMatchError] (第 11 行)。这与 [switch] 语句有显著差异,当没有任何 [case] 匹配时,后者什么也不做;
  • 第 69 行:在 [null] 上调用方法会导致 [Error] 错误(第 12 行)。这在 PHP 7 中就已如此;
  • 第 74 行:空安全运算符 [?->] (PHP 8.0)在对象为 [null] 时返回 [null],而不是调用方法。这避免了编写 [if ($object !== null)] 测试(第 13 行)。

这些变化使 PHP 8 程序更加安全:错误会中止处理,而不是让处理带着错误的数据继续进行。它们也要求开发者加入相应的 [catch] 子句。

7.12. 多个 [catch]、[catch] 不带变量,以及 [throw] 表达式

脚本 [exceptions-10.php] 展示了 PHP 8 的三个特性以及异常处理的一种常见用法:

<?php

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

// 自 PHP 8.0 起 [throw] 是表达式:可以用在 ?? 之后或箭头函数中
function readAge(array $data): int
{
    $age = $data["age"] ?? throw new \InvalidArgumentException("The age is missing");
    return is_int($age) && $age >= 0 ? $age : throw new \DomainException("Invalid age [$age]");
}

// 只抛出异常的箭头函数
$forbidden = fn(string $operation) => throw new \LogicException("Operation [$operation] forbidden");

// 测试数据
$tests = [["age" => 48], [], ["age" => -4]];
foreach ($tests as $i => $data) {
    try {
        print "test $i: age=" . readAge($data) . "\n";
    } catch (\InvalidArgumentException | \DomainException $ex) {
        // 一个 [catch] 子句处理两种异常类型
        print "test $i: " . $ex::class . ": " . $ex->getMessage() . "\n";
    }
}

try {
    $forbidden("deletion");
} catch (\LogicException) {
    // 自 PHP 8.0 起,[catch] 子句的变量是可选的
    print "the operation was refused\n";
}

// 将底层异常包装为应用程序异常
class DaoException extends \RuntimeException
{
}

function readConfiguration(string $json): array
{
    try {
        return json_decode($json, true, flags: JSON_THROW_ON_ERROR);
    } catch (\JsonException $ex) {
        // 原始原因作为第 3 个参数传递:它不会丢失
        throw new DaoException("Unreadable configuration", 10, $ex);
    }
}

try {
    readConfiguration('{"dsn": "mysql:host=localhost"');
} catch (DaoException $ex) {
    print $ex::class . ": " . $ex->getMessage() . " (code " . $ex->getCode() . ")\n";
    print "cause: " . $ex->getPrevious()::class . ": " . $ex->getPrevious()->getMessage() . "\n";
}

结果:

1
2
3
4
5
6
7
> php exceptions-10.php
test 0: age=48
test 1: InvalidArgumentException: The age is missing
test 2: DomainException: Invalid age [-4]
the operation was refused
DaoException: Unreadable configuration (code 10)
cause: JsonException: Syntax error

说明

  • 第 9 行:从 PHP 8.0 起,[throw] 是表达式,不再只是指令。因此它可以用在任何需要值的地方:这里用在 [??] 运算符之后。如果键 [age] 不存在,就抛出异常;否则,把它的值赋给 [$age] ;
  • 第 10 行:[throw] 用在条件表达式 [? :]中;
  • 第 14 行:一个函数体只是抛出异常的箭头函数。在 PHP 8.0 之前这是不可能的:箭头函数只能包含一个表达式;
  • 第 21 行:一个 [catch] 子句同时处理两种异常类型(结果的第 3–4 行)。请注意,[InvalidArgumentException] 和 [DomainException] 都派生自 [LogicException]:使用 [catch (\LogicException $ex)] 也会有相同的效果;
  • 第 29 行:从 PHP 8.0 起,如果你不需要异常本身而只需要它的类型,则 [catch] 子句中的变量是可选的(第 5 行);
  • 第 35–37 行:一个应用程序专用的异常。在后续章节中,我们将编写数据访问层(DAO,Data Access Object),无论错误来自何处(文件、JSON、数据库),它们都只会抛出这种类型的异常;
  • 第 39–47 行:函数 [readConfiguration] 解码一个 JSON 字符串。底层异常 [JsonException] 被拦截并(第 45 行)包装为 [DaoException] 异常。原始原因作为构造函数的第三个参数传入;
  • 第 53 行:调用方代码只知道 [DaoException],但它可以使用 [getPrevious] 方法取回错误的原始原因(结果的第 6–7 行)。

7.13. 将警告转换为异常:[ErrorException]

尽管 PHP 8 有所改进,某些异常情况仍然只是警告:数组键不存在、变量未定义、用 [fopen] 无法打开文件等。这些警告无法被 [try / catch] 拦截。不过,你可以安装一个错误处理器,把它们转换为 [ErrorException] 异常。[exceptions-11.php] 脚本正是这样做的:

<?php

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

// 错误处理器:将 PHP 警告转换为 [ErrorException] 异常
set_error_handler(function (int $level, string $message, string $file, int $line): bool {
    throw new \ErrorException($message, 0, $level, $file, $line);
});

// 未知键不再只引发警告,而是引发异常
$person = ["lastName" => "Langevin"];
try {
    print $person["firstName"] . "\n";
} catch (\ErrorException $ex) {
    print "Error: " . $ex->getMessage() . " (line " . $ex->getLine() . ")\n";
    print "level E_WARNING: " . var_export($ex->getSeverity() === E_WARNING, true) . "\n";
}
// 打开不存在的文件也是如此
try {
    $stream = fopen(__DIR__ . "/nonexistent.txt", "r");
} catch (\ErrorException $ex) {
    print "Error: " . $ex->getMessage() . "\n";
}
// 我们恢复 PHP 的错误处理器
restore_error_handler();
print "end\n";

结果:

1
2
3
4
5
> php exceptions-11.php
Error: Undefined array key "firstName" (line 14)
level E_WARNING: true
Error: fopen(.../php8-oct-2026/scripts-console/exceptions/nonexistent.txt): Failed to open stream: No such file or directory
end

说明

  • 第 7–9 行:[set_error_handler] 函数设置一个错误处理器——每当出现警告、通知或弃用提示时,PHP 就会调用它,而不是显示消息。它接收错误级别、错误消息、发生错误的文件和行号。这里,它抛出一个存储这些信息的 [ErrorException] 异常。返回类型 [bool] 是 [set_error_handler] 文档中规定的:函数返回 [false] 就是让 PHP 按常规方式处理错误。这里它永远不会返回任何东西,因为它总是抛出异常;
  • 第 14 行:键 [firstName] 不存在。此时不是产生警告,而是抛出 [ErrorException] 异常,并被捕获(结果的第 2 行);
  • 第 17 行:方法 [getSeverity]是 [ErrorException] 类特有的,返回原始错误的级别(第 3 行);
  • 第 21 行:尝试打开不存在的文件同样会导致异常(第 4 行);
  • 第 26 行:恢复之前的错误处理器,这里是 PHP 自带的那个。

许多 PHP 框架(Symfony、Laravel)都使用这一技术:在开发期间,任何警告都会变成异常,这迫使开发者修正代码。我们稍后将使用的 [PHPUnit] 测试工具的工作方式与此类似:如果测试产生警告或弃用提示,它可以让测试失败。