Getting Started

Install via Composer: composer require vendor/request-id (replace with actual package name).
Publish the config file (if provided): php artisan vendor:publish --tag=request-id-config.
Register the RequestId middleware. In Laravel 10/11, add it to the $middleware array in app/Http/Kernel.php. In Laravel 11/12, append it to the middleware section of bootstrap/app.php:
```
->withMiddleware(function (Middleware $middleware) {
    $middleware->append(\Vendor\RequestId\Middleware\RequestId::class);
})
```
First use case: automatically attach a unique request ID to every response header (e.g., X-Request-Id) and make it available for logging and downstream tracing.

Implementation Patterns

Global vs. route middleware – Apply globally for full request tracing, or only to API routes by registering it as a route middleware group.
Accessing the ID – The middleware typically stores the ID as a request attribute ($request->attributes->get('request_id')) or sets a header. Use $request->header('X-Request-Id') in controllers.
Logging integration – Add the request ID to every log entry using Laravel’s context:
```
Log::withContext(['request_id' => $request->attributes->get('request_id')]);
```
Place this in a service provider or a dedicated middleware that runs after RequestId.
Custom ID generation – Override the default UUID/ULID generator via config or by binding a custom callable in a service provider. Common patterns: use Str::uuid(), Str::ulid(), or accept an incoming X-Request-Id header from a trusted proxy.
Propagating to downstream services – Forward the request ID as a header when making HTTP calls with Http::withHeaders(['X-Request-Id' => $id]).

Testing – Assert the response header in feature tests:

$response = $this->get('/');
$response->assertHeader('X-Request-Id');

Laravel 12 return type fix (v3.0.1) – The handle() method now returns Symfony\Component\HttpFoundation\Response instead of Illuminate\Http\Response. This allows compatibility with all response types (JsonResponse, RedirectResponse, etc.). If you extend the middleware, ensure your overridden handle() method uses the same or a covariant return type.
Middleware ordering – If you rely on the request ID in other middleware (e.g., logging), register RequestId before them. In Laravel 11+ use $middleware->prepend() or adjust priority.
Config caching – After changing config, run php artisan config:cache in production. Avoid closures in config if you cache.
Header name consistency – The default header (X-Request-Id) may clash with proxies or load balancers. Customize it in config and ensure upstream services agree.
Uniqueness and length – UUIDs are 36 characters; ULIDs are 26. If you have strict header size limits, validate the generated ID length.
Debugging – If the header is missing, check middleware registration, route exclusions, and whether an exception bypassed the middleware. Use php artisan route:list -v to confirm middleware is applied.
Extension points – Many implementations allow overriding the ID generator via a container binding or a config callback. Use this to integrate with existing tracing systems (e.g., OpenTelemetry).