Request Id Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package. sbsedv/request-id-bundle ships a Bundle class and Symfony DI config; it has no service provider, no auto-discovery, and no Laravel-facing config. If you're working in a Laravel codebase, read this assessment as a pattern reference (request-ID middleware + log correlation) rather than something you composer require into an app.

Install and wire up (Symfony context):

composer require sbsedv/request-id-bundle

• Register Sbsedv\RequestIdBundle\RequestIdBundle in config/bundles.php.
• Look first at the bundle's config tree (config/packages/sbsedv_request_id.yaml) and the RequestIdStorage service — that's the public surface you'll interact with day to day.
• First use case: accept or generate an ID on the inbound request, store it, and return it on the response so it can be correlated across logs, queues, and downstream services.

v1.9.0 is a single change: Symfony 8 support. There are no new features, deprecations, or BC breaks in the changelog. Practical implication:

• On Symfony 6/7: stay on ^1.8 unless you want the widened constraint; nothing to gain.
• On Symfony 8: you need ^1.9.0 — earlier releases block the install.
• Nothing here changes how you use the package beyond the framework constraint.

Implementation Patterns

Baseline request correlation. The bundle's kernel-level listener reads the incoming header (default X-Request-ID, case-insensitive per HTTP spec) or generates one when absent, then exposes it via RequestIdStorage. Inject that service wherever you need the ID — do not read $request->headers in scattered places.

Log correlation. Register a Monolog processor that pulls from RequestIdStorage and merges request_id into every record. This is the highest-value pattern: one ID in the response header lets a user paste a value into your log search and get the full trace. Do the same for your exception reporter (Sentry/Bugsnag tag).

Outbound propagation. Add a middleware/decorator on your HTTP client (Symfony HttpClient or Guzzle) that injects the current ID into outgoing calls. Without this, correlation breaks at the first service hop. Skip it for calls to third parties you don't control — sending your internal trace ID outward is usually harmless but is unnecessary noise.

Custom generation. If you need ULIDs, UUIDv7, or a prefixed ID (req_01H...), implement the bundle's ID-generator interface and register it as the generator service instead of post-processing the header. Prefixes make log grepping much easier.

Long-running processes. For Messenger consumers and CLI commands, decide explicitly: reuse a per-message ID from the envelope, or mint a fresh one per message. Never let a worker inherit the ID from the previous message. Reset/repopulate the storage at the start of each handled item.

Testing. Assert the response header in a functional test and assert the ID equals whatever you injected via the request header — this catches config drift after header-name changes.

Gotchas and Tips

• Header spoofing is the main risk. An untrusted client can send arbitrary X-Request-ID values and poison your logs (log injection, forged correlation, or oversized/unbounded strings). Either disable inbound trust, or validate against a strict regex and cap the length before storing. Only trust the header when the request came through a proxy you control.
• Symfony 8 upgrade friction is transitive, not local. composer why-not symfony/framework-bundle 8.0 will tell you which of your other bundles is holding you back. The request-id bundle is rarely the blocker; it's just the one that got out of the way first.
• composer.lock churn. Because the only diff is a widened symfony/* constraint, a composer update sbsedv/request-id-bundle on a Symfony 6/7 app can silently pull newer transitive Symfony constraints if your own are loose. Pin your Symfony version intentionally.
• Middleware ordering. If your log processor is registered before the request-ID listener runs, or your logger is used during container boot, you'll get null IDs. Ensure the ID is set as early as possible in the kernel-request phase.
• Buffered/async log handlers resolve the processor at flush time, not at log-call time. With buffered handlers in long-running workers, a stale ID from a prior request can be stamped onto delayed records — another reason to reset per item.
• Header normalization (X-Request-Id vs X-Request-ID) is cosmetic in HTTP/2 but not in naive proxy regexes or when you copy the value into a second system. Keep one canonical name in config and document it.
• Extension points to prefer over forking: custom ID generator, configurable header name, and the storage service. Almost every "I need the ID somewhere else" request is solved by injecting RequestIdStorage, not by patching the listener.
• Laravel equivalent, if that's your actual target: a global middleware that reads X-Request-ID (validated), stores it on the request, writes it back on the response, and a Monolog tap/processor adding request_id to context — plus Context::add() for queued jobs. Roughly 30 lines; you don't need this bundle, but the design here is a good reference for it.