PHPackages                             skedli/http-middleware - 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. skedli/http-middleware

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

skedli/http-middleware
======================

PSR-15 middleware components for correlation ID propagation, structured logging, error handling, JWT authentication, and idempotency.

2.0.0(1mo ago)1234↓90.5%[1 PRs](https://github.com/skedli/http-middleware/pulls)MITPHPPHP ^8.5CI passing

Since Feb 22Pushed 1w agoCompare

[ Source](https://github.com/skedli/http-middleware)[ Packagist](https://packagist.org/packages/skedli/http-middleware)[ Docs](https://github.com/skedli/http-middleware)[ RSS](/packages/skedli-http-middleware/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (68)Versions (19)Used By (0)

HTTP Middleware
===============

[](#http-middleware)

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

- [Overview](#overview)
- [Installation](#installation)
- [How to use](#how-to-use)
    - [Correlation ID](#correlation-id)
        - [Default usage](#default-usage)
        - [Reusing an existing correlation ID](#reusing-an-existing-correlation-id)
        - [Custom provider](#custom-provider)
        - [Using the correlation ID in your own logs](#using-the-correlation-id-in-your-own-logs)
    - [Request and response logging](#request-and-response-logging)
        - [Default usage](#default-usage-1)
        - [What is logged](#what-is-logged)
        - [Automatic correlation ID binding](#automatic-correlation-id-binding)
    - [Error handling](#error-handling)
        - [Default usage](#default-usage-2)
        - [Exception mapping](#exception-mapping)
        - [Error handling settings](#error-handling-settings)
        - [Logging errors](#logging-errors)
        - [Declarative mapping table](#declarative-mapping-table)
        - [Per-group usage](#per-group-usage)
    - [Authentication](#authentication)
        - [Default usage](#default-usage-3)
        - [Using a JWKS endpoint](#using-a-jwks-endpoint)
        - [Supported algorithms](#supported-algorithms)
        - [Accessing the authenticated user](#accessing-the-authenticated-user)
        - [Custom token decoder](#custom-token-decoder)
        - [Custom authenticated user](#custom-authenticated-user)
        - [Builder precedence](#builder-precedence)
        - [Authorization](#authorization)
    - [Health check](#health-check)
        - [Liveness](#liveness)
        - [Readiness](#readiness)
            - [Default usage](#default-usage-4)
            - [Custom health checks](#custom-health-checks)
            - [Doctrine health check](#doctrine-health-check)
            - [Non-critical checks](#non-critical-checks)
            - [Multiple instances of the same component](#multiple-instances-of-the-same-component)
            - [Degraded readiness](#degraded-readiness)
            - [Drain-aware readiness](#drain-aware-readiness)
            - [Response format](#response-format)
    - [Idempotency](#idempotency)
        - [Default usage](#default-usage-5)
        - [Storing responses with Doctrine DBAL](#storing-responses-with-doctrine-dbal)
        - [Custom scope provider](#custom-scope-provider)
        - [Builder options](#builder-options)
        - [Custom store](#custom-store)
        - [Race-condition guarantees](#race-condition-guarantees)
        - [Conflict response](#conflict-response)
- [License](#license)

Overview
--------

[](#overview)

Provides PSR-15 middleware for HTTP requests, including correlation ID propagation, structured request/response logging, error handling, stateless JWT authentication, extensible health check support, and idempotency enforcement.

Built on top of [PSR-15](https://www.php-fig.org/psr/psr-15) and [PSR-7](https://www.php-fig.org/psr/psr-7), the middleware can be used with any framework that supports the `MiddlewareInterface` and `RequestHandlerInterface`standards.

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

[](#installation)

```
composer require skedli/http-middleware
```

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

[](#how-to-use)

### Correlation ID

[](#correlation-id)

The middleware reads the `Correlation-Id` header from the incoming request. If present and non-empty, it reuses the value. Otherwise, it generates a new UUID v4. In both cases, the correlation ID is:

- Injected as a request attribute (`correlationId`) for downstream handlers.
- Added to the response as the `Correlation-Id` header.

#### Default usage

[](#default-usage)

Create the middleware with `CorrelationIdMiddleware::create()` and register it in your application. The default provider generates a UUID v4 when no `Correlation-Id` header is present.

```