weew / error-handler
Error handler for php.
Installs: 15 519
Dependents: 2
Suggesters: 0
Security: 0
Stars: 0
Watchers: 2
Forks: 1
Open Issues: 0
Requires
- weew/helpers-array: ^1.0
- weew/helpers-string: ^1.0
Requires (Dev)
- phpunit/phpunit: ^4.7
- satooshi/php-coveralls: ^0.6.1
- weew/http-client: ^1.1
- weew/http-server: ^1.0
README
Table of contents
- Installation
- Introduction
- Enabling error handling
- About error handlers
- Error handling
- Exception handling
- 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();