Download the PHP package meritum/http-exception-handler without Composer

meritum/http-exception-handler

HTTP exception handler that translates exceptions into structured JSON error responses using the meritum/structured-logging pipeline.

Requirements

• PHP 8.4+
• georgeff/kernel ^1.6
• meritum/http ^1.0
• meritum/structured-logging ^1.0

Installation

Usage

Module registration

Register ExceptionHandlerModule alongside StructuredLoggingModule. StructuredLoggingModule requires a LoggerInterface to already be registered:

ExceptionHandlerModule registers:

• ExceptionHandlerInterface — the handler meritum/http resolves when an exception reaches the kernel boundary
• HttpExceptionTranslationHandler — tagged as exception.translator.handlers, translates HttpExceptionInterface instances into structured domain exceptions

How it works

When an exception reaches the HTTP kernel boundary:

1. ExceptionHandlerInterface::handle() is called with the exception and the current request
2. The exception is passed through the meritum/structured-logging translate→report pipeline — it is translated to a domain exception and logged
3. An ErrorEnvelope is built from the domain exception and returned as a JSON response

HTTP exceptions (implementing HttpExceptionInterface) are translated by HttpExceptionTranslationHandler into an HttpDomainException, which carries the request context and sets the appropriate log severity. Any other exception falls through to the structured-logging catch-all translator and produces a generic 500 response.

Response format

All error responses use a consistent JSON envelope:

• code — the domain exception error code; HTTP_ followed by the HTTP status code for HTTP exceptions
• status — the HTTP status code as an integer; also set as the response status
• title — the HTTP exception title; "Unexpected Error" for non-HTTP exceptions
• detail — the exception message; may be null
• errors — an optional array of additional error detail objects; omitted when empty

Custom HTTP exceptions

Extend HttpException or implement HttpExceptionInterface directly to define domain-specific HTTP exceptions:

Throw the exception from within the request pipeline:

HttpExceptionTranslationHandler matches any HttpExceptionInterface, so custom exceptions are handled automatically with no additional registration.

Custom translation handlers

To produce a different domain exception for a specific HTTP exception type, implement TranslationHandler and register it at a higher priority than the default handler (0):

Register and tag it in your module:

Because this handler runs at priority 1, it matches before HttpExceptionTranslationHandler (0) for ValidationHttpException instances. All other HTTP exceptions continue to be handled by the default.

Using ErrorEnvelope directly

ErrorEnvelope is public API. Use it to build consistent error responses anywhere in your application:

Attaching additional errors

Call withErrors() to attach a list of error detail objects to the envelope. The shape of each entry is up to the caller — withErrors() carries any string-keyed map:

This produces:

errors is omitted from the response entirely when withErrors() is not called. withErrors() replaces any previously set errors — pass the full list in a single call.

License

MIT