Download the PHP package snicco/psr7-error-handler without Composer

A powerful and customizable error handler for PSR-7/PSR-15 applications

The ErrorHandler component of the Snicco project is a standalone error handler for PHP applications that use PSR-7 requests.

Table of contents

1. Installation
2. Needed collaborators
   1. RequestAwareLogger
   2. ExceptionInformationProvider
   3. ExceptionDisplayer
3. Full example
4. Exception utilities
5. Contributing
6. Issues and PR's
7. Security

Installation

Collaborators for the HTTP error handler

On a high level, the HttpErrorHandler interface is responsible for transforming instances of Throwable into instances of Psr\Http\Message\ResponseInterface.

This package provides a TestErrorHandler, which just re-throws exceptions and a ProductionErrorHandler, which is the main focus of this documentation.

To instantiate the ProductionErrorHandler, we need the following collaborators:

The RequestAwareLogger

The RequestAwareLogger is a simple wrapper class around a PSR-3 logger.

It allows you to add log context to each log entry depending on the caught exception, the current request, etc.

The last argument passed to RequestAwareLogger::__construct() is variadic and accepts instances of RequestLogContext.

This is how you use it:

(Monolog is just an example, you can use any PSR-3 logger.)

The ExceptionInformationProvider

The ExceptionInformationProvider is responsible for converting instances of Throwable to an instance of ExceptionInformation.

ExceptionInformation is a value object that consist of:

• a unique identifier for the exception that will be passed as log context and can be displayed to users.
• an HTTP status code that should be used when displaying the exception.
• a safe title for displaying the exception (safe meaning "does not contain sensitive information").
• a safe message for displaying the exception (safe meaning "does not contain sensitive information").
• the original Throwable
• a transformed Throwable
• the original instance of Psr\Http\Message\ServerRequestInterface

This package comes with a InformationProviderWithTransformation implementation of that interface.

You can instantiate this class like so:

As its class name suggests, the InformationProviderWithTransformation allows you to transform exceptions into other kinds of exceptions.

This is done by using ExceptionTransformers.

An example on how to transform custom exception classes to an instance of HttpException.

If you provide no ExceptionTransformers every exception will be converted to a HttpException)

The ExceptionDisplayer

An ExceptionDisplayer is responsible for displaying ExceptionInformation.

An ExceptionDisplayer has one content-type that it supports.

The ProductionExceptionHandler accepts one or more ExceptionDisplayers and will determine the best displayer for the current request.

This package comes with two default displayers that will be used as a fallback:

• FallbackHtmlDisplayer, for requests where the Accept header is text/html.
• FallbackJsonDisplayer, for requests where the Accept header is application/json.

The best displayer for the combination of exception/request is determined by using DisplayerFilters.

Out of the box this package comes with the following filters:

• Delegating, delegates to other filters.
• CanDisplay, filters based on the return value of ExceptionDisplayer::canDisplay()
• Verbosity, filters based on the return value of ExceptionDisplayer::isVerbose() and the verbosity level during the current request.
• ContentType, filters based on the return value of ExceptionDisplayer::supportedContentType() and the Accept header of the current request. ! Important: This filter only performs very basic content negotiation. Content-negotiation is out of scope for this package and should be performed in a middleware.

Full working example

This is a working example of how you would instantiate the ProductionErrorHandler, preferably in your dependency-injection container.

Then use the instantiated error handler in a middleware like so:

Exception utilities

User-facing exceptions

This package comes with a UserFacing interface, which your custom exceptions can implement.

If an exception that implements UserFacing is thrown, the return values of UserFacing::safeTitle() and UserFacing::safeMessage() will be used to create the ExceptionInformation, instead of the default HTTP error messages that might not make sense to your users.

The original exception message will be logged while your users get to see something they can relate (a little more) to.

HTTP exceptions

This packages comes with a generic HTTPException class that you can throw in your HTTP related code (mostly middleware).

This allows you to dictate the HTTP response code and optionally additional response headers.

The difference between using the HTTPException class and using an ExceptionTransformer is that the latter is intended for your domain exceptions while HTTPExceptions should be thrown only in HTTP related code (like middleware and Controllers).

Contributing

This repository is a read-only split of the development repo of the Snicco project.

This is how you can contribute.

Reporting issues and sending pull requests

Please report issues in the Snicco monorepo.

Security

If you discover a security vulnerability, please follow our disclosure procedure.