PHP 怎样统一记录 Error 和 Exception

PHP 7 及更高版本里，统一记录 Error 和 Exception 的入口应当是 Throwable。在业务边界使用 catch (Throwable $e)，再把类型、消息、错误码、文件、行号、堆栈和 previous 链写进同一套日志字段，就不会因为只捕获 Exception 而漏掉 TypeError、ValueError 等 Error。但 warning、notice 这类传统错误不会自动进入这个捕获块，仍要用错误处理器或运行环境配置单独处理。

官方资料：https://www.php.net/manual/en/class.throwable.php

先确认 Throwable 的捕获边界

Exception 适合表示业务或运行时异常，Error 则覆盖类型错误、参数错误、解析错误等引擎层问题。两者都实现 Throwable，但 Error 并不是 Exception 的子类，所以旧代码里的 catch (Exception $e) 可能漏掉错误对象。

这一区分很重要：catch (Throwable $e) 适合统一记录可抛出的对象，却不等于“捕获所有 PHP 错误”。普通 warning 或 notice 是否转成异常，取决于是否额外设置 set_error_handler()，不能把它们和 Throwable 日志混为一谈。

用一套字段记录两类对象

记录器不应该依赖具体类名，而应依赖 Throwable 公开的方法。推荐至少保留下面这些字段：

生产日志建议写成 JSON，便于按 type、请求标识和错误码检索；堆栈可以完整保存在服务端，但不要把文件路径、参数或消息原样回显给用户。

让局部捕获和全局兜底复用同一个记录器

下面的记录器只接收 Throwable，局部边界和全局处理器都调用它。示例中的 error_log() 代表接入现有日志系统的位置。

 get_class($error),
        'message' => $error->getMessage(),
        'code' => $error->getCode(),
        'file' => $error->getFile(),
        'line' => $error->getLine(),
        'trace' => $error->getTraceAsString(),
        'previous' => $error->getPrevious() ? get_class($error->getPrevious()) : null,
    ];

    // 真实项目可在这里替换为 JSON logger，并做敏感参数脱敏。
    error_log(json_encode($record, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES));
}

try {
    // 这里的业务调用可能抛出 Exception，也可能抛出 Error。
    runBusinessTask();
} catch (Throwable $error) {
    // 记录后按接口协议返回安全的错误响应。
    logThrowable($error);
    throw $error;
}

// 只兜底未在局部处理的 Throwable；处理器内部不要再次抛错。
set_exception_handler(function (Throwable $error): void {
    logThrowable($error);
});

如果局部捕获后重新抛出，外层全局处理器可能再次记录同一个对象，实际项目要约定“哪一层负责落盘”。常见做法是：业务层补充上下文并抛出，应用入口统一落盘；或者业务层已经完成记录时，用请求级标记避免重复写入。

上线前检查这四个边界

• 是否使用 Throwable，而不是只写 Exception？
• 日志是否保留真实子类名、文件和行号，并限制敏感参数进入堆栈？
• previous 是否只记录链路摘要，避免无限递归或重复展开？
• warning、notice 和进程级退出是否有单独的错误处理方案？

统一的是记录模型，不是把所有错误都当成可恢复异常。Error 往往意味着代码或输入契约需要修复，Exception 可能可以按业务策略重试；日志字段一致后，告警级别仍应由类型和场景决定。

相关问题

catch (Throwable) 会捕获 warning 吗？

不会。只有实现 Throwable 的对象会进入该捕获块；warning、notice 通常仍走 PHP 的错误报告机制。

为什么不能让自定义类直接 implements Throwable？

PHP 手册规定用户类不能直接实现 Throwable，应继承 Exception 或其子类。

全局异常处理器里还能继续抛异常吗？

不建议。处理器运行时没有可供它再次接管的同一处理链，应该先做不会抛错的记录和安全收尾。

应该记录 getTrace() 还是 getTraceAsString()？

结构化系统更适合保存数组形式的 getTrace()，纯文本日志可用 getTraceAsString()；两者都要注意参数脱敏。