youssef / error
Makes handling and debugging PHP errors suck less.
v0.1
2016-11-14 20:37 UTC
Requires
- php: >=5.3.0
- kuria/event: ~0.2.0
This package is not auto-updated.
Last update: 2024-12-16 13:33:19 UTC
README
Makes handling and debugging PHP errors suck less. Based on kuria/error (https://github.com/kuria/error)
Table of Contents
Features
- debug and non-debug mode
- converts PHP errors (warnings, notices, etc) into exceptions
- respects the global
error_reporting
setting
- respects the global
- handles uncaught exceptions and fatal errors (including parse errors)
- CLI error screen (writes errors to STDERR)
- web error screen (renders errors for web browsers)
- non-debug mode:
- simple error message
- does not disclose any internal information
- does not use any variation of the word "oops"
- debug mode:
- file paths and line numbers
- highlighted code previews
- stack traces
- argument lists
- variable contexts
- output buffer (can be shown as HTML too)
- plaintext trace (for copy-paste)
- non-debug mode:
- event system that can be utilised to:
- implement logging
- suppress or force errors conditionally
- change or add content to the error screens
Requirements
- PHP 5.3 or newer
Usage example
use Kuria\Error\ErrorHandler;
$debug = true; // true during development, false in production
error_reporting(E_ALL | E_STRICT); // configure the error reporting
$errorHandler = new ErrorHandler($debug);
$errorHandler->register();
// trigger an error to see the error handler in action
echo $invalidVariable;
Event system
- implemented using the kuria/event library
- the error handler fires events as it handles errors
- both built-in error screen implementations emit events as they render
Error handler events
Possible events emitted by the ErrorHandler
class:
error
- emitted when a PHP errors occurs
- arguments:
object $exception
- instance of
ErrorException
orKuria\Error\ContextualErrorException
- instance of
bool $debug
bool &$suppressed
- reference to the suppressed state of the error
- the error can be suppressed by current
error_reporting
configuration or by other event handlers
fatal
- emitted when an uncaught exception or a fatal error is being handled
- arguments:
object $exception
bool $debug
FatalErrorHandlerInterface &$handler
- reference to the current fatal error handler
emerg
- emitted when another exceptions has been thrown during fatal error handling
- more uncaught exceptions or a fatal error at this point will just kill the script
- arguments:
object $exception
bool $debug
Web error screen events
Possible events emitted by the WebErrorScreen
class:
render
- emitted when rendering in non-debug mode
- arguments:
array &$view
title
: used in<title>
heading
: used in<h1>
text
: content of the default paragraphextras
: custom HTML after the main section- append to this using
.=
- append to this using
object $exception
string|null $outputBuffer
WebErrorScreen $screen
render.debug
- emitted when rendering in debug mode
- arguments:
array &$view
title
: used in<title>
extras
: custom HTML after the main section- append to this using
.=
- append to this using
object $exception
string|null $outputBuffer
WebErrorScreen $screen
layout.css
- emitted when CSS styles are being output
- arguments:
string &$css
- reference to the CSS output
- it can be appended to or replaced
bool $debug
WebErrorScreen $screen
layout.js
- emitted when JavaScript code is being output
- arguments:
string &$js
- reference to the JavaScript output
- it can be appended to or replaced
bool $debug
WebErrorScreen $screen
CLI error screen events
Possible events emitted by the CliErrorScreen
class:
render
- emitted when rendering in non-debug mode
- arguments:
array &$view
title
: first line of outputoutput
: error message- you can append to it using
.=
- you can append to it using
object $exception
string|null $outputBuffer
CliErrorScreen $screen
render.debug
- emitted when rendering in debug mode
- arguments:
array &$view
title
: first line of outputoutput
: exception information- you can append to it using
.=
- you can append to it using
object $exception
string|null $outputBuffer
CliErrorScreen $screen
Event listener examples
Notes
- do not typehint the
Exception
class in your listeners if you want to be compatible with the new exception hierarchy in PHP 7
Logging
Logging unhandled errors into a file.
use Kuria\Error\Util\Debug;
$errorHandler->on('fatal', function ($exception, $debug) {
$logFilePath = sprintf('./errors_%s.log', $debug ? 'debug' : 'prod');
$entry = sprintf(
"[%s] %s - %s in file %s on line %d\n",
date('Y-m-d H:i:s'),
Debug::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.
$errorHandler->on('error', function ($exception, $debug, &$suppressed) {
$suppressed = false;
});
Altering the error screens
Examples for the web error screen.
Changing default labels of the non-debug error screen:
use Kuria\Error\Screen\WebErrorScreen;
$errorHandler->on('fatal', function ($exception, $debug, $screen) {
if (!$debug && $screen instanceof WebErrorScreen) {
$screen->on('render', function (&$view) {
$view['heading'] = 'It is all your fault!';
$view['text'] = 'You have broken everything and now I hate you.';
});
}
});
Adding customized section to the debug screen:
use Kuria\Error\Screen\WebErrorScreen;
$errorHandler->on('fatal', function ($exception, $debug, $screen) {
if ($debug && $screen instanceof WebErrorScreen) {
$screen
->on('layout.css', function (&$css) {
$css .= '#custom-group {color: #f60000;}';
})
->on('render.debug', function (&$view) {
$view['extras'] .= <<<HTML
<div id="custom-group" class="group">
<div class="section">
Example of a custom section
</div>
</div>
HTML;
})
;
}
});