constup-foss/php-exerr

PHP errors and exceptions.

1.0.0 2026-05-25 21:34 UTC

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.95
• phpunit/phpunit: ^13

MIT

• Nikola Stojiljković

README

Table of Contents

• Description
• Installation
• Available exceptions
  • abstract LibraryException
• Use
  • Extending a base exception
  • Throwing your exception
  • Advantages of the above architecture
• License
• Supporting development

Description

PHP Errors and exceptions.

This library contains a set of base exceptions with an expanded set of properties compared to PHP’s default \Exception. The idea is to provide standardized base exceptions that make controlling and debugging the application easier.

Installation

composer require constup-foss/php-exerr

Available exceptions

abstract LibraryException

Intended to be used in composer libraries. The following properties are added to the base \Exception:

• string $libraryName - Name of the library that threw the exception. Example: "constup-foss/php-exerr". Helps to identify the origin of the exception during debugging.

• ?string $debugMessage - Debug message that can be used to identify the exact cause of the exception. This message should be used for logging purposes only and must not be displayed to the user. It should contain as much information as possible to help identify the exact cause of the exception.

• ?string $userMessage - User-friendly message that can be displayed to the user. Must not contain sensitive information.

• ?int $httpResponseCode - HTTP response code that should be passed as the response.

• ?bool $recoverable - Indicates whether the exception is recoverable. If true, the exception should be handled gracefully and the application should continue running. If false, the exception should be handled and the application should terminate.

Use

Extending a base exception

Here is an example of your own custom exception based on the LibraryException. Note that this example contains all optional (nullable) properties, but you are free to omit them in your exceptions.

class YourCustomException extends LibraryException
{
    /**
     * Thrown when an item in the collection is not of the expected type.
     *
     * @param string $itemType
     * @param string $expectedType
     * @param int    $index
     *
     * @return $this
     */
    public function invalidItemTypeAtIndex(
        string $itemType,
        string $expectedType,
        int $index,
    ): self {
        $this->message = 'Validation error';
        $this->code = 1;
        $this->libraryName = 'your/library-name';
        $this->debugMessage = "Invalid item type at index: {$index}. Expected: {$expectedType}. Got: {$itemType}";
        $this->userMessage = 'You have provided invalid data. Please, try again.';
        $this->httpResponseCode = 400;
        $this->recoverable = false;

        return $this;
    }
}

Throwing your exception

throw new YourCustomException()->invalidItemTypeAtIndex($itemType, $expectedType, $index);

Advantages of the above architecture

• Exceptions can be classified by their Interface. When an exception that implements LibraryExceptionInterface is passed to an exception handler, the exception handler knows which properties to expect.

• An exception handler can classify exceptions by their class (YourCustomException from the example above).

• Having multiple exception methods in the same class brings the following benefits:

  • Your exceptions can be classified by their domain.

  • Managing of error codes is much easier. Each of your exceptions can have a possible range of codes. Exception codes that logically belong to the same range are not scattered across multiple files, making it easier to maintain and avoid conflicts.

License

MIT License

• License file: LICENSE.txt

• Online version: https://opensource.org/license/mit

Supporting development

If you like this library or find it useful, consider buying me a nice cup of coffee. Coffee fuels open source.