filp/whoops: A PHP Error Handler for Readable Debug Pages

The Problem whoops Addresses for PHP Developers

PHP's default error output is plain text, and for uncaught exceptions in a web app it typically produces a white screen or a minimal error string that tells a developer the exception type and file but not much else. whoops replaces that with a browser-rendered page showing the full stack trace, the code context around each frame, the request data, and other diagnostic information that makes it possible to understand an exception without reaching for a separate log file.

The library is primarily a development tool. Its pretty page is not designed to be shown to end users in production; it is designed to be shown to the developer who triggered the error. This distinction matters because the page can expose request headers, session data, and environment variables that should never reach a production client. The practical audience is any PHP developer who builds or maintains a web application and wants richer error context during local or staging development.

The README describes whoops as an error handler framework, not just an error page renderer. The distinction is important: the pretty page is one output handler among several, and the underlying system is a stack-based handler pipeline that can be configured to produce JSON, XML, or plain text output instead.

A Stack-Based Handler Architecture with No Required Dependencies

The README states that whoops is a stand-alone library with no required external dependencies. The architecture is a stack of handlers. When an error or exception occurs, whoops runs the handlers in last-in-first-out order, stopping when a handler returns a value indicating it has fully handled the event. Each handler has access to the exception, the full stack trace, and the individual trace frames with their variables and code context.

This design has a direct consequence for testing and debugging: it is possible to add, remove, or replace handlers programmatically. A development environment might push PrettyPageHandler first. A production environment might push a logging handler and a handler that returns a generic error response, with PrettyPageHandler absent entirely. The handler stack does not care what handlers are registered, which allows whoops to serve as the error infrastructure for both environments with different configurations.

The Whoops\Util\SystemFacade class provides a seam for overriding the system calls that whoops makes internally. The README notes that a developer can extend SystemFacade, override functions, and pass the custom instance to the Whoops\Run constructor. This is useful in testing contexts where side effects like die() calls need to be suppressed.

The CallbackHandler allows a plain PHP closure or callable to act as a handler. According to the README, whoops automatically wraps any closure or callable passed to Whoops\Run::pushHandler, so there is no need to instantiate CallbackHandler directly.

Installing whoops and Registering the Pretty Page Handler

The README instructs developers who use Laravel 4, Laravel 5.5+, Mezzio, or ZubZet 1.2+ that they already have whoops and do not need to install it. For other frameworks and standalone PHP applications, the install is a single Composer command:

composer require filp/whoops

With the package installed, two PHP statements register the pretty error handler:

$whoops = new \Whoops\Run;
$whoops->pushHandler(new \Whoops\Handler\PrettyPageHandler);
$whoops->register();

The first line creates the Run instance. The second pushes PrettyPageHandler onto the handler stack. The third registers whoops as PHP's exception and error handler. After this, any uncaught exception or PHP error will produce the pretty page in the browser instead of PHP's default output.

The README also lists community-provided integrations for Silex 1 and 2, Phalcon, Laravel 3 and 5, CakePHP 3 and 4, Zend 2 and 3, Yii 1, FuelPHP, Slim, Pimple, Laminas, and StackPHP and PSR-7 middlewares. None of these require changes to whoops itself: they wrap or extend the same Run and handler classes.

Collecting HTML Output Without Sending It to the Browser

The README documents a pattern for capturing the error HTML instead of writing it directly to the output buffer. This is useful when the application needs to process the error page itself, for example to log the HTML, wrap it in a custom template, or serve it through a response object rather than through a raw echo.

$whoops = new \Whoops\Run;
$whoops->allowQuit(false);
$whoops->writeToOutput(false);
$whoops->pushHandler(new \Whoops\Handler\PrettyPageHandler);
$html = $whoops->handleException($e);

Calling allowQuit(false) prevents whoops from calling die() after handling the exception. Calling writeToOutput(false) stops it from echoing the output directly. The return value of handleException() is then the generated HTML string. This pattern decouples the error rendering from the HTTP response layer, which is necessary in frameworks that manage output through a response abstraction rather than PHP's direct output mechanisms.

The Available Handlers and Their Use Cases

whoops ships five built-in handlers, each in the Whoops\Handler namespace.

PrettyPageHandler renders the interactive HTML debug page with the stack trace, code context, and request data. It is designed for browser-based web development workflows. PlainTextHandler outputs a plain text message, which the README describes as intended for CLI applications where the terminal cannot display HTML. JsonResponseHandler captures exceptions and returns information about them as a JSON string, which the README notes works well for AJAX requests and API endpoints. XmlResponseHandler does the same in XML format, also suitable for AJAX requests.

CallbackHandler wraps any PHP callable. As noted above, whoops wraps closures automatically when passed to pushHandler, making CallbackHandler unnecessary for most use cases.

A SOAP handler is available as a separate pluggable package rather than bundled with the library. The README also mentions the ability to open referenced files directly in an editor or IDE from the pretty page, documented in docs/Open Files In An Editor.md. This feature requires IDE-specific configuration but allows a developer to jump directly from a stack frame to the relevant file in their editor without navigating manually.

Where whoops Is the Wrong Tool

whoops is a development and debugging aid, not a production error management system. It has no built-in mechanism for aggregating errors across requests, sending alerts, or writing structured logs to a remote service. A production application needs a logging layer such as Monolog and an error tracking service such as Sentry in addition to, or instead of, whoops.

The pretty page handler deliberately exposes information that would be dangerous in a production environment. Stack traces reveal internal file paths. The request data panel can show session contents, cookies, and environment variables. Leaving PrettyPageHandler registered in production is a security risk, not just a cosmetic concern.

whoops also does not provide any mechanism for suppressing or filtering specific error types. All errors and exceptions that PHP would normally report go through the handler stack. For applications that intentionally generate certain non-fatal errors as part of their design, this can mean the pretty page appears for expected conditions, which is disruptive during development.

Symfony's ErrorHandler Component as an Alternative

The symfony/error-handler package is the closest alternative in the PHP ecosystem. It provides error handling with a debug-style web exception page and integrates deeply with the Symfony HTTP kernel's error handling lifecycle, including support for Symfony's profiler and debug toolbar.

The practical difference between the two tools is coupling. whoops is a standalone library that works in any PHP project regardless of framework. symfony/error-handler is built to slot into the Symfony container and benefits from that context, producing pages that include Symfony-specific diagnostic information like service definitions and event listener chains. Outside a Symfony application, symfony/error-handler requires more manual setup to get comparable output.

For a non-Symfony PHP application, whoops requires less configuration and has no framework prerequisites. For a Symfony application, symfony/error-handler is already present through the framework and integrates more naturally with the full request and response lifecycle. The README's statement that whoops is already bundled into Laravel 5.5+ and Mezzio reflects the same logic: each framework chose the error handler that fits its own architecture.

Editorial conclusion

PHP developers building web applications who want a readable error page during development should reach for whoops first: two lines of PHP register it and the pretty handler works out of the box. Developers building CLI tools can use PlainTextHandler, and API services can use JsonResponseHandler. whoops is not appropriate for production error display, and it does not replace a structured logging system. Verify that Laravel 5.5+ or Mezzio already bundles it before adding it as an explicit dependency.

Frequently asked questions

Official sources

1. filp/whoops on GitHub
2. Issues
3. License: MIT
4. Project website
5. README