tobento/service-error-handler

PHP errors and exceptions handling

1.0.4 2023-02-05 15:00 UTC

This package is auto-updated.

Last update: 2024-03-05 17:07:00 UTC


README

The Error Handler Service provides tools to manage errors and exceptions.

Table of Contents

Getting started

Add the latest version of the error handler service project running this command.

composer require tobento/service-error-handler

Requirements

  • PHP 8.0 or greater

Highlights

  • Framework-agnostic, will work with any project
  • Decoupled design

Documentation

Error Handling

Check out Throwable Handlers to learn more about the Throwable Handlers.

use Tobento\Service\ErrorHandler\ErrorHandling;
use Tobento\Service\ErrorHandler\ThrowableHandlers;
use Tobento\Service\ErrorHandler\ThrowableHandlerFactory;
use Tobento\Service\ErrorHandler\Handler;

$throwableHandlers = new ThrowableHandlers(new ThrowableHandlerFactory());

// adding any handler:
// $throwableHandlers->add(ValidationExceptionHandler::class);
// $throwableHandlers->add(GeneralExceptionHandler::class);

// only on development:
$throwableHandlers->add(Handler\Debug::class);

// adding last:
$throwableHandlers->add(Handler\Errors::class);

(new ErrorHandling($throwableHandlers))->register();

Throwable Handlers

The throwable handlers can be used where you need to handle exceptions in general.

Create Throwable Handlers

use Tobento\Service\ErrorHandler\ErrorHandling;
use Tobento\Service\ErrorHandler\ThrowableHandlers;
use Tobento\Service\ErrorHandler\ThrowableHandlersInterface;
use Tobento\Service\ErrorHandler\ThrowableHandlerFactory;

$throwableHandlers = new ThrowableHandlers(new ThrowableHandlerFactory());

var_dump($throwableHandlers instanceof ThrowableHandlersInterface);
// bool(true)

With autowiring factory

The autowiring factory is needed if you Add Throwable Handlers with dependencies.

use Tobento\Service\ErrorHandler\ErrorHandling;
use Tobento\Service\ErrorHandler\ThrowableHandlers;
use Tobento\Service\ErrorHandler\ThrowableHandlersInterface;
use Tobento\Service\ErrorHandler\AutowiringThrowableHandlerFactory;

// Any PSR-11 container
$container = new \Tobento\Service\Container\Container();

$throwableHandlers = new ThrowableHandlers(
    new AutowiringThrowableHandlerFactory($container)
);

var_dump($throwableHandlers instanceof ThrowableHandlersInterface);
// bool(true)

Add Throwable Handler

By class instance

$throwableHandlers->add(new Handler\Errors());

By class name

$throwableHandlers->add(Handler\Errors::class);

By class name with build-in parameters (not resolvable by autowiring)

$throwableHandlers->add([ThrowableHandler::class, 'name' => 'value']);

By anonymous function

use Throwable;

$throwableHandlers->add(function(Throwable $t): mixed {
    // Return throwable if cannot handle, otherwise anything else.
    return $t;
});

Restrict Throwable Handler

By error level(s)

The throwable handler will only be used on the specified error levels.

$throwableHandlers->add(ThrowableHandler::class)
                  ->level(\E_USER_WARNING, \E_WARNING);

By exception(s)

The throwable handler will only be used on the specified exceptions.

$throwableHandlers->add(ThrowableHandler::class)
                  ->handles(SomeException::class, AnotherException::class);

Prioritize Throwable Handler

You might want to prioritize the excution order of the handlers by the following way (highest first):

$throwableHandlers->add(ThrowableHandler::class)
                  ->priority(1000); // is default

Handle Throwable

use Throwable;

try {
    // do something
} catch (Throwable $t) {
    // do something with the response:
    $response = $throwableHandlers->handleThrowable($t);
}

Handlers

Debug

The debug handler will render a debugging page on any exception not caught.

use Tobento\Service\ErrorHandler\Handler\Debug;
use Tobento\Service\View\ViewInterface;
use Tobento\Service\ErrorHandler\ThrowableHandlerInterface;

$debug = new Debug(
    view: null, // null|ViewInterface
);

var_dump($debug instanceof ThrowableHandlerInterface);
// bool(true)

Custom view

Check out View Service to learn more about the View in general.

private/
    view/
        debug/
            error.php
            throwable.php
use Tobento\Service\ErrorHandler\Handler\Debug;
use Tobento\Service\View\ViewInterface;
use Tobento\Service\View\View;
use Tobento\Service\View\PhpRenderer;
use Tobento\Service\Dir\Dirs;
use Tobento\Service\Dir\Dir;

$view = new View(
    new PhpRenderer(
        new Dirs(
            new Dir('/private/view'),
        )
    )
);

$debug = new Debug(
    view: $view, // null|ViewInterface
);

Errors

The errors handler will render an error page on shutdown.

use Tobento\Service\ErrorHandler\Handler\Errors;
use Tobento\Service\View\ViewInterface;
use Tobento\Service\ErrorHandler\ThrowableHandlerInterface;

$errors = new Errors(
    view: null, // null|ViewInterface
);

var_dump($errors instanceof ThrowableHandlerInterface);
// bool(true)

Custom error view

Check out View Service to learn more about the View in general.

private/
    view/
        error.php
use Tobento\Service\ErrorHandler\Handler\Errors;
use Tobento\Service\View\ViewInterface;
use Tobento\Service\View\View;
use Tobento\Service\View\PhpRenderer;
use Tobento\Service\Dir\Dirs;
use Tobento\Service\Dir\Dir;

$view = new View(
    new PhpRenderer(
        new Dirs(
            new Dir('/private/view'),
        )
    )
);

$errors = new Errors(
    view: $view, // null|ViewInterface
);

Log

The log handler will log any errors or exceptions.

use Tobento\Service\ErrorHandler\Handler\Log;
use Psr\Log\LoggerInterface;
use Monolog\Logger;
use Monolog\Handler\TestHandler;
use Tobento\Service\ErrorHandler\ThrowableHandlerInterface;

$logger = new Logger('name');
$logger->pushHandler(new TestHandler());

$log = new Log(
    logger: $logger, // Closure|LoggerInterface
);

var_dump($log instanceof ThrowableHandlerInterface);
// bool(true)

Example with Closure and throwable handlers

use Tobento\Service\ErrorHandler\Handler\Log;
use Psr\Log\LoggerInterface;
use Monolog\Logger;
use Monolog\Handler\TestHandler;

$throwableHandlers->add(new Log(function(): LoggerInterface {
    $logger = new Logger('name');
    $testHandler = new TestHandler();
    $logger->pushHandler($testHandler);
    return $logger;
}))->levels(E_ERROR, E_CORE_ERROR);

Credits