Request Id Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require chrisguitarguy/request-id-bundle
   

   Add the bundle to config/bundles.php (Symfony 4+):

   return [
       // ...
       Chrisguitarguy\RequestId\ChrisguitarguyRequestIdBundle::class => ['all' => true],
   ];
   

2. Verify Auto-Generation The bundle automatically generates a Request-Id if no header is provided. Test with:

   curl -v http://your-app.test
   

   Check the response headers for Request-Id.

3. First Use Case: Logging Access the request ID in a controller or service:

   use Chrisguitarguy\RequestId\RequestId;
   
   public function someAction(RequestId $requestId)
   {
       $this->logger->info('Processing request', ['request_id' => $requestId->getId()]);
   }
   

Implementation Patterns

Core Workflows

1. Request ID Injection Use dependency injection to access the request ID in any service:

   public function __construct(private RequestId $requestId) {}
   

2. Middleware Integration Extend the bundle’s functionality by creating a custom middleware:

   public function handle(Request $request, Closure $next)
   {
       $requestId = $request->headers->get('Request-Id');
       // Custom logic (e.g., validate, transform)
       return $next($request);
   }
   

3. Logging and Monitoring Attach the request ID to logs (Monolog) or APM tools (e.g., New Relic):

   $processor = new RequestIdProcessor($requestId);
   $logger->pushHandler(new StreamHandler('app.log', LogLevel::DEBUG), $processor);
   

4. User-Facing Debugging Display the request ID in error pages or user notifications:

   {% if app.requestId %}
       <div class="debug-info">Request ID: {{ app.requestId }}</div>
   {% endif %}
   

Integration Tips

• Symfony Flex: If using Symfony 4+, the bundle auto-configures via config/packages/chrisguitarguy_request_id.yaml.
• APIs: Use the Request-Id header for traceability across microservices.
• Testing: Mock the RequestId service in PHPUnit:

  $this->requestId = $this->createMock(RequestId::class);
  $this->requestId->method('getId')->willReturn('TEST-123');
  

Gotchas and Tips

Pitfalls

1. Header Trust Misconfiguration

   • If trust_request_header: false, the bundle ignores incoming Request-Id headers.
   • Fix: Set true in config if you want clients to provide IDs (e.g., for distributed tracing).

2. Header Name Conflicts

   • Customize request_header or response_header if they clash with existing headers (e.g., X-Request-ID).

3. Thread Safety

   • The request ID is scoped to the current request. Avoid storing it in static/global contexts.

4. Symfony 5+ Kernel Changes

   • For Symfony 5.3+, ensure the bundle is listed in config/bundles.php (not AppKernel).

Debugging

• Missing Request ID? Check if the bundle is enabled and no middleware is stripping headers.

  php bin/console debug:container chrisguitarguy_request_id.request_id
  

• Header Not Propagated Verify the response_header is correctly set in config and not overridden by other middleware.

Extension Points

1. Custom ID Generation Override the default UUID generator by binding a custom service:

   # config/services.yaml
   Chrisguitarguy\RequestId\RequestIdGenerator: '@app.custom_request_id_generator'
   

2. Event Listeners Subscribe to kernel.request or kernel.response events to modify behavior:

   public static function getSubscribedEvents()
   {
       return [
           KernelEvents::REQUEST => ['onRequest', 10],
       ];
   }
   

3. Database Storage Add the request ID to database logs or audit tables:

   $entity->setRequestId($requestId->getId());
   $entityManager->persist($entity);
   

Pro Tips

• Distributed Tracing: Combine with tools like OpenTelemetry to propagate the Request-Id across services.
• Security: Sanitize user-provided IDs if trust_request_header is enabled (e.g., reject non-alphanumeric IDs).
• Performance: The bundle adds minimal overhead (~1ms for UUID generation). Benchmark if critical.