PHPackages                             tiny-blocks/http-middleware-error - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. tiny-blocks/http-middleware-error

ActiveLibrary[HTTP & Networking](/categories/http)

tiny-blocks/http-middleware-error
=================================

PSR-15 middleware that maps thrown exceptions to structured JSON error responses with optional logging.

1.0.0(today)00MITPHPPHP ^8.5CI passing

Since Jun 26Pushed todayCompare

[ Source](https://github.com/tiny-blocks/http-middleware-error)[ Packagist](https://packagist.org/packages/tiny-blocks/http-middleware-error)[ Docs](https://github.com/tiny-blocks/http-middleware-error)[ RSS](/packages/tiny-blocks-http-middleware-error/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (12)Versions (2)Used By (0)

Http Middleware Error
=====================

[](#http-middleware-error)

[![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](https://github.com/tiny-blocks/http-middleware-error/blob/main/LICENSE)

- [Overview](#overview)
- [Installation](#installation)
- [How to use](#how-to-use)
    - [Declaring a mapping](#declaring-a-mapping)
    - [Composing multiple mappings](#composing-multiple-mappings)
    - [Resolving the response from the exception](#resolving-the-response-from-the-exception)
    - [Logging and displaying error details](#logging-and-displaying-error-details)
    - [Disabling the fallback for unmapped exceptions](#disabling-the-fallback-for-unmapped-exceptions)
- [License](#license)
- [Contributing](#contributing)

Overview
--------

[](#overview)

Provides a PSR-15 middleware that captures exceptions thrown by downstream handlers and translates them into structured JSON error responses. Each consumer declares an `ExceptionMapping`, a class whose `mappings()` method returns an `ExceptionMappingTable` that turns each known exception into a `MappedError` (machine-readable code, HTTP status between 400 and 599, human-readable message, optional headers). The consumer declares only the rules it owns, and the middleware composes the tables of every configured mapping into a single first-match-wins lookup, so neither the consumer nor the middleware repeats the composition. Unmapped exceptions either short-circuit to a generic 500 fallback or rethrow, depending on the builder configuration.

The library integrates with [tiny-blocks/http-middleware-correlation-id](https://github.com/tiny-blocks/http-middleware-correlation-id)to enrich every log entry with the request's correlation identifier when one is present on the request attributes, so error logs can be grouped across services without any extra plumbing in the consumer's log calls.

Installation
------------

[](#installation)

```
composer require tiny-blocks/http-middleware-error
```

How to use
----------

[](#how-to-use)

### Declaring a mapping

[](#declaring-a-mapping)

A consumer declares the rules it owns by implementing `ExceptionMapping`. The `mappings()` method returns an `ExceptionMappingTable` built once, so the same table is reused on every request rather than rebuilt per exception. Rules are evaluated in registration order, and the first match wins. Exact-class, listed-class, and subclass matches cover the common cases.

```