Weave Code
Laravel Middleware Request Id Laravel Package
softonic/laravel-middleware-request-id
Laravel middleware that assigns a unique request ID to every incoming request and response header, making it easy to trace requests through logs and distributed systems. Simple setup, configurable header name, and seamless Laravel integration.
At a glance
Frequently asked questions about Laravel Middleware Request Id
- How do I install softonic/laravel-middleware-request-id?
- Install it with Composer by running composer require softonic/laravel-middleware-request-id and pin at least version 3.0.1. There are no database, queue, cache, or external service dependencies, so no migrations or extra infrastructure are required. After installing you register the middleware in your HTTP stack, and optionally publish its configuration file if you need to customise the header name. The whole setup is measured in minutes rather than hours.
- How do I register this middleware in Laravel 11 or 12?
- In Laravel 11 and 12 you register it in bootstrap/app.php using the withMiddleware() closure, appending it to the global middleware stack. Place it ahead of your application middleware but behind any trusted-proxy handling so the request context is already resolved when the ID is generated. It is a thin single-responsibility middleware, so it does not touch routing, container bindings, or service providers. You can also attach it to a specific route group if you only want request IDs on certain endpoints.
- Which Laravel versions does this request ID middleware support?
- Version 3.x targets Laravel 12 and Symfony 7, and it is backwards-compatible in spirit with Laravel 10 and 11 as long as the Symfony HttpFoundation Response contract holds. Because correctness is now tied to Symfony's Response interface rather than Laravel's, Symfony major releases are the upgrade signal to watch. If you are still on Laravel 10 or 11, check the package constraints and run your test suite before rolling it out.
- Why does version 3.0.0 throw a TypeError when a controller returns a JsonResponse?
- Version 3.0.0 narrowed the handle() return type hint to Illuminate\Http\Response, but Laravel pipelines legitimately return JsonResponse, RedirectResponse, StreamedResponse, and binary responses. The 3.0.1 patch widened the hint to Symfony\Component\HttpFoundation\Response and relies on covariance, which is the correct architectural fix. Any 3.0.0 pin is a latent runtime TypeError on JSON APIs, which are exactly the endpoints most likely to want request IDs. Pin >=3.0.1 and treat 3.0.0 as unusable.
- Can I change the request ID header name?
- Yes, the header name is configurable, so you can align it with whatever your gateway, load balancer, or logging pipeline already uses. Publish the package configuration and set the header to something like X-Request-Id, X-Correlation-Id, or your organisation's internal convention. Keeping the same name across services matters most, because a renamed header on one hop silently breaks trace continuity. Decide the name once and document it for every service in the chain.
- Does it reuse an inbound X-Request-Id or always generate a new one?
- The package generates or propagates a correlation identifier, but you should verify the exact precedence behaviour against the version you install before trusting it in production. The trust boundary matters here: blindly reusing a client-supplied header lets callers forge trace IDs, while always overwriting an inbound gateway ID breaks continuity across hops. Many teams adopt the pattern of trusting the header only from a known proxy and generating otherwise. Write a test that covers both cases so the behaviour is pinned in your codebase, not just in the package.
- How do I access the request ID in my application logs?
- The middleware injects the ID into the response header, and you will typically want it in application code as well so log lines can carry it. A common approach is a small companion middleware or listener that reads the same header or request attribute and pushes it into Log::withContext(), which Laravel then includes on every log record for that request. Confirm whether your installed version exposes the ID beyond the response header before assuming a helper is available. Without this step you get an ID in the response but no way to correlate it with the log lines that explain the failure.
- How do I propagate the request ID to outbound HTTP calls?
- The middleware only covers the inbound request and the response header, so outbound propagation is your responsibility. Add a small HTTP client middleware or a Guzzle handler that reads the current request ID and sets the same header on every outgoing request. Without it, downstream services generate their own IDs and your traces stop at the first service boundary, which is exactly the gap the package is meant to close. This is the single most common way a request-ID setup is deployed incorrectly.
- How should I test this middleware in a Laravel application?
- Write feature tests that hit a route returning a plain Response, a JsonResponse, a RedirectResponse, and ideally a streamed or binary response, then assert the ID header is present on each. The JsonResponse case is precisely what the 3.0.0 to 3.0.1 patch fixes, so it deserves an explicit assertion to prevent regressions. Also test the inbound case: send a request with the configured header already set and assert your intended reuse-or-regenerate behaviour. These tests are cheap and catch the silent failures that otherwise only show up during incident forensics.
- Is this package production-ready, and what are the maintenance risks?
- The code itself is a small, auditable single-responsibility utility with no data-plane dependency, which keeps evaluation and operational cost low. The caveats are governance and version currency: no maintainer cadence, test coverage, download volume, or security advisory history was supplied, and it appears to be a single-maintainer package. Pin >=3.0.1, watch Symfony major releases rather than Laravel ones, and review the diff on every upgrade. If that supply-chain exposure is unacceptable, a hand-rolled middleware is roughly thirty lines of code.
Weaver
How can I help you explore Laravel packages today?