kuria / error
Makes handling and debugging PHP errors suck less
Installs: 15 834
Dependents: 2
Suggesters: 0
Security: 0
Stars: 18
Watchers: 4
Forks: 1
Open Issues: 0
Requires
- php: >=7.1
- kuria/debug: ^4.0
- kuria/event: ^2.0
- kuria/php-highlighter: ^2.0 || ^3.0
Requires (Dev)
- ext-mbstring: *
- kuria/dev-meta: ^0.6
README
Makes handling and debugging PHP errors suck less.
Contents
Features
normal / debug mode
converts PHP errors (warnings, notices, etc.) into exceptions
respects the global
error_reporting
settinghandles uncaught exceptions and fatal errors (including parse and out-of-memory errors)
CLI error screen writes errors to stderr
web error screen renders errors for web browsers
event system that can be utilised to:
- implement logging
- suppress or force errors conditionally
- change or add content to the error screens
Requirements
- PHP 7.1+
Usage example
<?php use Kuria\Error\ErrorHandler; $debug = true; // true during development, false in production error_reporting(E_ALL); // configure the error reporting $errorHandler = new ErrorHandler(); $errorHandler->setDebug($debug); $errorHandler->register(); // trigger an error to see the error handler in action echo $invalidVariable;
Event system
Error handler events
Possible events emitted by the ErrorHandler
class are listed in ErrorHandlerEvents
:
ErrorHandlerEvents::ERROR
Emitted when a PHP errors occurs.
Arguments:
Kuria\Error\Exception\ErrorException $exception
- you may use the
suppress()
orforce()
method to suppress or force the exception, respectivelly, regardless of theerror_reporting
PHP setting
- you may use the
bool $debug
ErrorHandlerEvents::EXCEPTION
Emitted when an uncaught exception or a fatal error is being handled.
Arguments:
Throwable $exception
bool $debug
Warning
Avoid performing memory-intensive tasks in listeners of this event if
$exception
is an instance of Kuria\Error\Exception\OutOfMemoryException
.
ErrorHandlerEvents::FAILURE
Emitted when an uncaught exception or a fatal error could not be handled. This can happen
when an exception
event listener or the registered error screen throws an additional
exception. Throwing another exception or causing a fatal error at this point will just
kill the script.
Arguments:
Throwable $exception
bool $debug
Warning
Avoid performing memory-intensive tasks in listeners of this event if
$exception
is an instance of Kuria\Error\Exception\OutOfMemoryException
.
Web error screen events
Possible events emitted by the WebErrorScreen
class are listed in WebErrorScreenEvents
:
WebErrorScreenEvents::RENDER
Emitted when rendering in normal mode.
Receives an array with the following keys:
&title
: used in<title>
&heading
: used in<h1>
&text
: content of the default paragraph&extras
: custom HTML after the main sectionexception
: the exceptionoutput_buffer
: string|null
WebErrorScreenEvents::RENDER_DEBUG
Emitted when rendering in debug mode.
Receives an array with the following keys:
&title
: used in<title>
&extras
: custom HTML after the main sectionexception
: the exceptionoutput_buffer
: string|null
WebErrorScreenEvents::CSS
Emitted when CSS styles are being output.
Receives a single boolean value indicating debug mode.
WebErrorScreenEvents::JS
Emitted when JavaScript code is being output.
Receives a single boolean value indicating debug mode.
CLI error screen events
Possible events emitted by the CliErrorScreen
class are listed in CliErrorScreenEvents
:
CliErrorScreenEvents::RENDER
Emitted when rendering in normal mode.
Receives an array with the following keys:
&title
: first line of output&output
: error messageexception
: the exceptionoutput_buffer
: string|null
CliErrorScreenEvents::RENDER_DEBUG
Emitted when rendering in debug mode.
Receives an array with the following keys:ng keys:
&title
: first line of output&output
: error messageexception
: the exceptionoutput_buffer
: string|null
Event listener examples
Logging
Logging uncaught exceptions into a file:
<?php use Kuria\Debug\Error; use Kuria\Error\ErrorHandlerEvents; $errorHandler->on(ErrorHandlerEvents::EXCEPTION, function (\Throwable $exception, bool $debug) { $logFilePath = sprintf('./errors_%s.log', $debug ? 'dev' : 'prod'); $entry = sprintf( "[%s] %s: %s in file %s on line %d\n", date('Y-m-d H:i:s'), Error::getExceptionName($exception), $exception->getMessage(), $exception->getFile(), $exception->getLine() ); file_put_contents($logFilePath, $entry, FILE_APPEND | LOCK_EX); });
Disabling the "@" operator
This listener causes statements like echo @$invalidVariable;
to throw an exception regardless of the "shut-up" operator.
<?php use Kuria\Error\Exception\ErrorException; use Kuria\Error\ErrorHandlerEvents; $errorHandler->on(ErrorHandlerEvents::ERROR, function (ErrorException $exception, bool $debug) { $exception->force(); });
Altering the error screens
Note
Examples are for the WebErrorScreen
.
Changing default labels in normal mode:
<?php use Kuria\Error\Screen\WebErrorScreen; use Kuria\Error\Screen\WebErrorScreenEvents; $errorScreen = $errorHandler->getErrorScreen(); if (!$errorHandler->isDebugEnabled() && $errorScreen instanceof WebErrorScreen) { $errorScreen->on(WebErrorScreenEvents::RENDER, function ($event) { $event['heading'] = 'It is all your fault!'; $event['text'] = 'You have broken everything and now I hate you.'; }); }
Adding a customized section to the debug screen:
<?php use Kuria\Error\Screen\WebErrorScreen; use Kuria\Error\Screen\WebErrorScreenEvents; $errorScreen = $errorHandler->getErrorScreen(); if ($errorHandler->isDebugEnabled() && $errorScreen instanceof WebErrorScreen) { // add custom CSS $errorScreen->on(WebErrorScreenEvents::CSS, function () { echo '#custom-group {color: #f60000;}'; }); // add custom HTML $errorScreen->on(WebErrorScreenEvents::RENDER_DEBUG, function (array $view) { $view['extras'] .= <<<HTML <div id="custom-group" class="group"> <div class="section"> Example of a custom section </div> </div> HTML; }); }