Correlation Ids Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package — you cannot composer require it into a Laravel app (it depends on symfony/http-kernel and symfony/dependency-injection). The good news is that the framework-agnostic core, manomano-tech/correlation-ids, is a plain PHP class you can install and use directly:

composer require manomano-tech/correlation-ids

Start by reading the interface of CorrelationIds in the underlying package — it exposes a way to construct an instance from a string (or generate one when absent) and read the value back. That is the entire surface area you actually need.

Your first use case in Laravel is almost always: read X-Correlation-Id off the incoming request, synthesize one if missing, echo it back on the response, and make it available everywhere (logs, outbound HTTP, queued jobs). Look first at App\Http\Kernel::$middleware and app/Http/Middleware/ — that is where this bundle's Symfony KernelEventListener would translate to in Laravel.

Implementation Patterns

Request middleware. Create a CorrelationIdMiddleware that:

1. Reads X-Correlation-Id from the request (fall back to X-Request-Id if your gateway sends that).
2. Validates it (UUID or [A-Za-z0-9-]{8,64}), otherwise generates a new one.
3. Stores it via app()->instance(CorrelationIds::class, $ids) and/or Context::add('correlation_id', ...).
4. Calls $next($request) and adds the header to the response.

Log context. This is the highest-value pattern. Use Illuminate\Support\Facades\Log::withContext(['correlation_id' => $id]) (or a Monolog processor) so every log line carried the ID without touching call sites. This is exactly what the Symfony bundle's Monolog bridge would have done for you.

Outbound HTTP propagation. Add a Guzzle Middleware::mapRequest() that copies the ID onto every outgoing request — otherwise the correlation breaks the moment you call another service. Centralize this in a Http::globalRequestMiddleware() if you use Laravel's HTTP client.

Queued jobs. Serialize the ID into the job payload in a base job class (__sleep/__wakeup or the handle() bootstrap), because a CLI worker does not inherit the request's container state. This is the most commonly missed propagation path.

Symfony precedent to copy. The bundle's structure (a listener + a service definition + a Monolog processor) is a reasonable template even in Laravel — mirror the same three pieces as middleware + app()->instance + log processor.

Gotchas and Tips

• Archived since 2018 and zero-dependents. Do not assume it is maintained. The underlying library is small enough to vendor if needed; the Symfony bundle itself is effectively dead unless you are on Symfony 3/4.
• Do not blindly trust the incoming header. Client-supplied correlation IDs are an injection vector into your logs — validate the format and reject lengths that could break log parsers.
• Symfony vs Laravel translation. The bundle wires everything via services.yaml and kernel event priorities. In Laravel, middleware priority matters just as much: this must run before anything that logs (e.g. before TrimStrings, and definitely before exception handlers that log).
• Octane / long-running workers. A singleton binding will leak the ID from one request to the next. Use app()->scoped() (Octane-aware) or reset it in the terminate() phase.
• Case sensitivity. HTTP headers are case-insensitive but $request->header('X-Correlation-Id') only checks the exact key in Laravel — use $request->headers->get('X-Correlation-Id') which normalizes.
• Extension point worth stealing. The Symfony bundle exposes a generator interface. In Laravel, bind that interface so tests can inject a deterministic stub (e.g. test-request-id) instead of a random UUID — makes assertions much easier.