README

Installation
Introduction
Enabling error handling
About error handlers
Error handling
Exception handling
- Exception handler callbacks
- Sophisticated exception handlers
Converting errors to exceptions

Installation

composer require weew/error-handler

Introduction

This little library allows you to easily handle exceptions, recoverable and fatal errors globally in your code. Some types of errors are recoverable some are not, this kind of error handling should be used as last resort to do some logging, etc.

Enabling error handling

You can manually toggle between three kinds of errors that the error handler can handle: exceptions, recoverable and fatal errors.

$errorHandler = new ErrorHandler();

// enable exception handling
$errorHandler->enableExceptionHandling();

// enable handling of recoverable php errors
$errorHandler->enableRecoverableErrorHandling();

// enable handling of fatal php errors
$errorHandler->enableFatalErrorHandling();

// enable handling of recoverable and fatal php errors
$errorHandler->enableErrorHandling();

// enable handling of exceptions, recoverable and fatal php errors
$errorHandler->enable();

You can always check whether some kind of error handling has been enabled.

$errorHandler->isExceptionHandlingEnabled();
$errorHandler->isRecoverableErrorHandlingEnabled();
$errorHandler->isFatalErrorHandlingEnabled();

About error handlers

Error handlers are small pieces of logic that you can register on the ErrorHandler. There are two different kinds of handlers: error and exception handlers. They all follow the same pattern: a handler accepts and abstraction of the occurred error / exception and returns a boolean value determining whether the error has bee handled or not. If the error has been handled, error handlers must return true, returning false is optional.

Error handling

In PHP there are two different kind of errors, the ones that you can recover from and the ones you can't. You can differentiate between them if you want to. All PHP errors are converted to an instance of IError. It will contain all the relevant information about the occurred error and be passed down to your error handlers.

Abstraction of PHP errors

All PHP errors are converted to an instance of IError. It serves as a holder for all the relevant error information and makes it accessible trough few getter methods.

// is this kind of error recoverable or not
$error->isRecoverable();

// get error type (E_WARNING, E_STRICT, etc.)
$error->getCode();

// get error message
$error->getMessage();

// get error file
$error->getFile();

// get error line
$error->getLine();

There is also a very useful ErrorType class that holds information about all kinds of PHP errors and might be used to get error type name based on the error type number, check if a particular type of error is recoverable or not, and so on.

Handling recoverable PHP errors

Creating an error handler for recoverable errors.

$errorHandler = new ErrorHandler();
$errorHandler->addRecoverableErrorHandler(function(IError $error) {
    return true;
});

Handling fatal PHP errors

Creating an error handler for fatal errors.

$errorHandler = new ErrorHandler();
$errorHandler->addFatalErrorHandler(function(IError $error) {
    return true;
});

Handling both kinds of errors

Creating an error handler that covers both, recoverable and fatal errors.

$errorHandler = new ErrorHandler();
$errorHandler->addErrorHandler(function(IError $error) {
    if ($error->isRecoverable()) {
        return true;
    }
});

Sophisticated error handlers

If you do not want to work with callbacks, you can create a sophisticated error handler class. All you have to do is to implement the INativeErrorHandler interface.

class CustomErrorHandler implements INativeErrorHandler {
    public function handle(IError $error) {
        return true;
    }
}

$errorHandler = new ErrorHandler();
$errorHandler->addErrorHandler(new CustomErrorHandler());

Exception handling

Error handler allows you to define the types of exceptions you want to handle in your exception handler. There are two ways you can plug in an exception handler: using callbacks or using an implementation of the IExceptionHandler interface.

Exception handler callbacks

When using simple callables / callbacks as exception handlers, all you have to do is to define the exception type in the function signature. Error handler will then figure out what kind of exceptions are supported by your exception handler and give it only the ones it can handle. Same as with errors, exception handlers must return true in order to tell that exception has been handled.

Below is an example of an exception handler that handles only exceptions of type HttpException or it's subclasses.

$errorHandler = new ErrorHandler();
$errorHandler->addExceptionHandler(function(HttpException $ex) {
    return true;
});

Sophisticated exception handlers

You can add an exception handler by passing in an instance of IExceptionHandler. When an exception is thrown, error handler will ask your custom exception handler whether it supports this kind of exceptions and if so, ask your handler to handle this exception.

class CustomExceptionHandler implements IExceptionHandler {
    public function supports(Exception $ex) {
        return $ex instanceof HttpException;
    }

    public function handle(HttpException $ex) {
        return true;
    }
}

$errorHandler = new ErrorHandler();
$errorHandler->addExceptionHandler(new CustomExceptionHandler());

Converting errors to exceptions

When a php errors occurres, it will be converted to an instance of IError and passed down to you error handlers. This requires you to differentiate between errors and exceptions. If you prefer dealing with errors as if they were regular exceptions, you can do so by telling the error handler to convert all php errors to appropriate exceptions. Do not forget to enable exception handling, otherwise you will not be able to handle them anymore.

$errorHandler = new ErrorHandler();
$errorHandler->convertErrorsToExceptions();
$errorHandler->enableExceptionHandling();

// or

$errorHandler = new ErrorHandler(true);
$errorHandler->enableExceptionHandling();

Now, whenever for example an E_WARNING occurres, you'll get a WarningException. To handle all WarningException occurrences you can create a regular exception handler.

$errorHandler->addExceptionHandler(function(WarningException $ex){
    return true;
});

If you want to deal with all PHP errors that are converted to an exception in the same handler, you can create an exception handler for the IErrorException interface.

$errorHandler->addExceptionHandler(function(IErrorException $ex) {
    // all kinds of php errors (E_WARNING, E_STRICT, etc.) can now be handled
    // here in form of an exception
    return true;
});

Below is a full list of available exceptions.

All exceptions listed above share the same IErrorException interface that offers some getters to access the error information.

// get numeric representation of the error type (E_WARNING, E_STRICT, etc.)
$ex->getErrorCode();

// get error message
$ex->getErrorMessage();

// get error file
$ex->getErrorFile();

// get error line
$ex->getErrorLine();

// check wether the error was recoverable or not
$ex->isRecoverable();

weew / error-handler

Maintainers

Details