Whoops 2.x 演进全记录:从 PHP 错误处理器到现代调试生态的版本迭代指南

原创2026-09-21 14:52:221,387 阅读
文章标签:开发工具后端

Whoops 2.x 演进全记录:从 PHP 错误处理器到现代调试生态的版本迭代指南

Whoops 是一个面向 PHP 的错误处理框架,核心能力是"堆栈式错误处理"——将多个 Handler(处理器)按顺序组合,统一接管异常、错误与致命错误,并为 Web 项目提供开箱即用的漂亮错误页。本文以仓库根目录的 CHANGELOG.md 为主干,完整梳理 v2.0.0 至 v2.17.0 的全部版本变更,并结合 src/Whoops/Run.php、src/Whoops/Handler/PrettyPageHandler.php 等源码实现与测试用例,逐一解读每项特性背后的设计意图与实战用法。读完本文,你将掌握 Whoops 版本演进脉络、各核心 API 的配置方式,以及如何针对特定 PHP 版本与框架场景做出正确的升级与集成决策。

版本说明:本文所有版本号、变更内容均以仓库当前 CHANGELOG.md 记录为准;文中涉及的 API 行为对照 src/Whoops/Run.php 等源码验证。Whoops 通过 Composer 安装(见 composer.json),运行 phpunit --testdox tests 可执行测试套件。

一、2.x 时代整体脉络:三大演进方向

把 CHANGELOG 全部条目摊开,可以发现 Whoops 2.x 的迭代始终围绕三条主线:

  1. 错误展示层持续升级:从 v2.1.0 引入"高亮出错代码行",到 v2.14.0 切换到 Prism.js 语法高亮,再到 v2.15.x 修复高亮与标签页切换问题,错误页的渲染质量被反复打磨(对应资源文件位于 src/Whoops/Resources)。
  2. Handler 栈与 Run 引擎的 API 扩充:prependHandler / appendHandler、removeFirstHandler / removeLastHandler、addFrameFilter 等能力陆续加入,让堆栈式处理更灵活可控。
  3. PHP 版本兼容与生态适配:v2.16.0 起要求 PHP >= 7.1 并支持 PHP 8.4,v2.9.0 支持 PHP 8,v2.8.0、v2.14.3 等节点都有对应的运行时支持声明(对照 composer.json 的 "php": "^7.1 || ^8.0")。

以下按版本号逐一展开。

二、v2.0.0 与 v2.1.0:架构定型期

v2.0.0:向后不兼容的架构收紧

v2.0.0 是 2.x 的第一个大版本,包含两项破坏性变更:

  • Run 类变为 final:如果此前通过继承 Whoops\Run 来扩展行为,现在必须改为自定义一个 SystemFacade 注入 Run 构造函数。这一设计在源码中清晰可见——src/Whoops/Run.php 声明 final class Run implements RunInterface,构造函数签名 public function __construct(?SystemFacade $system = null)(src/Whoops/Run.php)接受可选的 SystemFacade 实例。
  • 放弃 PHP < 5.5 支持。

从源码结构看,引入 SystemFacade 是为了把 set_error_handler、set_exception_handler、register_shutdown_function、ob_start、http_response_code、exit 等"系统级调用"全部封装起来(见 src/Whoops/Util/SystemFacade.php),使 Run 的可测试性与可定制性不再依赖继承。想要覆盖 Whoops 的系统行为,只需继承 SystemFacade 并覆写对应方法,例如:

class MySystemFacade extends \Whoops\Util\SystemFacade
{
    public function stopExecution($exitStatus)
    {
        // 自定义退出逻辑,例如记录日志后退出
        error_log("exiting with status: {$exitStatus}");
        parent::stopExecution($exitStatus);
    }
}

$run = new \Whoops\Run(new MySystemFacade);

v2.1.0:错误页细节体验初建

v2.1.0 一口气加入四项能力:

  • SystemFacade 公开化:允许客户端覆写 Whoops 行为(即上文 v2.0.0 引入机制的正式落地);
  • PrettyPageHandler 显示帧参数(frame arguments);
  • 高亮出错代码行;
  • 添加 Google 与 Stack Overflow 搜索图标。

其中"显示帧参数"对应 src/Whoops/Exception/Formatter.php 中 formatExceptionAsDataArray 输出的 trace 结构——每个栈帧包含 file、line、function、class、args 五个字段,为错误页与 JSON API 提供了完整的帧数据。

三、v2.2.0 – v2.6.0:PHP 兼容与 Handler 栈控制

v2.2.0:支持 PHP 7.2

版本兼容性的持续跟进,对应 composer.json 中 "php": "^7.1 || ^8.0" 的声明。

v2.3.0:展示前序异常消息

// 当一个异常由另一个异常触发时(链式异常)
try {
    throw new RuntimeException('inner');
} catch (RuntimeException $inner) {
    throw new LogicException('outer', 0, $inner);
}

v2.3.0 之后,PrettyPageHandler 的错误页会同时展示 outer 与 inner 的消息。这在 PrettyPageHandler.php 中体现为 previousMessages 与 previousCodes 两个模板变量,数据来源是 Inspector 的 getPreviousExceptionMessages() 与 getPreviousExceptionCodes()。

v2.3.1 / v2.4.1:健壮性修复

  • v2.3.1:防止"被捕获异常的帧与真实文件无关"时 Whoops 自身抛异常;
  • v2.4.1:更努力地关闭所有输出缓冲区——对应 handleException 中 while ($this->system->getOutputBufferLevel() > 0) 的循环清理逻辑(src/Whoops/Run.php)。

v2.4.0:Handler 栈前后插入

v2.4.0 引入 prependHandler 与 appendHandler,打破原来只能 pushHandler 尾部追加的限制:

$run = new \Whoops\Run;

// appendHandler:显式要求该 handler 作为"最后一个被注册"(执行时最先被调用)
$run->appendHandler(function ($exception, $inspector, $run) {
    // 最先执行的逻辑
});

// pushHandler:注册为最后一个(默认,执行时最后被调用)
$run->pushHandler(new \Whoops\Handler\PrettyPageHandler);

源码中 src/Whoops/Run.php 给出了三者差异:appendHandler 使用 array_unshift 把 handler 压入栈顶(先执行),prependHandler 只是 pushHandler 的别名(array_push,后执行),而 pushHandler 本身被注释建议优先使用前两个方法以保证语义清晰。

v2.5.0:自动配置 xdebug

若检测到 xdebug 的 file_link_format 配置,PrettyPageHandler 构造器会自动注册并默认选用 xdebug 编辑器(见 PrettyPageHandler.php),这让"点击错误页上的文件链接直接跳到 IDE"几乎零配置可用。

v2.6.0:修复 v2.4.0 的 handler 顺序回归

v2.4.0 曾导致 pushHandler 改变 handler 顺序,v2.6.0 修复此问题。Handler 栈的整体语义可概括为:handleException 按"注册顺序的逆序"遍历 handler(src/Whoops/Run.php),首个返回 Handler::QUIT 或 Handler::LAST_HANDLER 的 handler 会终止后续执行(src/Whoops/Run.php)。

四、v2.7.x:PrettyPageHandler 可定制化

v2.7.x 是错误页定制能力的小高峰:

v2.7.0:移除首尾 Handler

$run->removeFirstHandler(); // 等价于 array_pop:移除"最后注册"的那个 handler
$run->removeLastHandler();  // 等价于 array_shift:移除"最先注册"的那个 handler

注意命名与直觉相反——"First" 指栈中第一个(最先注册),"Last" 指栈中最后一个(最后注册)。对应源码 src/Whoops/Run.php,并有配套测试 tests/Whoops/RunTest.php。

v2.7.1:修复匿名类场景的 PHP 警告

v2.7.2:自定义 JS 与继承访问

  • PrettyPageHandler 接受自定义 JS 文件(addCustomJs,PrettyPageHandler.php);
  • PrettyPageHandler 与 templateHelper 可通过继承访问——对应源码中 protected $editor、protected $editors、protected $templateHelper 等 protected 成员。

v2.7.3:隐藏超全局键的命名清晰化

原 blacklist 方法增加更清晰的别名 hideSuperglobalKey(PrettyPageHandler.php):

$handler = new \Whoops\Handler\PrettyPageHandler;
$handler->hideSuperglobalKey('_SERVER', 'PHP_AUTH_PW'); // 掩盖敏感值
$handler->hideSuperglobalKey('_POST',   'password');

被掩盖的值在错误页中替换为等长的 * 字符串(非字符串值固定为 3 个 *),实现在 masked() 方法中(PrettyPageHandler.php)。构造器默认已隐藏 _SERVER['PHP_AUTH_PW']。

五、v2.8.0 – v2.12.1:PHP 8 时代与输出控制

v2.8.0:支持 PHP 8

v2.9.0:JsonResponseHandler 包含异常 code

JsonResponseHandler 输出的 JSON 数据由此开始包含 code 字段。对照 Formatter.php,formatExceptionAsDataArray 返回的数组结构为:

{
  "type": "RuntimeException",
  "message": "Something broke",
  "code": 13,
  "file": "/path/to/file.php",
  "line": 42
}

v2.9.1:修复 PHP 8 下 xdebug 函数崩溃

v2.9.2:修复复制按钮样式

v2.10.0:Handler 类的链式调用

Handler 类的 setter 方法改为返回 $this(多数方法签名标注 @return static),可以写成:

$handler = (new \Whoops\Handler\PrettyPageHandler)
    ->setPageTitle('出错了')
    ->setEditor('vscode')
    ->addDataTable('请求信息', ['method' => $_SERVER['REQUEST_METHOD'] ?? 'GET']);

v2.11.0:自定义退出码

Run 新增 sendExitCode($code):CLI 环境下默认退出码为 1,可改为 0–254 之间的任意整数,超出范围抛 InvalidArgumentException(src/Whoops/Run.php)。退出码在 handleException 末尾通过 SystemFacade::stopExecution 生效(src/Whoops/Run.php)。

v2.12.0:按需隐藏超全局中的非字符串值

v2.12.1:避免"从错误页重定向离开"

修复了错误处理过程中被 location 头干扰的问题——SystemFacade::setHttpResponseCode 在 headers_sent() 为假时会先 header_remove('location')(src/Whoops/Util/SystemFacade.php),确保错误页的 HTTP 状态码不被误覆盖。

六、v2.13.0 – v2.15.x:编辑器支持与错误页渲染打磨

v2.13.0:新增 Netbeans 编辑器

PrettyPageHandler 的预置编辑器表新增 netbeans => "netbeans://open/?f=%file:%line"(PrettyPageHandler.php)。

v2.14.0:切换到 Prism.js 语法高亮

v2.14.0 将语法高亮从 prettify 切换到 Prism.js,原因是避免 prettify 的许可问题,并使用维护更活跃的现代项目。仓库 src/Whoops/Resources/js/prism.js 与 src/Whoops/Resources/css/prism.css 即此变更的落地资源。

v2.14.1:修复高亮滚动过远 + 改进 xdebug linkformat 检测

v2.14.3:支持 PHP 8.1

v2.14.4:修复 PHP 5.5 支持 + 允许 psr/log 2/3

composer.json 中 "psr/log": "^1.0.1 || ^2.0 || ^3.0" 即此版本开放的上限(composer.json)。

v2.14.5:允许对超全局使用 ArrayAccess

masked() 方法支持 $_GET 等超全局以 ArrayAccess 形式访问(PrettyPageHandler.php)。

v2.14.6:Prism.js 升级至 1.29.0 修复安全问题

v2.15.0:新增 addFrameFilter

Run::addFrameFilter 允许注册帧过滤器回调,对所有 handler 产出的栈帧统一做过滤/变换(src/Whoops/Run.php):

$run->addFrameFilter(function (\Whoops\Exception\Frame $frame) {
    // 隐藏 vendor 目录帧
    if (strpos($frame->getFile(), '/vendor/') !== false) {
        return false;
    }
    return $frame;
});

帧过滤器会传入 Inspector::getFrames($frameFilters),并同时作用于 PrettyPageHandler 与 JsonResponseHandler 的输出(见 Formatter.php 与 JsonResponseHandler.php)。

v2.15.1:修复 getFrameFilters 在 null 上调用

v2.15.2:修复缺失的代码高亮导致标签页切换问题

v2.15.3:提升语法高亮性能

v2.15.4:改善注释中的链接颜色

七、v2.16.0 与 v2.17.0:最新能力

v2.16.0:支持 PHP 8.4,放弃 PHP 7.1 以下

自 v2.16.0 起,Whoops 要求 PHP >= 7.1,并支持到 PHP 8.4。这是当前 composer.json 中 "php": "^7.1 || ^8.0" 声明所对应的约束边界。

v2.17.0:支持 Cursor IDE

最新版本为编辑器表新增 cursor => "cursor://file/%file:%line"(PrettyPageHandler.php)。

至此,PrettyPageHandler.php 预置的编辑器标识符全集为:sublime、textmate、emacs、macvim、phpstorm、idea、vscode、atom、espresso、xdebug、netbeans、cursor,可通过 setEditor 直接选用:

$handler = new \Whoops\Handler\PrettyPageHandler;
$handler->setEditor('cursor');   // v2.17.0+
$handler->setEditor('vscode');   // 或 VS Code
$handler->setEditor('phpstorm'); // 或 PhpStorm

八、配套使用指南与示例资源

在编辑器中打开文件

setEditor 配合 %file / %line 占位符可以完全自定义编辑器协议。仓库 docs/Open Files In An Editor.md 提供了完整说明与示例:

use Whoops\Handler\PrettyPageHandler;

$handler = new PrettyPageHandler;
$handler->setEditor('sublime');

也可注册自定义解析器,甚至支持远程文件到本地路径的映射(适配 IntelliJ 平台需返回带 ajax => true 的数组,因为该平台要求 Ajax 请求否则浏览器会退出页面):

$handler->setEditor(function ($file, $line) {
    // 将远程开发服务器上的文件路径映射到本地
    $translations = ['^' . __DIR__ => '~/Development/PhpStormOpener'];
    foreach ($translations as $from => $to) {
        $file = preg_replace('#' . $from . '#', $to, $file, 1);
    }
    return [
        'url'  => "http://localhost:63342/api/file/?file=$file&line=$line",
        'ajax' => true
    ];
});

快速上手示例

仓库 examples/example.php 演示了 Handler 栈组合的完整玩法:

$run = new Run();
$handler = new PrettyPageHandler();

// 1. 自定义数据表(静态)
$handler->addDataTable('Ice-cream I like', [
    'Chocolate' => 'yes',
    'Coffee & chocolate' => 'a lot',
]);

// 2. 惰性数据表(回调)
$handler->addDataTableCallback('Details', function (\Whoops\Exception\Inspector $inspector) {
    return ['Exception class' => get_class($inspector->getException())];
});

// 3. 设置应用路径(错误页据此区分"应用帧"与"框架帧")
$handler->setApplicationPaths([__FILE__]);

$run->pushHandler($handler);

// 4. 再注册一个闭包 handler:给每个栈帧添加注释
$run->pushHandler(function ($exception, $inspector, $run) {
    $inspector->getFrames()->map(function ($frame) {
        if ($function = $frame->getFunction()) {
            $frame->addComment("This frame is within function '$function'", 'cpt-obvious');
        }
        return $frame;
    });
});

$run->register();

九、升级与选型决策速查

版本 关键变更 影响
v2.0.0 Run 变为 final,弃用继承 扩展请用自定义 SystemFacade
v2.4.0 新增 prependHandler / appendHandler 更精确的 Handler 执行顺序控制
v2.7.0 新增 removeFirstHandler / removeLastHandler 动态移除 Handler
v2.7.3 hideSuperglobalKey 命名清晰化 隐藏敏感超全局值
v2.9.0 JSON 输出包含 code API 消费方需适配新字段
v2.11.0 新增 sendExitCode CLI 退出码可定制
v2.14.0 切换 Prism.js 高亮 视觉与许可问题改善
v2.15.0 新增 addFrameFilter 全局栈帧过滤
v2.16.0 PHP 8.4 支持,弃用 < 7.1 升级 PHP 环境的硬约束
v2.17.0 Cursor IDE 支持 新增编辑器选项

版本兼容性结论(以当前仓库为准):Whoops 当前支持 PHP 7.1 – 8.4,依赖 psr/log ^1.0.1 || ^2.0 || ^3.0;测试框架使用 phpunit ^7.5.20 || ^8.5.8 || ^9.3.3(见 composer.json)。升级到 v2.16.0+ 前请确认项目 PHP 版本不低于 7.1。

快速验证:克隆仓库后执行 composer install,运行 phpunit --testdox tests(或 composer test)即可运行完整测试套件,验证当前 PHP 环境下各版本特性的行为一致性。

登录后查看全文
whoops