Stack Request Id Laravel Package

Getting Started

Minimal Setup in Laravel

1. Installation

   composer require qandidate/stack-request-id
   

   Note: While the package is Symfony-focused, Laravel can leverage it via middleware adaptation.

2. First Use Case: Request ID Middleware Create a custom Laravel middleware to wrap the Symfony RequestId logic:

   // app/Http/Middleware/RequestIdMiddleware.php
   namespace App\Http\Middleware;
   
   use Closure;
   use Qandidate\Stack\RequestId;
   use Qandidate\Stack\UuidRequestIdGenerator;
   use Symfony\Component\HttpFoundation\Request;
   
   class RequestIdMiddleware
   {
       public function handle($request, Closure $next)
       {
           $kernel = new \App\Http\Kernel(); // Laravel's kernel
           $generator = new UuidRequestIdGenerator(1337);
           $stack = new RequestId($kernel, $generator);
   
           // Override the request with the modified one
           $modifiedRequest = $stack->handle(Request::createFromGlobals());
           $request->headers->set('X-Request-ID', $modifiedRequest->headers->get('X-Request-ID'));
   
           return $next($request);
       }
   }
   

   Register it in app/Http/Kernel.php:

   protected $middleware = [
       \App\Http\Middleware\RequestIdMiddleware::class,
   ];
   

3. Verify Request ID Access the ID via:

   $requestId = request()->headers->get('X-Request-ID');
   

Implementation Patterns

Core Workflows

1. Request ID Generation

   • Use UuidRequestIdGenerator for UUIDs (default) or implement RequestIdGeneratorInterface for custom logic (e.g., sequential IDs).
   • Example custom generator:

     class CustomRequestIdGenerator implements RequestIdGeneratorInterface
     {
         public function generate(): string
         {
             return uniqid('CUST_', true);
         }
     }
     

2. Middleware Integration

   • Laravel: Wrap Symfony’s RequestId in a Laravel middleware (as above) to inject the header and modify the request object.
   • Symfony: Directly use the provided RequestId class in your kernel (as per README).

3. Logging Integration

   • Monolog: Add the MonologProcessor to prepend request IDs to logs:

     // config/logging.php
     'processors' => [
         \Qandidate\Stack\RequestId\MonologProcessor::class,
     ],
     

   • Laravel Log Channels: Extend the MonologProcessor to work with Laravel’s log channels:

     use Illuminate\Support\Facades\Log;
     use Monolog\Logger;
     
     class LaravelMonologProcessor
     {
         public function __invoke(array $record): array
         {
             $record['extra']['request_id'] = request()->header('X-Request-ID');
             return $record;
         }
     }
     

4. Database Tracing

   • Attach the request ID to database queries via Laravel’s query listeners or Eloquent observers:

     // app/Providers/AppServiceProvider.php
     public function boot()
     {
         \DB::listen(function ($query) {
             $query->bindValue(':request_id', request()->header('X-Request-ID'), 'string');
         });
     }
     

5. API Responses

   • Include the request ID in API responses for debugging:

     return response()->json([
         'data' => $data,
         'meta' => [
             'request_id' => request()->header('X-Request-ID'),
         ],
     ]);
     

Gotchas and Tips

Pitfalls

1. Symfony vs. Laravel Compatibility

   • The package is Symfony-centric. Laravel requires middleware adaptation (e.g., manual request object manipulation).
   • Fix: Use the middleware pattern above to bridge the gap.

2. Request ID Overrides

   • If the incoming request already has an X-Request-ID header, the middleware may overwrite it.
   • Fix: Skip generation if the header exists:

     if (!$request->headers->has('X-Request-ID')) {
         $modifiedRequest = $stack->handle(Request::createFromGlobals());
         $request->headers->set('X-Request-ID', $modifiedRequest->headers->get('X-Request-ID'));
     }
     

3. Thread Safety

   • UuidRequestIdGenerator uses a seed (e.g., 1337). In multi-threaded environments, this could lead to collisions.
   • Fix: Use random_int() or omit the seed:

     $generator = new UuidRequestIdGenerator(); // No seed = random UUIDs
     

4. Monolog Processor Timing

   • The MonologProcessor listens to kernel.request, which may not capture all log entries (e.g., those before the request is fully processed).
   • Fix: Use a global log processor (Laravel’s Monolog setup) or listen to monolog.record:

     // config/logging.php
     'processors' => [
         function ($record) {
             $record['extra']['request_id'] = request()->header('X-Request-ID') ?? 'N/A';
             return $record;
         },
     ],
     

Tips

1. Consistent Naming

   • Use X-Request-ID as the header name to align with industry standards (e.g., AWS X-Ray, Datadog).

2. Testing

   • Mock the middleware to test request ID propagation:

     $request = Request::create('/test', 'GET', [], [], [], ['HTTP_X_REQUEST_ID' => 'TEST_123']);
     $response = $this->app->handle($request);
     $this->assertEquals('TEST_123', $response->headers->get('X-Request-ID'));
     

3. Performance

   • UUID generation is lightweight. For high-throughput apps, consider a simpler ID (e.g., uniqid()).

4. Extending Functionality

   • Custom Headers: Modify the RequestId class to support additional headers (e.g., X-Request-Trace).
   • Storage: Store request IDs in a database for auditing:

     \DB::table('request_logs')->insert([
         'id' => request()->header('X-Request-ID'),
         'created_at' => now(),
     ]);
     

5. Debugging

   • Log missing request IDs to identify middleware bypasses:

     if (!$request->header('X-Request-ID')) {
         \Log::warning('Request ID missing for URL: ' . $request->url());
     }