Request Id Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require avariya/request-id-bundle
   

2. Enable the bundle in config/bundles.php (Laravel 5.4+) or AppKernel.php (Symfony):

   Avariya\RequestIdBundle\AvariyaRequestIdBundle::class => ['all' => true],
   

3. Verify default behavior:
   • The bundle auto-generates a X-Request-Id header if none is provided.
   • Logs will include the request ID via Monolog (if enabled).

First Use Case: Debugging a Request

• Check logs: The request ID will appear in Monolog entries (if monolog_support: true).
• Inspect headers: Use Request::header('X-Request-Id') in controllers to correlate logs/DB entries.

Implementation Patterns

Core Workflow

1. Request Handling:

   • The KernelSubscriber injects a UUID if X-Request-Id is missing.
   • Store the ID in the Request object for later use:

     $requestId = request()->header('X-Request-Id');
     

2. Logging Integration:

   • Monolog listener appends the ID to log contexts:

     avariya_request_id:
         monolog_support: true
     

   • Example log entry:

     {"request_id": "550e8400-e29b-41d4-a716-446655440000", ...}
     

3. Outbound API Calls (Guzzle):

   • Propagate the ID to external services via Guzzle middleware:

     avariya_request_id:
         guzzle_middleware: true
     

   • Ensure csa/guzzle-bundle is installed for middleware support.

Advanced Patterns

• Database Correlation:

  DB::table('logs')->insert([
      'request_id' => request()->header('X-Request-Id'),
      'message'    => 'User action',
  ]);
  

• Middleware for Custom Logic:

  public function handle($request, Closure $next) {
      $request->attributes->set('request_id', $request->header('X-Request-Id'));
      return $next($request);
  }
  

Gotchas and Tips

Pitfalls

1. Guzzle Middleware Dependency:

   • Requires csa/guzzle-bundle (not included by default). Install separately:

     composer require csa/guzzle-bundle
     

   • Configure Guzzle tag in config/packages/avariya_request_id.yaml:

     guzzle_middleware:
         guzzle_tag: guzzle.http_client
     

2. Monolog Version Conflicts:

   • The bundle targets Symfony MonologBundle v2/3. Ensure compatibility with your Laravel logging setup (e.g., monolog/monolog).
   • If using Laravel’s default logging, disable Monolog support:

     monolog_support: false
     

3. Header Overrides:

   • The bundle does not modify existing X-Request-Id headers. If you need to force regeneration, exclude the header in middleware:

     if (!$request->hasHeader('X-Request-Id')) {
         $request->headers->set('X-Request-Id', Str::uuid()->toString());
     }
     

Debugging Tips

• Verify Request ID Flow:

  php artisan tinker
  >> \Symfony\Component\HttpFoundation\Request::createFromGlobals()->header('X-Request-Id');
  

• Check Guzzle Middleware:
  • Ensure the middleware is registered in config/packages/csa_guzzle.yaml:

    clients:
        default:
            middleware: ['avariya_request_id']
    

Extension Points

1. Custom ID Generation: Override the subscriber’s generateId() method (extend the bundle or create a new subscriber).
2. Log Formatting: Extend the Monolog processor to modify log context:

   $processor = new \Avariya\RequestIdBundle\Processor\RequestIdProcessor();
   $processor->setRequestId($requestId);
   

3. Non-Header Propagation: Add support for other transports (e.g., cookies, database) by extending the RequestId class.