# ThrowableHandler
Namespace Chevere\ThrowableHandler
The ThrowableHandler package provides handling for throwable (opens new window) with rich formatting support for console, HTML and plain text documents. Its purpose is to ease the understanding of Exceptions (opens new window) on production systems.
💡 ThrowableHandler introduction
Read Throwable Handler for PHP (opens new window) at Rodolfo's blog for a compressive introduction to this package.
# Installing
ThrowableHandler is available through Packagist (opens new window) and the repository source is at chevere/throwable-handle (opens new window).
composer require chevere/throwable-handler
# Demo
- HTML (opens new window)
- HTML (silent) (opens new window)
- Plain text (opens new window)
- Console (asciinema) (opens new window)
# 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
Use the following helpers to forward errors as exceptions, which will be then handled by ThrowableHandler.
# 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
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
Use the following helpers to quick handle throwables by registering global handlers.
# Plain handler
Use ThrowableHandler::PLAIN
to set plain handler for all exceptions.
use Chevere\ThrowableHandler\ThrowableHandler;
set_exception_handler(ThrowableHandler::PLAIN);
# Console handler
Use ThrowableHandler::CONSOLE
to set console handler for all exceptions.
use Chevere\ThrowableHandler\ThrowableHandler;
set_exception_handler(ThrowableHandler::CONSOLE);
# HTML handler
Use ThrowableHandler::HTML
to set console handler for all exceptions.
use Chevere\ThrowableHandler\ThrowableHandler;
set_exception_handler(ThrowableHandler::HTML);
# Triggered handling
Use the following helpers to quick handle catches for throwables.
# handleAsPlain
Use function handleAsPlain
to handle throwable as plain text.
use function Chevere\ThrowableHandler\handleAsPlain;
try {
// ...
} catch(Throwable $e) {
handleAsPlain($e);
}
# handleAsConsole
Use function handleAsConsole
to handle throwable as console text.
use function Chevere\ThrowableHandler\handleAsConsole;
try {
// ...
} catch(Throwable $e) {
handleAsConsole($e);
}
# htmlHandler
Use function htmlHandler
to handle throwable as HTML.
use function Chevere\ThrowableHandler\htmlHandler;
try {
// ...
} catch(Throwable $e) {
htmlHandler($e);
}
# Manual handling
# Documents
Generate context documents with information about the throwable.
# Plain document
Use plainDocument
to create a plain text document.
use function Chevere\ThrowableHandler\plainDocument;
$document = plainDocument($throwable);
$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($throwable);
# Console document
Use consoleDocument
to create a console document.
use function Chevere\ThrowableHandler\consoleDocument;
$document = consoleDocument($throwable);
$console = $document->__toString();
Use Documents\ConsoleDocument
to create a console document by passing its handler.
use Chevere\ThrowableHandler\Documents\ConsoleDocument;
$handler = throwableHandler($throwable);
$document = new ConsoleDocument($throwable);
# 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($throwable);
# 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($throwable);
$consoleDoc = new ConsoleDocument($handler);
$plainDoc = new PlainDocument($handler);
$htmlDoc = new HtmlDocument($handler);
# 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($throwable);
$docLoud = new HtmlDocument($handler);
$docSilent = new HtmlDocument(
$handler->withIsDebug(false)
);
For the code above, $docLoud
contains debug information (throwable info, file, line, trace and server) while $docSilent
provides a generic message but referencing to the throwable handled id.