Download the PHP package letkode/http-exception-bundle without Composer

letkode/http-exception-bundle

HTTP status exceptions and a JSON exception listener for Symfony applications.

Installation

Symfony Flex registers the bundle automatically. Otherwise:

Requires a configured Symfony translator and a PSR-3 logger. Install symfony/validator to get per-field errors on 422 responses.

Configuration

All options are optional; defaults are shown.

path_prefix is matched as a plain string prefix, so /api also matches /apiary. An empty string ('') makes the listener handle every path.

Debug traces follow %kernel.debug%; there is nothing to configure.

Using your own exception listener

To handle exceptions with your own listener, turn the bundle's off:

The exceptions, the contracts, TranslationOption and the locale resolver stay available; only the kernel.exception listener is not registered. Your listener can keep relying on HttpStatusExceptionInterface (getStatusCode(), getErrorCode(), getOption()).

Usage

Throw an exception from any service; the listener turns it into JSON.

Every exception has a default errorCode (for example BAD_REQUEST), overridable through the second constructor argument.

Exceptions

Server errors (5xx) are logged as critical.

Translated messages

Pass a TranslationOption to translate the message (which then acts as a translation key):

Without a TranslationOption the message is returned as is.

Extending the exceptions

The exceptions are not final. Create a subclass for a domain case and override defaultErrorCode() to give it its own code:

Anything that catches EntityNotFoundException (or renders it) also handles the subclass. Your own exception class can also extend AbstractHttpStatusException (implement getStatusCode() and defaultErrorCode()) or implement HttpStatusExceptionInterface.

Errors by field

Attach an ErrorsOption to include an errors object in the response, keyed by field. Each message is a string or a Symfony TranslatableInterface, which is translated with the request locale:

Without the option the response has no errors key.

Other exceptions

Translations

The bundle ships exceptions.en.yaml and exceptions.es.yaml (keys http.<status>, http.default, validation.failed). Override any key by defining it in your application's translations/exceptions.<locale>.yaml.

Locale

Messages are translated with the locale of the current request. To change that, implement Letkode\HttpExceptionBundle\Contract\LocaleResolverInterface and alias it in your services.yaml:

License

MIT