Whoops
Whoops是面向 PHP 的开源错误处理框架，通过把多个处理器依次压入处理栈，将异常与运行时错误转换为可读的错误页面或结构化响应。它以 Composer 包的形式分发，被 Laravel 等框架及大量项目采用，主要价值在于缩短定位故障的时间。
定义
Whoops 是一个由 PHP 编写的错误处理框架，官方把它描述为“为 PHP 提供错误处理的框架”，本质上是一套可堆叠的错误处理系统。它并不替代 PHP 自身的语法或运行时，而是在异常或错误产生之后接管后续的展示与输出环节，把原本简陋的报错信息整理成便于阅读的界面[1]。
该库以 filp/whoops 之名发布在 PHP 的包仓库上，采用 MIT 许可协议，属于独立库，稳定版本不需要额外的运行时依赖[1]。它的核心对象是 Whoops\Run，开发者向其中注册一个或多个处理器，再由它统一注册为 PHP 的错误与异常处理入口。
框架生态中，Laravel 的若干版本以及 Mezzio 等框架已默认内置该库，另外还有面向 Silex、Phalcon、CakePHP、Yii、Slim、Laminas 等框架的第三方集成说明。
原理
Whoops 的运行围绕“栈”展开。Whoops\Run 维护一个处理器队列，开发者通过 pushHandler 依次压入处理器，异常发生时 Run 会逐个调用这些处理器的 handle 方法，直到某个处理器返回非空结果为止，从而形成责任链式的处理流程。
为了把异常信息整理成可供处理器使用的结构，库内部用 Whoops\Exception\Inspector 包装异常实例，提供异常名称、消息以及堆栈帧的迭代器；堆栈帧由 Frame 建模，可以读取文件名、行号、所属类、函数名、调用参数以及该文件对应行的源码片段[2]。FrameCollection 则提供 filter、map 等流式接口，用于筛选和改写帧集合，Frame 与 FrameCollection 都支持序列化[2]。
处理器层由 HandlerInterface 统一约定，处理器可以拿到 Run 实例、Inspector 实例以及待处理的异常[2]。库内置了若干实现：PrettyPageHandler 生成带样式的网页错误页，PlainTextHandler 面向命令行输出纯文本，JsonResponseHandler 与 XmlResponseHandler 把异常信息分别序列化为 JSON 与 XML，CallbackHandler 用于把闭包包装成处理器，此外还可以接入 SOAP 等可插拔处理器。
异常被转换成文本或 HTML 的过程可以自行控制：调用 allowQuit(false) 与 writeToOutput(false) 之后，handleException 会直接返回生成的 HTML 字符串，便于调用方进一步加工。库还允许继承 Whoops\Util\SystemFacade 覆盖内部使用的系统调用，以便在测试或特殊环境中替换行为。
发展历程
该库最初由 Filipe Dobreira 主导开发，后续由 Denis Sokolov 负责维护，Graham Campbell、Markus Staab 等人也长期参与贡献。包仓库的统计显示其首次发布距今约十余年，累计发布版本已达数十个，最新版本仍以 2.x 系列编号持续更新[3]。
2.x 版本在早期分支的基础上重写了内部结构，官方文档曾把 2 版作为预发布版本单独提供下载标签，并以 v1 分支保存稳定版文档[4]。随版本演进，该库对 PHP 版本的要求逐步提高，例如 2.1.6 时期的依赖声明为 PHP 5.5.9 以上或 7.0 以上，较新的版本则要求 PHP 7.1 或 8.0 以上[5]。
随着 PSR 标准的普及，社区出现了把它包装为 PSR-15 中间件的项目，用于在符合 PSR-7 与 PSR-15 的请求处理管线中捕获异常，该中间件要求 PHP 7.2 以上版本[6]。此外还有 WordPress、TYPO3、Magento、OXID 等平台的集成插件，以及若干以该库为基础的衍生分支[7]。
应用
最常见的用法是在项目入口处安装并注册处理器：先用 Composer 引入 filp/whoops，再实例化 Whoops\Run、压入 PrettyPageHandler 并调用 register，之后页面出现异常时就会显示详细的错误页。由于 Laravel 4、Laravel 5.5 及以上版本以及 Mezzio 已内置该库，这些框架的使用者无需额外安装即可获得相应能力。
在接口场景中，开发者常把 JsonResponseHandler 或 XmlResponseHandler 压入处理栈，使异常以对应格式返回给调用方，而不是输出 HTML 页面；命令行程序则多使用 PlainTextHandler 输出纯文本信息。PrettyPageHandler 还支持在错误页中把堆栈里的文件路径变成链接，点击后可在本地编辑器或 IDE 中直接打开对应文件，用于加速排查[1]。
集成方式并不限于手动注册。面向中间件的封装可以自动创建 Run 实例，并按请求的 Accept 头选择处理器；其 catchErrors 选项默认开启，会临时通过 set_error_handler 注册，使 PHP 错误与可抛出异常一并被捕获[6]。此外还有社区提供的编辑跳转扩展、调试条联动插件等辅助工具[7]。
局限
Whoops 定位在错误的呈现与分发，而不是错误的修复或拦截。它不会让出错的代码继续执行，也不改变 PHP 的错误语义，只是把已经发生的异常整理成更易读的形式。
其错误页会暴露文件路径、源码片段、调用参数等调试信息，因此适合开发阶段使用；材料中没有给出官方的生产环境配置指引，把它直接用于对外的线上环境存在信息暴露的风险。
作为独立的 PHP 库，它只覆盖 PHP 运行时的异常与错误，无法处理 Web 服务器、数据库连接中断、进程被杀等发生在 PHP 之外的问题；对跨进程或分布式调用链的追踪也不在其能力范围内[1]。
此外，部分能力依赖额外的可选组件或第三方集成，例如更友好的复杂值打印需要配合 symfony/var-dumper，SOAP 格式输出需要单独的 whoops/soap 包，框架集成也多由社区维护而非官方统一提供[7]。
参见
参考资料
- Packagist The PHP Package Repository [引用日期2026-10-29]
- API Documentation [引用日期2026-10-29]
- filp/whoops maintainers | packagist.org [引用日期2026-10-29]
- Packagist The PHP Package Repository [引用日期2026-10-29]
- "reference": "d2102955e48b9fd9ab24280a7ad12ed552752c4d", [引用日期2026-10-29]
- whoops [引用日期2026-10-29]
- whoops | Topic - Ecosyste.ms: Repos [引用日期2026-10-29]