Repository files navigation

There are many PHP implementations for theRFC 7807,even providingPSR-15 middleware. However,most of them - if not all - mix content negotiation, logging, and formatting witherror handling. Some even force you to throw specific types of exceptions in orderfor them to work.

I believe that those aren't the best design decisions and that we need moreflexibility to solve this problem.

This package is available onPackagist, and we recommend you to install it usingComposer:

composer require lcobucci/error-handling-middleware

In order to us this package you must add the middleware to your pipeline, configuringthe 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 thecorrect HTTP responses.

This package provides two middleware for handling errors: error logging and errorconversion.

They are designed to be used in the very beginning of the HTTP middleware pipeline,just after thecontent negotiation one:

<?phpuseLcobucci\ContentNegotiation\ContentTypeMiddleware;useLcobucci\ErrorHandling\ErrorConversionMiddleware;useLcobucci\ErrorHandling\ErrorLoggingMiddleware;// In a Laminas Mezzio application, it would look like this:$application->pipe(ContentTypeMiddleware::fromRecommendedSettings(/* ... */ ));// Very first middleware$application->pipe(newErrorConversionMiddleware(/* ... */ ));$application->pipe(newErrorLoggingMiddleware(/* ... */ ));// all other middleware.

With that we'll be able to perform the logging and conversion in the correct order,delegating the content negotiation and formatting toContentTypeMiddleware - usingthe configured formatters.

TheErrorConversionMiddleware uses anUnformattedResponse to let theContentTypeMiddleware perform the formatting. Make sure you have configuredformatters for the MIME typesapplication/problem+json and/orapplication/problem+xml.

It also makes the error/exception available in theerror attribute of the response,so you may access it (if needed) by using another middleware betweenErrorConversionMiddleware andContentTypeMiddleware.

There're two extension points that you can use for that: debug info strategy andstatus code extraction strategy.

You can also configure the response body attributes by implementing certain interfacesin your exceptions.

This defines how the_debug property should be generated in the response body.We provide two default implementations - one designed for production mode and theother for development mode.

To configure this you must pass the desired implementation (or a customised one) asthe second argument of theErrorConversionMiddleware constructor.

To provide your own implementation you need to create a class that implements theDebugInfoStrategy interface.

This defines how the translation from error/exception to HTTP status code shouldbe done. We provide a single default implementation for that, which is based onclass maps.

To configure this you must pass the desired implementation (or a customised one) asthe third argument of theErrorConversionMiddleware constructor.

To provide your own implementation you need to create a class that implements theStatusCodeExtractionStrategy interface.

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/exceptioncode will be used (when it's different than zero), or fallback to the status code500 (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 thecorrect status code:

<?phpdeclare(strict_types=1);namespaceMy\Fancy\App\UserManagement;useLcobucci\ErrorHandling\Problem\ResourceNotFound;useRuntimeException;finalclass UserNotFoundextends RuntimeExceptionimplements ResourceNotFound{}

Important: you SHOULD NOT implement more than one of the marker interfaces,otherwise you may have unexpected results.

With this library, you may modify thetype andtitle properties of the generatedresponse and also append new members to it.

That's done by implementing theTyped,Titled, and/orDetailed 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 theRFC 7807:

<?phpdeclare(strict_types=1);namespaceMy\Fancy\App\UserManagement;useLcobucci\ErrorHandling\Problem\Forbidden;useLcobucci\ErrorHandling\Problem\Typed;useLcobucci\ErrorHandling\Problem\Titled;useLcobucci\ErrorHandling\Problem\Detailed;useRuntimeException;usefunctionsprintf;finalclass InsufficientCreditextends RuntimeExceptionimplements Forbidden, Typed, Titled, Detailed{private$currentBalance;publicstaticfunctionforPurchase(int$currentBalance,int$cost):self    {$exception =newself(sprintf('Your current balance is %d, but that costs %d.',$currentBalance,$cost));$exception->currentBalance =$currentBalance;return$exception;    }publicfunctiongetTypeUri():string    {return'https://example.com/probs/out-of-credit';    }publicfunctiongetTitle():string    {return'You do not have enough credit.';    }/** @inheritDoc */publicfunctiongetExtraDetails():array    {return ['balance' =>$this->currentBalance];// you might add "instance" and "accounts" too :)    }}

MIT, seeLICENSE.