PHPackages                             vinala/error - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Debugging & Profiling](/categories/debugging)
4. /
5. vinala/error

ActiveLibrary[Debugging & Profiling](/categories/debugging)

vinala/error
============

Makes handling and debugging PHP errors suck less.

v0.2.0(9y ago)014MITPHPPHP >=5.3.0

Since Dec 22Pushed 9y ago1 watchersCompare

[ Source](https://github.com/vinala/error)[ Packagist](https://packagist.org/packages/vinala/error)[ RSS](/packages/vinala-error/feed)WikiDiscussions master Synced 4w ago

READMEChangelog (2)Dependencies (1)Versions (6)Used By (0)

Error handler
=============

[](#error-handler)

Makes handling and debugging PHP errors suck less.

Table of Contents
-----------------

[](#table-of-contents)

- [Features](#features)
- [Requirements](#requirements)
- [Usage example](#usage)
- [Event system](#event-system)
    - [Error handler events](#error-handler-events)
    - [Web error screen events](#web-error-screen-events)
    - [CLI error screen events](#cli-error-screen-events)
- [Event listener examples](#listener-examples)
    - [Logging](#listener-logging)
    - [Disabling the @ operator](#listener-disable-shutup)
    - [Altering the error screens](#listener-custom-content)

 Features
---------------------------------------------

[](#-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:
        [![Web error screen in non-debug mode](https://camo.githubusercontent.com/ed530121076fe4e6a8b152442841ab8158dc96ade6610cec946a1b5a897e3a4c/687474703a2f2f7374617469632e73686972612e637a2f6b757269612f6572726f722f76302e322e782f6e6f6e2d64656275672d7468756d622e676966)](http://static.shira.cz/kuria/error/v0.2.x/non-debug.png)
        - simple error message
        - does not disclose any internal information
        - does not use any variation of the word "oops"
    - debug mode:
        [![Web error screen in debug mode](https://camo.githubusercontent.com/7d12d69fdfbff61236eb7bd33c7ec23ad1a2cb35cd4931bcac760f222fbf232e/687474703a2f2f7374617469632e73686972612e637a2f6b757269612f6572726f722f76302e322e782f64656275672d7468756d622e676966)](http://static.shira.cz/kuria/error/v0.2.x/debug.png)
        - 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
-----------------------------------------------------

[](#-requirements)

- PHP 5.3 or newer

 Usage example
-----------------------------------------------

[](#-usage-example)

```
use Vinala\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
-----------------------------------------------------

[](#-event-system)

- implemented using the [kuria/event](https://github.com/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

[](#-error-handler-events)

Possible events emitted by the `ErrorHandler` class:

#### error

[](#error)

- emitted when a PHP errors occurs
- arguments:
    1. `object $exception`
        - instance of `ErrorException` or `Vinala\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

[](#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

[](#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

[](#-web-error-screen-events)

Possible events emitted by the `WebErrorScreen` class:

#### render

[](#render)

- emitted when rendering in **non-debug mode**
- single argument - an event array with the following keys:
    - `&title`: used in ``
    - `&heading`: used in ``
    - `&text`: content of the default paragraph
    - `&extras`: custom HTML after the main section
    - `exception`: the exception
    - `output_buffer`: string|null
    - `screen`: instance of `WebErrorScreen`

#### render.debug

[](#renderdebug)

- emitted when rendering in **debug mode**
- single argument - an event array with the following keys:
    - `&title`: used in ``
    - `&extras`: custom HTML after the main section
    - `exception`: the exception
    - `output_buffer`: string|null
    - `screen`: instance of `WebErrorScreen`

#### layout.css

[](#layoutcss)

- emitted when CSS styles are being output
- single argument - an event array with the following keys:
    - `&css`: the CSS output
    - `debug`: boolean
    - `screen`: instance of `WebErrorScreen`

#### layout.js

[](#layoutjs)

- emitted when JavaScript code is being output
- single argument - an event array with the following keys:
    - `&js`: the JS output
    - `debug`: boolean
    - `screen`: instance of `WebErrorScreen`

###  CLI error screen events

[](#-cli-error-screen-events)

Possible events emitted by the `CliErrorScreen` class:

#### render

[](#render-1)

- emitted when rendering in non-debug mode
- single argument - an event array with the following keys:
    - `&title`: first line of output
    - `&output`: error message
    - `exception`: the exception
    - `output_buffer`: string|null
    - `screen`: instance of `WebErrorScreen`

#### render.debug

[](#renderdebug-1)

- emitted when rendering in debug mode
- single argument - an event array with the following keys:
    - `&title`: first line of output
    - `&output`: error message
    - `exception`: the exception
    - `output_buffer`: string|null
    - `screen`: instance of `WebErrorScreen`

###  Event listener examples

[](#-event-listener-examples)

#### Notes

[](#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)

Logging unhandled errors into a file.

```
use Vinala\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

[](#-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

[](#-altering-the-error-screens)

Examples for the web error screen.

Changing default labels of the non-debug error screen:

```
use Vinala\Error\Screen\WebErrorScreen;

$errorHandler->on('fatal', function ($exception, $debug, $screen) {
   if (!$debug && $screen instanceof WebErrorScreen) {
        $screen->on('render', function ($event) {
            $event['heading'] = 'It is all your fault!';
            $event['text'] = 'You have broken everything and now I hate you.';
        });
    }
});

```

Adding customized section to the debug screen:

```
use Vinala\Error\Screen\WebErrorScreen;

$errorHandler->on('fatal', function ($exception, $debug, $screen) {
   if ($debug && $screen instanceof WebErrorScreen) {
        $screen
            ->on('layout.css', function ($event) {
                $event['css'] .= '#custom-group {color: #f60000;}';
            })
            ->on('render.debug', function ($event) {
                $event['extras'] .=