ErrorHandler

The ErrorHandler class is designed to capture core PHP errors and uncaught exceptions, and give developers a chance to handle the errors gracefully. Such as displaying an error page and logging the error. The class is designed to handle errors differently when running under different environments. Such as "live" and "development".

The most basic setup, this will handle errors by displaying the error message and a stack trace. Either as an HTML page, or a simple message when being used with a command line app.

$handler = new ErrorHandler();
$handler->handle();

That's all there is too it. That may be fine during development, but in production you will probably want to display your own error page. (One that doesn't show sensitive information) You do that by registering your own error callback instead of using the default, which will be called when an error is captured. You can do whatever you want in that function: include an error page, email yourself the error, etc.

$handler = new ErrorHandler();
$handler->setCallback(function($handler) {
     // The $handler parameter is the ErrorHandler instance.
     // The $handler->getLastError() method returns an exception which
     // describes the error.
     include("templates/error.php");
});

$handler->handle();

That's looking better, but you may want to handle errors differently in production and development. For that situation the ErrorHandler class supports the use of "environments". You tell the handler which environment -- "live", "staging", "development" -- is currently running, and then defined different callbacks for each possible environment.

if (!defined("ENVIRONMENT")) {
     define("ENVIRONMENT", "live");
}
$handler = new ErrorHandler();
$handler->setCallback("live", function($handler) {
     include("templates/live_error.php");
});
$handler->setCallback("dev", function($handler) {
     include("templates/dev_error.php");
});
$handler->setRunningEnvironment(ENVIRONMENT);
$handler->handle();

We pass the currently running environment to the ErrorHandler::setRunningEnvironment() method. When an error is trapped, the callback set for that environment will be called. The example could be shortened a bit.

if (!defined("ENVIRONMENT")) {
     define("ENVIRONMENT", "live");
}

$handler = new ErrorHandler();
$handler->setCallback("live", function($handler) {
     include("templates/live_error.php");
});
$handler->setCallback("dev", function($handler) {
     include("templates/dev_error.php");
});
$handler->handle(ENVIRONMENT);

This time we pass the running environment straight to the ErrorHandler::handle() method. In fact the ::handle() method can even take an error callback.

$handler = new ErrorHandler();
$handler->handle(function() {
     include("templates/error.php");
});

That's the short, short example for using the error handler.

There are many more options for dealing with how errors are handled, and which errors are handled. See the API documentation for more information.

Notes: The instances of this class stop handling errors when the instance goes out of scope. Therefore the instance should be created in the global scope.

Only the single error is handled, because the errors it handles are meant to kill execution of the script. The callbacks should handle a graceful shutdown.

::setCallback

Sets the callback that will be called when an error is handled.

$handler->setCallback(function($handler) {
   // The $handler parameter is the ErrorHandler instance.
   // The $handler->getLastError() method returns an exception which
   // describes the error.
   include("templates/error.php");
});

$handler->setCallback("live", function($handler) {
   include("templates/error_live.php");
});

$handler->setCallback("dev", function($handler) {
   include("templates/error_dev.php");
});

::setCoreErrors

Sets the core errors which will be handled.

$handler->setCoreErrors([E_ERROR, E_WARNING, E_DEPRECIATED]);

$handler->setCoreErrors("live", [E_ERROR, E_WARNING]);

$handler->setCoreError("dev", [E_ERROR, E_WARNING, E_NOTICE]);

::removeCoreError

Stops handling a core error.

$handler->removeCoreError(E_NOTICE);

$handler->removeCoreError("live", E_NOTICE);

$handler->removeCoreError("dev", E_DEPRECIATED);

::setUncaughtExceptions

Sets the uncaught exceptions which will be handled.

$handler->setUncaughtExceptions([RuntimeException::class, LogicException::class]);

$handler->setUncaughtException("live", [RuntimeException::class, LogicException::class]);

$handler->setUncaughtException("dev", [InvalidArgumentException::class, LogicException::class]);

::removeUncaughtException

Stops handling an uncaught exception.

$handler->removeUncaughtException(LogicError::class);

$handler->removeUncaughtException("live", LogicError::class);

$handler->removeUncaughtException("dev", InvalidArgumentException::class);

::isHandlingCoreError

Returns whether errors of the given type are being handled.

$is_handled = $handler->isHandlingCoreError(E_WARNING);

$is_handled = $handler->isHandlingCoreError("live", E_WARNING);

::isHandlingUncaughtException

Returns whether the given exception is being handled.

$is_handled = $handler->isHandlingUncaughtException(LogicException::class);

$is_handled = $handler->isHandlingUncaughtException("live", LogicException::class);