README

Makes handling and debugging PHP errors suck less. Based on kuria/error (https://github.com/kuria/error)

Table of Contents

• Features
• Requirements
• Usage example
• Event system
  • Error handler events
  • Web error screen events
  • CLI error screen events
• Event listener examples
  • Logging
  • Disabling the @ operator
  • Altering the error screens

Features

• debug and non-debug mode
• converts PHP errors (warnings, notices, etc) into exceptions
  • respects the global error_reporting setting
• 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)
• 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:
  1. object $exception
     • instance of ErrorException or Kuria\Error\ContextualErrorException
  2. bool $debug
  3. 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:
  1. object $exception
  2. bool $debug
  3. 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:
  1. object $exception
  2. bool $debug

Web error screen events

Possible events emitted by the WebErrorScreen class:

render

• emitted when rendering in non-debug mode
• arguments:
  1. array &$view
     • title: used in <title>
     • heading: used in <h1>
     • text: content of the default paragraph
     • extras: custom HTML after the main section
       • append to this using .=
  2. object $exception
  3. string|null $outputBuffer
  4. WebErrorScreen $screen

render.debug

• emitted when rendering in debug mode
• arguments:
  1. array &$view
     • title: used in <title>
     • extras: custom HTML after the main section
       • append to this using .=
  2. object $exception
  3. string|null $outputBuffer
  4. WebErrorScreen $screen

layout.css

• emitted when CSS styles are being output
• arguments:
  1. string &$css
     • reference to the CSS output
     • it can be appended to or replaced
  2. bool $debug
  3. WebErrorScreen $screen

layout.js

• emitted when JavaScript code is being output
• arguments:
  1. string &$js
     • reference to the JavaScript output
     • it can be appended to or replaced
  2. bool $debug
  3. WebErrorScreen $screen

CLI error screen events

Possible events emitted by the CliErrorScreen class:

render

• emitted when rendering in non-debug mode
• arguments:
  1. array &$view
     • title: first line of output
     • output: error message
       • you can append to it using .=
  2. object $exception
  3. string|null $outputBuffer
  4. CliErrorScreen $screen

render.debug

• emitted when rendering in debug mode
• arguments:
  1. array &$view
     • title: first line of output
     • output: exception information
       • you can append to it using .=
  2. object $exception
  3. string|null $outputBuffer
  4. 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;
            })
        ;
    }
});