Download the PHP package lcobucci/error-handling-middleware without Composer
On this page you can find all versions of the php package lcobucci/error-handling-middleware. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download lcobucci/error-handling-middleware
More information about lcobucci/error-handling-middleware
Files in lcobucci/error-handling-middleware
Package error-handling-middleware
Short Description A PSR-15 middleware compatible with RFC 7807
License MIT
Informations about the package error-handling-middleware
Error handling middleware
Motivation
There are many PHP implementations for the RFC 7807, even providing PSR-15 middleware. However, most of them - if not all - mix content negotiation, logging, and formatting with error handling. Some even force you to throw specific types of exceptions in order for them to work.
I believe that those aren't the best design decisions and that we need more flexibility to solve this problem.
Installation
This package is available on Packagist, and we recommend you to install it using Composer:
Usage
In order to us this package you must add the middleware to your pipeline, configuring the desired behaviour (debug info strategy and status code extraction strategy).
Once this is set you'll be able to have your errors/exceptions converted into the correct HTTP responses.
Middleware position
This package provides two middleware for handling errors: error logging and error conversion.
They are designed to be used in the very beginning of the HTTP middleware pipeline, just after the content negotiation one:
With that we'll be able to perform the logging and conversion in the correct order,
delegating the content negotiation and formatting to ContentTypeMiddleware
- using
the configured formatters.
Important
The ErrorConversionMiddleware
uses an UnformattedResponse
to let the
ContentTypeMiddleware
perform the formatting. Make sure you have configured
formatters for the MIME types application/problem+json
and/or
application/problem+xml
.
It also makes the error/exception available in the error
attribute of the response,
so you may access it (if needed) by using another middleware between
ErrorConversionMiddleware
and ContentTypeMiddleware
.
Configuring the conversion middleware behaviour
There're two extension points that you can use for that: debug info strategy and status code extraction strategy.
You can also configure the response body attributes by implementing certain interfaces in your exceptions.
Debug info strategy
This defines how the _debug
property should be generated in the response body.
We provide two default implementations - one designed for production mode and the
other for development mode.
To configure this you must pass the desired implementation (or a customised one) as
the second argument of the ErrorConversionMiddleware
constructor.
To provide your own implementation you need to create a class that implements the
DebugInfoStrategy
interface.
Status code extraction strategy
This defines how the translation from error/exception to HTTP status code should be done. We provide a single default implementation for that, which is based on class maps.
To configure this you must pass the desired implementation (or a customised one) as
the third argument of the ErrorConversionMiddleware
constructor.
To provide your own implementation you need to create a class that implements the
StatusCodeExtractionStrategy
interface.
Default class map
The default map uses the marker interfaces in this packages to perform such translation. If the error/exception doesn't implement any of the marker interfaces, the error/exception code will be used (when it's different than zero), or fallback to the status code 500 (Internal Server Error).
The default map is:
Lcobucci\ErrorHandling\Problem\InvalidRequest
->400
Lcobucci\ErrorHandling\Problem\AuthorizationRequired
->401
Lcobucci\ErrorHandling\Problem\Forbidden
->403
Lcobucci\ErrorHandling\Problem\ResourceNotFound
->404
Lcobucci\ErrorHandling\Problem\Conflict
->409
Lcobucci\ErrorHandling\Problem\ResourceNoLongerAvailable
->410
Lcobucci\ErrorHandling\Problem\UnprocessableRequest
->422
Lcobucci\ErrorHandling\Problem\ServiceUnavailable
->503
This allows us to create our own exceptions that are automatically converted to the correct status code:
Important: you SHOULD NOT implement more than one of the marker interfaces, otherwise you may have unexpected results.
Customising the response body properties
With this library, you may modify the type
and title
properties of the generated
response and also append new members to it.
That's done by implementing the Typed
, Titled
, and/or Detailed
interfaces -
you don't necessarily need to implement all of them, only the ones you want.
The example below shows how to represent one of the samples in the RFC 7807:
License
MIT, see LICENSE.
All versions of error-handling-middleware with dependencies
ext-json Version *
fig/http-message-util Version ^1.1
lcobucci/content-negotiation-middleware Version ^3.1
psr/http-factory Version ^1.0
psr/http-message Version ^1.0
psr/http-server-handler Version ^1.0
psr/http-server-middleware Version ^1.0
psr/log Version ^3.0