PHPackages                             chevere/throwable-handler - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. chevere/throwable-handler

ActiveLibrary[Utility & Helpers](/categories/utility)

chevere/throwable-handler
=========================

Throwable handler for multiple contexts

1.0.10(2mo ago)1131.9k—2.4%1[11 issues](https://github.com/chevere/throwable-handler/issues)7Apache-2.0PHPPHP ^8.1CI passing

Since Feb 8Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/chevere/throwable-handler)[ Packagist](https://packagist.org/packages/chevere/throwable-handler)[ Docs](https://chevere.org)[ RSS](/packages/chevere-throwable-handler/feed)WikiDiscussions 1.0 Synced 1mo ago

READMEChangelog (10)Dependencies (12)Versions (38)Used By (7)

ThrowableHandler
================

[](#throwablehandler)

[![Chevere](chevere.svg)](chevere.svg)

[![Build](https://camo.githubusercontent.com/55e7f19bcfe573ba1156fe62acfd93c67c964a163c3d1b95bc6ce29a7e0683de/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f636865766572652f7468726f7761626c652d68616e646c65722f746573742e796d6c3f6272616e63683d312e30267374796c653d666c61742d737175617265)](https://github.com/chevere/throwable-handler/actions)[![Code size](https://camo.githubusercontent.com/912bf8e93a3973ca17127688b8a90d6fa6de660d5c07c4672387006e0d32b2e3/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c616e6775616765732f636f64652d73697a652f636865766572652f7468726f7761626c652d68616e646c65723f7374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/912bf8e93a3973ca17127688b8a90d6fa6de660d5c07c4672387006e0d32b2e3/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c616e6775616765732f636f64652d73697a652f636865766572652f7468726f7761626c652d68616e646c65723f7374796c653d666c61742d737175617265)[![Apache-2.0](https://camo.githubusercontent.com/8bc21096c5d0a240dceae1e4f706536f34eae29aaa9e3926b7c0dd4dbb94eaaa/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f636865766572652f7468726f7761626c652d68616e646c65723f7374796c653d666c61742d737175617265)](LICENSE)[![PHPStan](https://camo.githubusercontent.com/6016298b28550819030c76e9327f62501596a31fd76406695bae2f3d2a1f26a4/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6c6576656c253230392d626c756576696f6c65743f7374796c653d666c61742d737175617265)](https://phpstan.org/)[![Mutation testing badge](https://camo.githubusercontent.com/d20f62389ac242ef41fdddb96d068c35509f02d069612a249871812471b013b5/68747470733a2f2f696d672e736869656c64732e696f2f656e64706f696e743f7374796c653d666c61742d7371756172652675726c3d687474707325334125324625324662616467652d6170692e737472796b65722d6d757461746f722e696f2532466769746875622e636f6d253246636865766572652532467468726f7761626c652d68616e646c6572253246312e30)](https://dashboard.stryker-mutator.io/reports/github.com/chevere/throwable-handler/1.0)

[![Quality Gate Status](https://camo.githubusercontent.com/f5f30bcfbb2a3e9502694b25f106036e4e5d29c8165fc91b37c485079c709711/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d636865766572655f7468726f7761626c652d68616e646c6572266d65747269633d616c6572745f737461747573)](https://sonarcloud.io/dashboard?id=chevere_throwable-handler)[![Maintainability Rating](https://camo.githubusercontent.com/be5b5cb44fa0db94c78ce7d9193788c17dd01d7441f53e12ddf69c14ddf92141/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d636865766572655f7468726f7761626c652d68616e646c6572266d65747269633d7371616c655f726174696e67)](https://sonarcloud.io/dashboard?id=chevere_throwable-handler)[![Reliability Rating](https://camo.githubusercontent.com/927754801088dc9fab45497994c947b2713e9a6dc21eb366f926f7a7ef8f0162/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d636865766572655f7468726f7761626c652d68616e646c6572266d65747269633d72656c696162696c6974795f726174696e67)](https://sonarcloud.io/dashboard?id=chevere_throwable-handler)[![Security Rating](https://camo.githubusercontent.com/7403ac00dedae2e88119e512115bbce0700d7b7f8c8779d026dbd3401d21af38/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d636865766572655f7468726f7761626c652d68616e646c6572266d65747269633d73656375726974795f726174696e67)](https://sonarcloud.io/dashboard?id=chevere_throwable-handler)[![Coverage](https://camo.githubusercontent.com/4a73e5d0d127bf3ce708895d53a4a85f18aeabe00932bf5e4edb9a89ece56426/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d636865766572655f7468726f7761626c652d68616e646c6572266d65747269633d636f766572616765)](https://sonarcloud.io/dashboard?id=chevere_throwable-handler)[![Technical Debt](https://camo.githubusercontent.com/9c97fd78e66ab92bdf22c8efb9e40f0b23e794a61c4e9c3a877cac316d2a000a/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d636865766572655f7468726f7761626c652d68616e646c6572266d65747269633d7371616c655f696e646578)](https://sonarcloud.io/dashboard?id=chevere_throwable-handler)[![CodeFactor](https://camo.githubusercontent.com/b3ff729b29230d83016c91580c315d81c5bcb52f250e4ab8b8cc18462651b500/68747470733a2f2f7777772e636f6465666163746f722e696f2f7265706f7369746f72792f6769746875622f636865766572652f7468726f7761626c652d68616e646c65722f6261646765)](https://www.codefactor.io/repository/github/chevere/throwable-handler)

[![ThrowableHandler](.github/banner/throwable-handler-logo.svg)](.github/banner/throwable-handler-logo.svg)

Summary
-------

[](#summary)

The ThrowableHandler package provides handling for [throwable](https://www.php.net/throwable) with rich formatting support for console, HTML and plain text documents. Its purpose is to ease the understanding of [Exceptions](https://www.php.net/manual/en/language.exceptions.php) on production systems by providing a consistent and user-friendly output.

Read [Throwable Handler for PHP](https://rodolfoberrios.com/2022/05/03/throwable-handler/) at Rodolfo's blog for a comprehensive introduction to this package.

Installing
----------

[](#installing)

ThrowableHandler is available through [Packagist](https://packagist.org/packages/chevere/throwable-handler) and the repository source is at [chevere/throwable-handle](https://github.com/chevere/throwable-handler).

```
composer require chevere/throwable-handler
```

Quick start
-----------

[](#quick-start)

For quick catch-all use, first register ThrowableHandler to handle all errors.

```
use Chevere\ThrowableHandler\ThrowableHandler;

set_error_handler(ThrowableHandler::ERROR_AS_EXCEPTION);
register_shutdown_function(ThrowableHandler::SHUTDOWN_ERROR_AS_EXCEPTION);
```

Then register your exception handler, you can choose:

- `ThrowableHandler::PLAIN`
- `ThrowableHandler::CONSOLE`
- `ThrowableHandler::HTML`

```
use Chevere\ThrowableHandler\ThrowableHandler;

set_exception_handler(ThrowableHandler::PLAIN);
```

Keep reading the documentation for more advanced usage and configuration options.

Demo
----

[](#demo)

[![HTML demo](demo/demo.svg)](demo/demo.svg)

- [HTML](https://chevere.github.io/throwable-handler/demo/output/html.html)
- [HTML (silent)](https://chevere.github.io/throwable-handler/demo/output/html-silent.html)
- [Plain text](https://chevere.github.io/throwable-handler/demo/output/plain.txt)
- [Console (asciinema)](https://asciinema.org/a/491732)

Features
--------

[](#features)

- Multiple use modes (auto, triggered, manual)
- Supports nested throwables (previous: `$e`)
- Console document
    - Colorful console output (where available)
- Plain document
    - Same as console (no-color)
    - Same as copy HTML text
- HTML document
    - Responsive design (narrow devices)
    - Silent mode for end-user

Errors as exceptions
--------------------

[](#errors-as-exceptions)

Use the following helpers to forward errors as exceptions, which will be then handled by ThrowableHandler.

### errorAsException

[](#errorasexception)

Use function `ThrowableHandler::ERROR_AS_EXCEPTION` to handle errors as exceptions. By doing this the system will throw exception instead of emitting errors.

```
use Chevere\ThrowableHandler\ThrowableHandler;

set_error_handler(ThrowableHandler::ERROR_AS_EXCEPTION);
```

### shutdownErrorAsException

[](#shutdownerrorasexception)

Use function `ThrowableHandler::SHUTDOWN_ERROR_AS_EXCEPTION` to register errors on shutdown. This will take care or register errors in shutdown by forwarding the error to the exception handler.

```
use Chevere\ThrowableHandler\ThrowableHandler;

register_shutdown_function(ThrowableHandler::SHUTDOWN_ERROR_AS_EXCEPTION);
```

Automatic handling
------------------

[](#automatic-handling)

Use the following helpers to quick handle throwables by registering global handlers.

### Plain handler

[](#plain-handler)

Use `ThrowableHandler::PLAIN` to set plain handler for all exceptions.

```
use Chevere\ThrowableHandler\ThrowableHandler;

set_exception_handler(ThrowableHandler::PLAIN);
```

### Console handler

[](#console-handler)

Use `ThrowableHandler::CONSOLE` to set console handler for all exceptions.

```
use Chevere\ThrowableHandler\ThrowableHandler;

set_exception_handler(ThrowableHandler::CONSOLE);
```

### HTML handler

[](#html-handler)

Use `ThrowableHandler::HTML` to set console handler for all exceptions.

```
use Chevere\ThrowableHandler\ThrowableHandler;

set_exception_handler(ThrowableHandler::HTML);
```

Triggered handling
------------------

[](#triggered-handling)

Use the following helpers to quick handle catches for throwables.

### handleAsPlain

[](#handleasplain)

Use function `handleAsPlain` to handle throwable as plain text.

```
use function Chevere\ThrowableHandler\handleAsPlain;

try {
    // ...
} catch(Throwable $e) {
    handleAsPlain($e);
}
```

### handleAsConsole

[](#handleasconsole)

Use function `handleAsConsole` to handle throwable as console text.

```
use function Chevere\ThrowableHandler\handleAsConsole;

try {
    // ...
} catch(Throwable $e) {
    handleAsConsole($e);
}
```

### htmlHandler

[](#htmlhandler)

Use function `htmlHandler` to handle throwable as HTML.

```
use function Chevere\ThrowableHandler\htmlHandler;

try {
    // ...
} catch(Throwable $e) {
    htmlHandler($e);
}
```

Manual handling
---------------

[](#manual-handling)

### Documents

[](#documents)

Generate context documents with information about the throwable.

#### Plain document

[](#plain-document)

Use `plainDocument` to create a plain text document.

```
use function Chevere\ThrowableHandler\plainDocument;

$document = plainDocument($e);
$plain = $document->__toString();
```

Use `Documents\PlainDocument` to create a plain text document by passing its handler.

```
use Chevere\ThrowableHandler\Documents\PlainDocument;

$handler = throwableHandler($throwable);
$document = new PlainDocument($handler);
```

#### Console document

[](#console-document)

Use `consoleDocument` to create a console document.

```
use function Chevere\ThrowableHandler\consoleDocument;

$document = consoleDocument($e);
$console = $document->__toString();
```

Use `Documents\ConsoleDocument` to create a console document by passing its handler.

```
use Chevere\ThrowableHandler\Documents\ConsoleDocument;

$handler = throwableHandler($e);
$document = new ConsoleDocument($handler);
```

#### HTML document

[](#html-document)

Use `htmlDocument` to create an HTML document.

```
use function Chevere\ThrowableHandler\htmlDocument;

$document = htmlDocument($throwable);
$html = $document->__toString();
```

Use `Documents\HtmlDocument` to create a console document by passing its handler.

```
use Chevere\ThrowableHandler\Documents\HtmlDocument;

$handler = throwableHandler($throwable);
$document = new HtmlDocument($handler);
```

### Multiple documents

[](#multiple-documents)

Multiple documents can be created **from the same** handler event:

```
use Chevere\ThrowableHandler\Documents\ConsoleDocument;
use Chevere\ThrowableHandler\Documents\HtmlDocument;
use Chevere\ThrowableHandler\Documents\PlainDocument;
use function Chevere\ThrowableHandler\throwableHandler;

$handler = throwableHandler($e);
$consoleDoc = new ConsoleDocument($handler);
$plainDoc = new PlainDocument($handler);
$htmlDoc = new HtmlDocument($handler);
```

### Debug

[](#debug)

The method `withIsDebug` in `ThrowableHandlerInterface` can be used to toggle debug information on generated documents.

```
use Chevere\ThrowableHandler\Documents\HtmlDocument;
use function Chevere\ThrowableHandler\throwableHandler;

$handler = throwableHandler($e);
$docLoud = new HtmlDocument($handler);
$docSilent = new HtmlDocument(
    $handler->withIsDebug(false)
);
```

Custom title and message
------------------------

[](#custom-title-and-message)

When handling silent HTML documents, the default title is `Something went wrong` and the default message is `Please try again later. If the problem persists don't hesitate to contact the system administrator.`. These defaults are used when debug information is disabled and no custom title or message is set.

The methods `withTitle` and `withMessage` in `ThrowableHandlerInterface` can be used to set custom title and message on generated documents.

```
use Chevere\ThrowableHandler\Documents\HtmlDocument;
use function Chevere\ThrowableHandler\throwableHandler;

$handler = throwableHandler($e)
    ->withIsDebug(false)
    ->withTitle('Algo se fue a la chucha')
    ->withMessage(