Guide · Open source
How to use Whoops: PHP error pages and handlers
Updated · written with AI from the project's own documentation and checked against our catalogue data
Whoops is an open-source error handler library for PHP. Out of the box it shows a detailed error page in the browser to help you debug a web project, and it can also return plain text, JSON or XML. This guide shows how to install it with Composer, register the main handler, and choose the output format that fits your project.
whoopsfilp/whoops · ★ 13.2k · MIT Install options & downloads Quick start
- 1Check prerequisites. Make sure PHP and Composer are installed in your environment.
- 2Install the package. Run composer require filp/whoops in your project folder.
- 3Create a Run instance. Create a new \Whoops\Run object in your bootstrap code.
- 4Push a handler. Add PrettyPageHandler for browser error pages, or another handler that suits your output needs.
- 5Register Whoops. Call register() so Whoops handles errors and exceptions from that point on.
- 6Test with an error. Trigger an exception in a local page and check that the error output appears as expected.
What Whoops does and who it is for
Whoops is an error handler framework for PHP. It catches errors and exceptions and reports them in a more useful way than the default output. Its main feature is a pretty error interface for debugging web projects, and at its core it is a stacked error handling system, so you can choose or combine how errors are shown.
It suits PHP developers debugging web applications locally, and teams using a framework that already bundles it. It is a PHP library only, so it does not apply to non-PHP projects.
- Stand-alone library, with no required dependencies according to the README
- Includes a pretty error page for web app projects
- Handlers for JSON, XML and SOAP responses
- Can open referenced files directly in your editor or IDE
Install Whoops with Composer
You need PHP and Composer. Run the following command in your project folder to add Whoops as a dependency.
If you use Laravel 4, Laravel 5.5+, Mezzio or ZubZet 1.2+, the README says you already have Whoops, so you may not need to install it yourself.
composer require filp/whoopsRegister the pretty error page
If your project is not on one of the frameworks above, create a Whoops\Run instance, push the PrettyPageHandler onto it, and register it. This makes Whoops take over error handling for the script.
The README also lists the examples/ folder in the repository as a place to see more options, and the API Documentation for details.
$whoops = new \Whoops\Run;
$whoops->pushHandler(new \Whoops\Handler\PrettyPageHandler);
$whoops->register();Choose a handler for JSON, XML or plain text output
Whoops ships several built-in handlers in the Whoops\Handler namespace. PrettyPageHandler shows the browser error page. PlainTextHandler outputs a plain text message for command-line applications. JsonResponseHandler and XmlResponseHandler return information about exceptions as a JSON or XML string, which can help with AJAX requests.
Handlers are stacked, so you can push more than one. Passing a closure or other callable to pushHandler wraps it automatically in a CallbackHandler.
- PrettyPageHandler: browser error page
- PlainTextHandler: plain text for CLI applications
- JsonResponseHandler: JSON for AJAX requests
- XmlResponseHandler: XML for AJAX requests
- CallbackHandler: wraps a closure or callable
Get the error output as HTML instead of printing it
If you want to process the generated HTML yourself, the README shows how to turn off quitting and direct output, then capture the return value of handleException.
$whoops = new \Whoops\Run;
$whoops->allowQuit(false);
$whoops->writeToOutput(false);
$whoops->pushHandler(new \Whoops\Handler\PrettyPageHandler);
$html = $whoops->handleException($e);Customise or extend Whoops
To override some system calls Whoops makes, extend Whoops\Util\SystemFacade, override the functions you want, and pass it as the argument to the Run constructor. The README also notes that pluggable handlers exist, such as a SOAP handler.
What people use it for
- Debugging a PHP web application locally with a detailed error page
- Returning JSON error details to an AJAX front end
- Returning XML error details from an API-style endpoint
- Printing readable error messages in a command-line PHP tool using PlainTextHandler
- Building custom error reporting by writing your own callable handler
Frequently asked questions
How do I install Whoops?
Install it with Composer by running composer require filp/whoops in your project folder. You need PHP and Composer. Then register the PrettyPageHandler in your code, as shown in the guide.
Is Whoops free to use?
Whoops is released under the MIT licence, according to the project page. The README does not state any other terms, so check the licence file in the repository for the full text.
What are the requirements for Whoops?
The stated prerequisites are PHP and Composer. The README says Whoops is a stand-alone library with no required dependencies, though it is specifically a PHP library.
Can Whoops return JSON errors for AJAX requests?
Yes. JsonResponseHandler captures exceptions and returns information on them as a JSON string, which the README says can be used with AJAX requests. XmlResponseHandler does the same for XML.
Should I use Whoops in production?
The README describes Whoops as a debugging-focused error page and does not address production use. Detailed error pages can expose sensitive internals, so think carefully before enabling them on a live site.
What are alternatives to Whoops?
Comparable projects include Symfony ErrorHandler, Laravel Ignition, and Whoops-compatible handlers from the whoops-php organization. The README does not compare them directly, so review each one for your framework.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Whoops suits PHP developers who want a clear error page while debugging a web project locally, or who need JSON or XML error output for AJAX-style requests. If you need production error monitoring, a full logging service, or a non-PHP tool, the README does not cover those, so look at a dedicated monitoring product or a framework's built-in handler instead.
Install options & downloads