- Installation
- Introduction
- Enabling error handling
- About error handlers
- Error handling
- Exception handling
- Converting errors to exceptions
composer require weew/error-handler
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.
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();
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.
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.
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.
Creating an error handler for recoverable errors.
$errorHandler = new ErrorHandler();
$errorHandler->addRecoverableErrorHandler(function(IError $error) {
return true;
});
Creating an error handler for fatal errors.
$errorHandler = new ErrorHandler();
$errorHandler->addFatalErrorHandler(function(IError $error) {
return true;
});
Creating an error handler that covers both, recoverable and fatal errors.
$errorHandler = new ErrorHandler();
$errorHandler->addErrorHandler(function(IError $error) {
if ($error->isRecoverable()) {
return true;
}
});
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());
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.
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;
});
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());
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.
Error type | Exception name |
---|---|
E_COMPILE_ERROR |
CompileErrorException |
E_COMPILE_WARNING |
CompileWarningException |
E_CORE_ERROR |
CoreErrorException |
E_CORE_WARNING |
CoreWarningException |
E_DEPRECATED |
DeprecatedException |
E_ERROR |
ErrorException |
E_NOTICE |
NoticeException |
E_PARSE |
ParseException |
E_RECOVERABLE_ERROR |
RecoverableErrorException |
E_STRICT |
StrictException |
E_USER_DEPRECATED |
UserDeprecatedException |
E_USER_ERROR |
UserErrorException |
E_USER_NOTICE |
UserNoticeException |
E_USER_WARNING |
UserWarningException |
E_WARNING |
WarningException |
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();