PHP ErrorHandler library

Translations: Español

PHP library for handling exceptions.

To handle exceptions you can use the josantonius/exception-handler library.

---

• Requirements
• Installation
• Available Classes
  • ErrorHandler
  • ErrorHandled
  • ErrorException
• Exceptions Used
• Quick Start
• Usage
• Tests
• TODO
• Changelog
• Contribution
• Sponsor
• License

---

Requirements

This library is compatible with the PHP versions: 8.1.

Installation

The preferred way to install this extension is through Composer.

To install PHP ErrorHandler library, simply:

composer require josantonius/error-handler

The previous command will only install the necessary files, if you prefer to download the entire source code you can use:

composer require josantonius/error-handler --prefer-source

You can also clone the complete repository with Git:

git clone https://github.com/josantonius/php-error-handler.git

Available Classes

ErrorHandler

Available methods in Josantonius\ErrorHandler\ErrorHandler:

Convert errors to exceptions

$errorHandler->convertToExceptions(int ...$errorLevel): self

@param int[] $erroLevel Define the specific error levels that will become exceptions.

@throws WrongErrorLevelException

@see https://www.php.net/manual/en/errorfunc.constants.php to view available error levels.

The exception will be thrown from the ErrorException instance.

Convert errors to exceptions except for some of them

$errorHandler->convertToExceptionsExcept(int ...$errorLevel): self

@param int[] $erroLevel Define specific error levels that will not become exceptions.

@throws WrongErrorLevelException

@see https://www.php.net/manual/en/errorfunc.constants.php to view available error levels.

The exception will be thrown from the ErrorException instance.

Register error handler function

$errorHandler->register(callable $callback): self

@see https://www.php.net/manual/en/functions.first_class_callable_syntax.php for more information about first class callable syntax.

The error handler will receive the ErrorHandled object.

Use error reporting to determine which errors are handled

$errorHandler->useErrorReportingLevel(): self

@see https://www.php.net/manual/en/function.error-reporting.php for more information.

If the setting value in error_reporting() is used to determine which errors are handled.

If this method is not used, all errors will be sent to the handler.

ErrorHandled

Available methods in Josantonius\ErrorHandler\ErrorHandled:

Gets error file

$errorHandled->getFile(): string

Gets error message

$errorHandled->getMessage(): string

Gets error level

$errorHandled->getLevel(): int

Gets error file line

$errorHandled->getLine(): int

Gets error name

$errorHandled->getName(): string

ErrorException

The available methods in Josantonius\ErrorHandler\ErrorException are the same as in ErrorHandled.

This class extends from ErrorException.

Exceptions Used

WrongErrorLevelException

Josantonius\ErrorHandler\Exceptions\WrongErrorLevelException if error level is not valid.

Quick Start

To use this library:

use Josantonius\ErrorHandler\ErrorHandler;

$errorHandler = new ErrorHandler();

Usage

Examples of use for this library:

Convert all errors to exceptions

$errorHandler->convertToExceptions();

Convert certain errors to exceptions

$errorHandler->convertToExceptions(E_USER_ERROR, E_USER_WARNING);

Only E_USER_ERROR and E_USER_WARNING will be converted to exceptions.

Convert all errors to exceptions except for some of them

$errorHandler->convertToExceptionsExcept(E_USER_DEPRECATED, E_USER_NOTICE);

All errors except E_USER_DEPRECATED and E_USER_NOTICE will be converted to exceptions.

Convert to exceptions using error reporting level

error_reporting(E_USER_ERROR) 

$errorHandler->convertToExceptions()->useErrorReportingLevel();

Only E_USER_ERROR will be converted to exception.

Convert to exceptions and use an exception handler

set_exception_handler(function (\ErrorException $exception) {
    log([
        'level'   => $exception->getLevel(),
        'message' => $exception->getMessage(),
        'file'    => $exception->getFile(),
        'line'    => $exception->getLine(),
        'name'    => $exception->getName(),
    ]);
});

$errorHandler->convertToExceptions();

Only E_USER_ERROR will be converted to exception.

Register an error handler function

function handler(Errorhandled $errorHandled): void {
    log([
        'level'   => $errorHandled->getLevel(),
        'message' => $errorHandled->getMessage(),
        'file'    => $errorHandled->getFile(),
        'line'    => $errorHandled->getLine(),
        'name'    => $errorHandled->getName(),
    ]);
 }

$errorHandled->register(
    callback: handler(...)
);

Register error handler function and convert to exceptions

class Handler {
    public static function errors(Errorhandled $exception): void { /* do something */ }
}

$errorHandled->register(
    callback: Handler::errors(...)
)->convertToExceptions();

Or:

$errorHandled->register(
    callback: Handler::errors(...)
)->convertToExceptions(E_USER_ERROR, E_USER_WARNING);

Or:

$errorHandled->register(
    callback: Handler::errors(...)
)->convertToExceptionsExcept(E_USER_DEPRECATED, E_USER_NOTICE);

The error will be sent to the error handler and then throw the exception.

Register error handler function, convert to exceptions and use error reporting level

class Handler {
    public function errors(Errorhandled $exception): void { /* do something */ }
}

error_reporting(E_USER_ERROR) 

$handler = new Handler();

$errorHandled->register(
    callback: $handler->errors(...),
)->convertToExceptions()->useErrorReportingLevel();

Only E_USER_ERROR will be passed to the handler and converted to exception.

Tests

To run tests you just need composer and to execute the following:

git clone https://github.com/josantonius/php-error-handler.git

cd php-error-handler

composer install

Run unit tests with PHPUnit:

composer phpunit

Run code standard tests with PHPCS:

composer phpcs

Run PHP Mess Detector tests to detect inconsistencies in code style:

composer phpmd

Run all previous tests:

composer tests

TODO

• Add new feature
• Improve tests
• Improve documentation
• Improve English translation in the README file
• Refactor code for disabled code style rules (see phpmd.xml and phpcs.xml)

Changelog

Detailed changes for each release are documented in the release notes.

Contribution

Please make sure to read the Contributing Guide, before making a pull request, start a discussion or report a issue.

Thanks to all contributors! ❤️

Sponsor

If this project helps you to reduce your development time, you can sponsor me to support my open source work 😊

License

This repository is licensed under the MIT License.

Copyright © 2016-present, Josantonius