tiny-blocks/http-middleware-correlation-id

PSR-15 middleware that ensures every request has a correlation identifier propagated through requests, responses, and logs.

1.0.1 2026-06-27 13:27 UTC

Requires

• php: ^8.5
• psr/http-message: ^2.0
• psr/http-server-handler: ^1.0
• psr/http-server-middleware: ^1.0
• psr/log: ^3.0
• ramsey/uuid: ^4.9

Requires (Dev)

• ergebnis/composer-normalize: ^2.52
• guzzlehttp/psr7: ^2.9
• infection/infection: ^0.33
• phpstan/phpstan: ^2.2
• phpunit/phpunit: ^13.1
• squizlabs/php_codesniffer: ^4.0

MIT

• Gustavo Freze de Araujo Santos

• logging
• http
• middleware
• correlation-id
• psr-15
• observability
• tiny-blocks

README

• Overview
• Installation
• How to use
  • Wiring the middleware
  • Configuring a custom provider
  • Emitting correlated logs
• License
• Contributing

Overview

Provides a PSR-15 middleware that guarantees every inbound HTTP request carries a correlation identifier. When the incoming request already includes a Correlation-Id header, the value is reused; otherwise a new identifier is generated through a configurable provider (UUID v4 by default). The correlation ID is exposed as the request attribute correlationId so downstream handlers can read it, and is echoed back through the Correlation-Id response header for end-to-end tracing across services.

The library also ships CorrelatedLogger, a thin wrapper over any PSR-3 LoggerInterface that resolves the correlation ID from the request and attaches it to the log context under the correlation_id key. This produces structured logs that can be grouped and filtered by the correlation ID without any extra plumbing in the consumer's log calls.

Installation

composer require tiny-blocks/http-middleware-correlation-id

How to use

Wiring the middleware

Builds the middleware with the default UUID v4 provider and processes a request through it.

<?php

declare(strict_types=1);

use GuzzleHttp\Psr7\Response;
use GuzzleHttp\Psr7\ServerRequest;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;
use TinyBlocks\HttpMiddlewareCorrelationId\CorrelationIdMiddleware;

# Build the middleware with the default UUID v4 provider.
$middleware = CorrelationIdMiddleware::create()->build();

# Process an inbound request through the middleware.
$response = $middleware->process(
    new ServerRequest('GET', '/orders'),
    new class () implements RequestHandlerInterface {
        public function handle(ServerRequestInterface $request): ResponseInterface
        {
            return new Response();
        }
    }
);

# The response carries the generated correlation ID on the Correlation-Id header.
$response->getHeaderLine('Correlation-Id');

Configuring a custom provider

Replaces the default UUID v4 provider with a custom strategy (for example, an externally supplied identifier).

<?php

declare(strict_types=1);

use TinyBlocks\HttpMiddlewareCorrelationId\CorrelationId;
use TinyBlocks\HttpMiddlewareCorrelationId\CorrelationIdMiddleware;
use TinyBlocks\HttpMiddlewareCorrelationId\CorrelationIdProvider;

# Custom provider that returns a fixed correlation ID.
$provider = new readonly class () implements CorrelationIdProvider {
    public function generate(): CorrelationId
    {
        return new readonly class () implements CorrelationId {
            public function toString(): string
            {
                return 'fixed-correlation-id';
            }
        };
    }
};

# Build the middleware with the custom provider.
$middleware = CorrelationIdMiddleware::create()
    ->withProvider(provider: $provider)
    ->build();

Emitting correlated logs

Uses CorrelatedLogger inside a downstream handler so that every log entry automatically carries the request's correlation ID under the correlation_id context key.

<?php

declare(strict_types=1);

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;
use Psr\Log\LoggerInterface;
use TinyBlocks\HttpMiddlewareCorrelationId\CorrelatedLogger;

final readonly class PlaceOrderHandler implements RequestHandlerInterface
{
    public function __construct(private LoggerInterface $logger)
    {
    }

    public function handle(ServerRequestInterface $request): ResponseInterface
    {
        # Resolve a PSR-3 logger that attaches the request's correlation ID to every log context.
        $logger = CorrelatedLogger::from($this->logger)->resolve($request);

        $logger->info('Order placed.', ['order_id' => 42]);

        # ...
    }
}

License

Http Middleware Correlation Id is licensed under MIT.

Contributing

Please follow the contributing guidelines to contribute to the project.