PHPackages                             philiprehberger/laravel-correlation-id - 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. [Logging & Monitoring](/categories/logging)
4. /
5. philiprehberger/laravel-correlation-id

ActiveLibrary[Logging & Monitoring](/categories/logging)

philiprehberger/laravel-correlation-id
======================================

Laravel middleware that generates or propagates correlation IDs for request tracing with automatic log context injection

v1.3.0(3w ago)2242MITPHPPHP ^8.2CI passing

Since Mar 6Pushed 3w agoCompare

[ Source](https://github.com/philiprehberger/laravel-correlation-id)[ Packagist](https://packagist.org/packages/philiprehberger/laravel-correlation-id)[ Docs](https://github.com/philiprehberger/laravel-correlation-id)[ GitHub Sponsors](https://github.com/philiprehberger)[ RSS](/packages/philiprehberger-laravel-correlation-id/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (23)Versions (10)Used By (0)

Laravel Correlation ID
======================

[](#laravel-correlation-id)

[![Tests](https://github.com/philiprehberger/laravel-correlation-id/actions/workflows/tests.yml/badge.svg)](https://github.com/philiprehberger/laravel-correlation-id/actions/workflows/tests.yml)[![Latest Version on Packagist](https://camo.githubusercontent.com/ad785233989807580b4f48b791caac0e830c8c76c44e41a37cf2a8091529e60e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7068696c69707265686265726765722f6c61726176656c2d636f7272656c6174696f6e2d69642e737667)](https://packagist.org/packages/philiprehberger/laravel-correlation-id)[![Last updated](https://camo.githubusercontent.com/dcbb5ad99a3a133efbf0e3cdb0ff89d36caa0e531c53c3ef651bb58acc6543cc/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6173742d636f6d6d69742f7068696c69707265686265726765722f6c61726176656c2d636f7272656c6174696f6e2d6964)](https://github.com/philiprehberger/laravel-correlation-id/commits/main)

Laravel middleware that generates or propagates correlation IDs for request tracing with automatic log context injection.

Requirements
------------

[](#requirements)

- PHP 8.2+
- Laravel 11 or 12

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

[](#installation)

```
composer require philiprehberger/laravel-correlation-id
```

The service provider is registered automatically via Laravel package auto-discovery.

Optionally publish the config:

```
php artisan vendor:publish --tag=correlation-id-config
```

Usage
-----

[](#usage)

```
use PhilipRehberger\CorrelationId\AddCorrelationId;

// Register the middleware in bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->prepend(AddCorrelationId::class);
})
```

### Accessing the Correlation ID

[](#accessing-the-correlation-id)

```
use PhilipRehberger\CorrelationId\CorrelationId;

// Via the helper class
$id = CorrelationId::get();
CorrelationId::set('my-custom-id');

// Via the request macro
$id = $request->correlationId();
```

### Configuration

[](#configuration)

```
// config/correlation-id.php
return [
    'request_headers' => ['X-Request-Id', 'X-Correlation-ID'],
    'response_header' => 'X-Request-Id',
    'log_context_key' => 'correlation_id',
    'sentry'          => true,
    'generator'       => 'uuid',
    'max_length'      => 255,
    'validation_pattern' => '/^[\x21-\x7e]+$/',
];
```

### How It Works

[](#how-it-works)

1. The middleware inspects incoming request headers in the order defined by `request_headers`.
2. The first non-empty value found is used as-is (propagation path).
3. When no matching header is present, a new ID is generated using the configured generator.
4. The ID is stored as a request attribute and shared with the log context.
5. After the handler returns, the ID is written to the response header defined by `response_header`.

### Validating Incoming IDs

[](#validating-incoming-ids)

Incoming correlation IDs from request headers are validated before they are trusted. A value that is too long or contains disallowed characters (newlines, control characters, spaces) is discarded and a fresh ID is generated instead — so an untrusted client cannot inject arbitrary content into your logs, responses, or downstream requests.

```
// config/correlation-id.php

// Reject incoming IDs longer than this. Set to null to disable.
'max_length' => 255,

// Incoming IDs must fully match this pattern. The default accepts any
// printable, non-space ASCII (UUID, ULID, nanoid, hex, base64url). Set to
// null to disable pattern validation.
'validation_pattern' => '/^[\x21-\x7e]+$/',
```

You can reuse the same rule in application code:

```
use PhilipRehberger\CorrelationId\CorrelationId;

CorrelationId::isValid('3f2504e0-4f89-41d3-9a0c-0305e82c3301'); // true
CorrelationId::isValid("bad\r\nvalue");                          // false
```

### Custom ID Generator

[](#custom-id-generator)

Control how new correlation IDs are generated when no upstream header is present:

```
// config/correlation-id.php

// UUID v4 (default)
'generator' => 'uuid',

// UUID v7 (time-ordered, sortable)
'generator' => 'uuid7',

// ULID (compact, sortable)
'generator' => 'ulid',

// Custom callable
'generator' => fn () => 'prefix-' . bin2hex(random_bytes(16)),
```

### Queue Job Propagation

[](#queue-job-propagation)

Propagate the correlation ID from the dispatching context into queued jobs:

```
use PhilipRehberger\CorrelationId\Concerns\TracksCorrelationId;
use PhilipRehberger\CorrelationId\Middleware\CorrelationIdJobMiddleware;

class ProcessOrder implements ShouldQueue
{
    use TracksCorrelationId;

    public function middleware(): array
    {
        return [new CorrelationIdJobMiddleware];
    }

    public function handle(): void
    {
        // CorrelationId::get() returns the same ID from dispatch time
    }
}
```

The `TracksCorrelationId` trait captures the current correlation ID when the job is created. The `CorrelationIdJobMiddleware` restores it when the job runs on a worker.

### HTTP Client Propagation

[](#http-client-propagation)

Automatically forward the correlation ID to outgoing HTTP requests made with Laravel's HTTP client:

```
use Illuminate\Support\Facades\Http;
use PhilipRehberger\CorrelationId\CorrelationId;

$response = Http::withMiddleware(CorrelationId::httpMiddleware())
    ->get('https://api.example.com/orders');

// Uses a custom header name
$response = Http::withMiddleware(CorrelationId::httpMiddleware('X-Request-Id'))
    ->get('https://api.example.com/orders');
```

The middleware adds the `X-Correlation-ID` header (or your custom header) to every outgoing request.

### Trace Spans

[](#trace-spans)

Track the timing of operations within a request using lightweight trace spans:

```
use PhilipRehberger\CorrelationId\CorrelationId;

$span = CorrelationId::startSpan('external-api-call', ['url' => $url]);

$response = Http::get($url);

$ended = CorrelationId::endSpan($span);

// Access span data
$ended->durationMs();  // Duration in milliseconds
$ended->toArray();     // Full array representation

// Retrieve all completed spans
$spans = CorrelationId::spans();

// Clear spans (e.g., between tests)
CorrelationId::clearSpans();
```

Spans are immutable value objects. Calling `endSpan()` returns a new instance with the end time set and stores it for later retrieval.

### Sentry Integration

[](#sentry-integration)

When `sentry/sentry-laravel` is installed and `'sentry' => true`, the middleware sets `correlation_id` as a tag on every Sentry event captured during the request.

API
---

[](#api)

Class / MethodDescription`AddCorrelationId` middlewareGenerates or propagates the correlation ID and injects it into logs and responses`CorrelationId::get()`Read the current correlation ID (`null` if not yet set)`CorrelationId::set(string $id)`Override the correlation ID (useful in tests or CLI commands)`CorrelationId::generate()`Generate a new correlation ID using the configured generator`CorrelationId::isValid(string $id)`Check a candidate ID against the configured length and pattern rules`CorrelationId::reset()`Clear the correlation ID and all trace spans for the current request`CorrelationId::httpMiddleware(?string $headerName)`Returns a Guzzle middleware closure for HTTP client propagation`CorrelationId::startSpan(string $name, array $metadata)`Start a new trace span linked to the current correlation ID`CorrelationId::endSpan(Span $span)`End a span and store it for retrieval`CorrelationId::spans()`Get all completed trace spans`CorrelationId::clearSpans()`Clear all stored trace spans`$request->correlationId()`Request macro that returns the current correlation ID`TracksCorrelationId` traitCaptures the correlation ID at dispatch time for queue jobs`CorrelationIdJobMiddleware`Queue job middleware that restores the correlation ID`PropagateCorrelationId::handler()`Static factory for the HTTP client propagation middleware`Span` value objectImmutable span with `name`, `durationMs()`, `toArray()`Development
-----------

[](#development)

```
composer install
vendor/bin/phpunit
vendor/bin/pint --test
vendor/bin/phpstan analyse
```

Support
-------

[](#support)

If you find this project useful:

⭐ [Star the repo](https://github.com/philiprehberger/laravel-correlation-id)

🐛 [Report issues](https://github.com/philiprehberger/laravel-correlation-id/issues?q=is%3Aissue+is%3Aopen+label%3Abug)

💡 [Suggest features](https://github.com/philiprehberger/laravel-correlation-id/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)

❤️ [Sponsor development](https://github.com/sponsors/philiprehberger)

🌐 [All Open Source Projects](https://philiprehberger.com/open-source-packages)

💻 [GitHub Profile](https://github.com/philiprehberger)

🔗 [LinkedIn Profile](https://www.linkedin.com/in/philiprehberger)

License
-------

[](#license)

[MIT](LICENSE)

###  Health Score

46

—

FairBetter than 92% of packages

Maintenance94

Actively maintained with recent releases

Popularity18

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 91.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~16 days

Recently: every ~30 days

Total

9

Last Release

26d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/cfd7d24cbbf32400fa13ce0bbe7a31edd2d66a6d4488eafdb3d64c5337bf0435?d=identicon)[philiprehberger](/maintainers/philiprehberger)

---

Top Contributors

[![philiprehberger](https://avatars.githubusercontent.com/u/8218077?v=4)](https://github.com/philiprehberger "philiprehberger (21 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (2 commits)")

---

Tags

middlewarelaravelloggingtracingcorrelation-idrequest id

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/philiprehberger-laravel-correlation-id/health.svg)

```
[![Health](https://phpackages.com/badges/philiprehberger-laravel-correlation-id/health.svg)](https://phpackages.com/packages/philiprehberger-laravel-correlation-id)
```

###  Alternatives

[laravel/cashier

Laravel Cashier provides an expressive, fluent interface to Stripe's subscription billing services.

2.6k31.8M158](/packages/laravel-cashier)[psalm/plugin-laravel

Psalm plugin for Laravel

3345.4M354](/packages/psalm-plugin-laravel)[api-platform/laravel

API Platform support for Laravel

58190.1k21](/packages/api-platform-laravel)[forjedio/inertia-table

Backend-driven dynamic tables for Laravel + Inertia.js

272.0k](/packages/forjedio-inertia-table)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)