# ThrowableHandler
The Chevere/ThrowableHandler
package provides handling for throwable (opens new window) with rich formatting support for console, HTML and plain text documents.
💡 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 GitHub (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)
# 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.