README

Summary

The ThrowableHandler package provides handling for throwable with rich formatting support for console, HTML and plain text documents. Its purpose is to ease the understanding of Exceptions on production systems by providing a consistent and user-friendly output.

Read Throwable Handler for PHP at Rodolfo's blog for a comprehensive introduction to this package.

Installing

ThrowableHandler is available through Packagist and the repository source is at chevere/throwable-handle.

composer require chevere/throwable-handler

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

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($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

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

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 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

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)
);

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.

Documentation

Documentation is available at chevere.org.

License

Chevere is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

chevere / throwable-handler

Maintainers

Details