错误处理

是什么，为什么存在

PHP 的错误处理首先是一套诊断政策。引擎发现未定义数组键、弃用用法或用户触发的警告时，会给诊断附上 错误级别（error level） 。error_reporting 掩码决定默认机制报告哪些级别，display_errors 与 log_errors 再决定把选中的信息送到哪里。

另一条失败通道是 Throwable 对象。用户代码通常抛出 异常（exception） ，引擎则会为类型错误、值错误和许多运行时失败创建 Error 子类。两者都可以通过 try/catch 处理，但 set_error_handler() 不会接收这些对象。

名称很容易造成混淆。Error 是实现 Throwable 的类，E_ERROR 是整数诊断级别；捕获 Error 与注册 E_ERROR 掩码不是同一件事。异常的分类、传播和清理属于 php/exceptions，这里关注诊断如何被选择、转换、记录和限制。

应用会在开发、测试和生产中采用不同的展示政策，但不应采用不同的正确性标准。未定义键和弃用诊断在生产环境同样值得记录；把它们从掩码中删除只会让缺陷更难发现。通常的差别是开发环境可以把细节展示给开发者，生产环境只记录细节并向用户返回通用响应。

自定义 错误处理器（error handler） 适合把诊断接入结构化日志，或在一段受控代码中把警告转换为 ErrorException。它不是修复损坏状态的通用恢复层，也不应替代边界校验。能够在操作前检测失败时，显式检查返回值或输入通常比等待警告更清楚。

工作原理

两条失败通道

诊断通道携带级别、消息、文件和行号。引擎或 trigger_error() 产生诊断后，PHP 先判断是否存在能处理该级别的用户处理器。处理器若返回 true，默认处理器不会再处理这条诊断；返回 false，控制权会交还给默认处理器。

Throwable 通道携带对象、类型和堆栈跟踪。匹配的 catch 先处理对象；没有匹配项时，对象沿调用栈传播，最后可能交给全局异常处理器。set_error_handler() 与 set_exception_handler() 因此解决不同问题，不能通过把掩码设成 E_ALL 合并成一个机制。

这个流程描述的是控制权，不表示每条路径都能恢复。错误处理器可以改变警告的后续行为，异常处理器可以生成最终响应，关闭函数可以补记信息；它们都无法把已经破坏的不变量恢复成可信状态。

报告掩码与输出目的地

error_reporting(E_ALL) 在当前请求中选择全部已定义的错误级别。生产环境通常仍应使用 E_ALL，再用 display_errors=Off 防止响应泄露路径、查询或堆栈。log_errors=On 则把默认处理器选中的诊断送往配置的日志目标。

display_startup_errors 涉及 PHP 启动阶段，不能依赖已经开始执行的脚本来可靠修正。部署配置应放在 php.ini、PHP-FPM 池或运行环境管理的配置中。请求内调用 ini_set() 适合小型演示和受控 CLI 工具，不应成为生产配置的唯一来源。

掩码使用位运算。E_ALL & ~E_DEPRECATED 会删除弃用诊断，但这通常不是理想的长期政策；依赖升级正需要这些信号。若日志量过大，应在日志传输或告警层采样和聚合，而不是让运行时看不见一整类缺陷。

注册处理器

set_error_handler($callback, $levels) 安装一个进程内的当前处理器，并返回先前的处理器。第二个参数限制回调接收的级别；省略时默认为 E_ALL。PHP 的 Web 工作进程可能服务多个请求，测试进程也会运行多个用例，因此这种注册属于需要明确所有权的可变全局状态。

回调接收严重级别、消息、文件和行号。它应先判断当前 error_reporting() 是否包含该级别，再执行转换或记录。返回 false 会继续使用 PHP 默认处理器；返回 true 表示自定义政策已经完全处理，默认展示和日志都不会再发生。

只记录后返回 true 很容易造成静默丢失。如果自定义日志写入失败，默认通道也已经被关闭。处理器应有明确的失败政策，并且绝不能在处理日志错误时递归触发同一处理器。

转换为 ErrorException

内建 ErrorException 把诊断的消息、级别、文件和行号装进可抛出对象。转换后，调用方可以在一个明确边界使用 catch 和 finally，而不必依赖函数返回 false 的同时检查全局日志。这对一些会通过警告报告失败的旧式 API 很有用。

转换会改变控制流。原本会返回 false 并继续的函数，现在可能在警告发生处抛出，因此不能在整个应用里不加选择地启用。应该把转换限制在拥有明确契约的入口层或测试范围，并确保依赖库预期的诊断没有被意外改成异常。

不要自行声明名为 ErrorException 的全局类。PHP 已提供该类，重复声明会造成致命错误。创建实例时应把原始严重级别传给构造函数的 severity 参数，调用方才能用 getSeverity() 保留诊断含义。

关闭阶段

register_shutdown_function() 注册的函数会在正常结束和许多终止路径上运行。关闭函数可通过 error_get_last() 查看最近一条错误记录，但该记录不保证是致命错误，也可能来自早先已经处理的诊断。代码必须先检查记录是否存在，再严格筛选允许的级别。

关闭阶段只适合最后记录、释放少量进程资源或提交已经准备好的遥测。内存耗尽、输出已经发送或运行时状态不完整时，复杂的模板、依赖注入容器和网络客户端都可能不可用。关闭处理器不是重新执行请求或继续业务事务的地方。

示例

下面三个示例依次展示诊断所有权、受控的异常转换，以及终止时的最后检查。输出均由本地 PHP 8.3.33 CLI 实际生成；最后一个程序按设计以非零状态结束。

接管选定的用户诊断

处理器只接收用户警告和用户通知，并为每个级别生成稳定名称。返回 true 表示默认处理器不应再次展示或记录同一条消息。

$levels 数组不是错误分类的完整副本，只包含本例注册的两个级别。若回调可能收到其他级别，应为未知值提供明确表示，而不是直接读取一个不存在的数组键。

restore_error_handler() 恢复先前处理器，而不是假定默认处理器一直在下面。框架、测试运行器或调用方可能已经安装自己的处理器，库代码必须把它原样交还。

在窄边界转换警告

直接读取缺失数组键会产生 E_WARNING。临时处理器把它转换为内建 ErrorException，调用方处理后仍能继续；finally 保证无论成功还是失败都会恢复处理器。

<?php

declare(strict_types=1);

function stockFor(array $stockBySku, string $sku): int
{
    return $stockBySku[$sku];
}

set_error_handler(
    static function (
        int $severity,
        string $message,
        string $file,
        int $line,
    ): bool {
        if (!(error_reporting() & $severity)) {
            return false;
        }

        throw new ErrorException($message, 0, $severity, $file, $line);
    },
);

try {
    stockFor(['BK-101' => 4], 'BK-404');
} catch (ErrorException $error) {
    printf("caught %s severity=%d\n", $error::class, $error->getSeverity());
} finally {
    restore_error_handler();
}

echo "recovered at boundary\n";

caught ErrorException severity=2
recovered at boundary

这里的严重级别 2 就是当前运行时中的 E_WARNING。示例输出数值是为了证明元数据被保留；生产日志通常还应保存符号名称、稳定事件码和安全的业务上下文。

这个技巧不应掩盖真正的修复。若缺失 SKU 是合法情况，array_key_exists() 或返回可空结果更能表达契约；若它违反内部不变量，转换成异常才适合把失败交给上层边界。

在终止时筛选最后错误

未捕获的 Error 最终会终止程序。关闭函数查看最后记录，只在它属于明确的致命级别集合时输出一条固定消息。

<?php

declare(strict_types=1);

ini_set('display_errors', '0');
ini_set('log_errors', '0');

register_shutdown_function(static function (): void {
    $last = error_get_last();
    $terminalLevels = [
        E_ERROR,
        E_PARSE,
        E_CORE_ERROR,
        E_COMPILE_ERROR,
    ];

    if ($last === null || !in_array($last['type'], $terminalLevels, true)) {
        return;
    }

    printf("shutdown observed type=%d\n", $last['type']);
});

echo "before uncaught Error\n";
undefined_entry_point();

before uncaught Error
shutdown observed type=1

类型 1 对应 E_ERROR，但原始失败是一个未捕获的 Error 对象。若在调用附近捕获该对象，或者全局异常处理器正常处理它，就不会需要关闭函数生成替代响应。

示例关闭默认展示和日志，只为得到可复现输出。真实生产配置必须保留安全日志；关闭函数还应避免输出已经开始的响应，因为那可能产生损坏的 JSON、HTML 或协议帧。

陷阱

把 E_ALL 当成万能捕获

修复方法： 分开设计两条路径。可恢复诊断使用错误处理器，Throwable 使用局部 catch 或应用入口的异常处理器；关闭函数只补充最后观测。

记录后总是返回 true

修复方法： 明确谁拥有展示与日志。只有确认自定义路径已经完成政策时才返回 true；希望默认日志继续时返回 false，并测试日志目标故障。

忽略 @ 的当前掩码

修复方法： 在转换前检查 error_reporting() & $severity。同时审查 @ 是否真的有必要；能够先检查条件或显式处理返回值时，应删除抑制。

把处理器留给后续代码

修复方法： 用 try/finally 包围临时注册，并在 finally 中调用 restore_error_handler()。测试应在失败路径后再触发一条诊断，确认原处理器已经恢复。

在生产响应中展示细节

修复方法： 生产环境关闭 display_errors，向客户端返回稳定的通用错误与关联 ID，在受控日志中记录经过筛选的上下文。密码、令牌、Cookie 和授权头既不能写入响应，也不能原样写入日志。

延伸阅读

• PHP 手册：错误基础
• PHP 手册：错误配置
• PHP 手册：set_error_handler()
• PHP 手册：ErrorException
• PHP 手册：register_shutdown_function()