Whoops 2.x 演进全记录:从 PHP 错误处理器到现代调试生态的版本迭代指南
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 的迭代始终围绕三条主线:
- 错误展示层持续升级:从 v2.1.0 引入"高亮出错代码行",到 v2.14.0 切换到 Prism.js 语法高亮,再到 v2.15.x 修复高亮与标签页切换问题,错误页的渲染质量被反复打磨(对应资源文件位于 src/Whoops/Resources)。
- Handler 栈与 Run 引擎的 API 扩充:
prependHandler/appendHandler、removeFirstHandler/removeLastHandler、addFrameFilter等能力陆续加入,让堆栈式处理更灵活可控。 - 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 环境下各版本特性的行为一致性。