new feature set

Author: mohamedahmed01

ReadME.md

@@ -1,53 +1,127 @@
-Laravel Correlation ID Middleware
-=================================
+# Laravel Correlation ID Middleware
 
-A package to manage correlation IDs for request tracing in Laravel applications,
-A correlation ID is a randomly generated identifier for every request entering a distributed system. Developers use the correlation identifier to trace the request as it makes its way through the system, identify any cyber security threats, and prevent them.
-The correlation ID basically serves as a thread that connects the various parts of a request as it moves through the system. This greatly simplifies distributed system debugging and troubleshooting by allowing developers to track a request’s progress and readily pinpoint the service or component where an issue occurred.
+A package to manage correlation IDs for request tracing in Laravel applications.
 
+A correlation ID is a unique identifier assigned to each request entering a distributed system. It helps developers trace requests, debug issues, and identify potential security threats. By attaching a correlation ID to each request, you can track its journey through various services and components, simplifying troubleshooting and monitoring.
 
-Installation
-------------
+---
 
-    composer require mohamedahmed01/laravel-correlation
+## 📌 Installation
 
-Configuration
--------------
+```sh
+composer require mohamedahmed01/laravel-correlation
+```
 
-Publish the config file:
+---
 
-    php artisan vendor:publish --tag=correlation-config
+## ⚙️ Configuration
 
-Config options (`config/correlation.php`):
+### Publish the Config File
 
-*   `header`: Header name to use (default: X-Correlation-ID)
-*   `auto_register_middleware`: Automatically register middleware (default: true)
+```sh
+php artisan vendor:publish --tag=correlation-config
+```
 
-Usage
------
+### Config Options (`config/correlation.php`)
+
+- **`header`**: Header name to use (default: `X-Correlation-ID`)
+- **`alternate_headers`**: Additional headers to check for a correlation ID (e.g., `X-Request-ID`, `Trace-ID`)
+- **`generator`**: Strategy for generating correlation IDs (`uuid`, `timestamp`, `hash`)
+- **`storage`**: Store correlation IDs in `cache`, `session`, or `none`
+- **`queue`**: Enable correlation ID propagation in queued jobs (default: `true`)
+- **`propagate`**: Automatically include correlation ID in outgoing HTTP requests (default: `true`)
+- **`auto_register_middleware`**: Automatically register middleware (default: `true`)
+
+---
+
+## 🚀 Usage
 
 The correlation ID will be:
 
-1.  Read from incoming requests
-2.  Generated if missing
-3.  Added to all responses
-4.  Available in logs
-5.  Accessible via `correlation_id()` helper
+1. Extracted from incoming requests (from configured headers)
+2. Generated if missing (based on configured strategy)
+3. Stored in cache (if enabled)
+4. Included in all responses
+5. Available in logs
+6. Passed through queued jobs
+7. Propagated in HTTP requests
+8. Accessible via helper functions and Blade directives
 
-### Manual Middleware Registration
+### Middleware Registration
 
-Add to `app/Http/Kernel.php`:
+If `auto_register_middleware` is disabled, manually register the middleware in `app/Http/Kernel.php`:
 
-    protected $middleware = [
-        \Mohamedahmed01\LaravelCorrelation\Http\Middleware\CorrelationMiddleware::class,
-    ];
+```php
+protected $middleware = [
+    \Mohamedahmed01\LaravelCorrelation\Http\Middleware\CorrelationMiddleware::class,
+];
+```
 
 ### Accessing the Correlation ID
 
+#### 📌 In Controllers or Services
+
+```php
+$correlationId = correlation_id();
+```
+
+#### 📌 In Blade Views
+
+```blade
+@correlationId
+```
+
+#### 📌 In Jobs (Queued Work)
+
+```php
+public function handle()
+{
     $correlationId = correlation_id();
+    Log::info("Processing job", ['correlation_id' => $correlationId]);
+}
+```
+
+#### 📌 In Logs
+
+All logs during a request will automatically include the correlation ID:
+
+```json
+{
+    "message": "User created",
+    "context": {
+        "correlation_id": "123e4567-e89b-12d3-a456-426614174000"
+    }
+}
+```
+
+### 🌍 HTTP Client Propagation
+
+If `propagate` is enabled, correlation IDs will be automatically included in outgoing HTTP requests:
+
+```php
+$response = Http::withCorrelationId()->get('https://api.example.com/data');
+```
+
+### 🔧 Artisan Commands
+
+List stored correlation IDs:
+
+```sh
+php artisan correlation:list
+```
+
+---
+
+## ✅ Testing
+
+Run the test suite to ensure functionality:
+
+```sh
+php artisan test
+```
 
-### Logging
+---
 
-All logs during a request will automatically include:
+## 📜 License
 
-    ['correlation_id' => 'your-uuid']
+MIT License

composer.json

@@ -10,7 +10,9 @@
     ],
     "require": {
         "php": "^8.0",
-        "laravel/framework": "^9.0|^10.0"
+        "laravel/framework": "^9.0|^10.0",
+        "guzzlehttp/guzzle": "^7.0",
+        "guzzlehttp/psr7": "^2.0"
     },
     "autoload": {
         "psr-4": {

config/correlation.php

@@ -2,5 +2,24 @@
 
 return [
     'header' => env('CORRELATION_HEADER', 'X-Correlation-ID'),
+
+    // Define ID generation method: uuid, timestamp, hash
+    'generator' => env('CORRELATION_GENERATOR', 'uuid'),
+
+    // Enable logging integration
+    'log' => true,
+
+    // Enable correlation ID propagation in HTTP requests
+    'propagate' => true,
+
+    // Enable queue support (attaching correlation ID to jobs)
+    'queue' => true,
+
+    // Enable storing correlation IDs in cache or database
+    'storage' => env('CORRELATION_STORAGE', 'cache'), // options: cache, database, none
+
+    // Alternate header names for compatibility
+    'alternate_headers' => ['X-Request-ID', 'Trace-ID'],
+
     'auto_register_middleware' => env('CORRELATION_AUTO_REGISTER', true),
 ];

src/Console/Commands/CorrelationListCommand.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace Mohamedahmed01\LaravelCorrelation\Console\Commands;
+
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\Cache;
+
+class CorrelationListCommand extends Command
+{
+    protected $signature = 'correlation:list';
+    protected $description = 'List recent correlation IDs';
+
+    public function handle()
+    {
+        $keys = Cache::get('correlation:keys', []);
+
+        if (empty($keys)) {
+            $this->warn('No correlation IDs found.');
+            return;
+        }
+
+        foreach ($keys as $key) {
+            $time = Cache::get("correlation:$key", 'Unknown time');
+            $this->info("Correlation ID: $key - Time: $time");
+        }
+    }
+}
+

src/CorrelationServiceProvider.php

@@ -3,12 +3,21 @@
 namespace Mohamedahmed01\LaravelCorrelation;
 
 use Illuminate\Support\ServiceProvider;
+use Illuminate\Support\Facades\Blade;
+use Illuminate\Support\Facades\Http;
+
 use Mohamedahmed01\LaravelCorrelation\Http\Middleware\CorrelationMiddleware;
+use Mohamedahmed01\LaravelCorrelation\CorrelationServiceProvider;
 
 class CorrelationServiceProvider extends ServiceProvider
 {
+
     public function boot(): void
     {
+        Blade::directive('correlationId', function () {
+            return "<?php echo correlation_id(); ?>";
+        });
+
         $this->publishes([
             __DIR__.'/../config/correlation.php' => config_path('correlation.php'),
         ], 'correlation-config');
@@ -17,6 +26,18 @@ public function boot(): void
             $this->app['router']->pushMiddlewareToGroup('web', CorrelationMiddleware::class);
             $this->app['router']->pushMiddlewareToGroup('api', CorrelationMiddleware::class);
         }
+
+        Http::macro('withCorrelationId', function () {
+            return Http::withHeaders([
+                config('correlation.header') => correlation_id(),
+            ]);
+        });
+
+        if ($this->app->runningInConsole()) {
+            $this->commands([
+                \Mohamedahmed01\LaravelCorrelation\Console\Commands\CorrelationListCommand::class,
+            ]);
+        }
     }
 
     public function register(): void

src/Http/Middleware/CorrelationMiddleware.php

@@ -4,6 +4,9 @@
 
 use Closure;
 use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Facades\Queue;
 use Illuminate\Support\Str;
 use Symfony\Component\HttpFoundation\Response;
 
@@ -12,20 +15,47 @@ class CorrelationMiddleware
     public function handle(Request $request, Closure $next): Response
     {
         $headerName = config('correlation.header', 'X-Correlation-ID');
-        $correlationId = $request->header($headerName) ?? Str::uuid()->toString();
+        $alternateHeaders = config('correlation.alternate_headers', []);
+
+        $correlationId = $this->getCorrelationId($request, $headerName, $alternateHeaders);
 
-        // Store in application container
         app()->instance('correlation.id', $correlationId);
 
-        // Add to log context using multiple methods
-        $this->addLogContext($correlationId);
+        if (config('correlation.log')) {
+            $this->addLogContext($correlationId);
+        }
+
+        if (config('correlation.storage') === 'cache') {
+            Cache::put('correlation:' . $correlationId, now()->toDateTimeString(), 3600);
+        }
+
+        if (config('correlation.queue')) {
+            Queue::before(fn($event) => $event->job->setCorrelationId($correlationId));
+        }
 
         $response = $next($request);
         $response->headers->set($headerName, $correlationId);
 
         return $response;
     }
 
+    protected function getCorrelationId(Request $request, string $headerName, array $alternateHeaders): string
+    {
+        // Check for existing correlation ID
+        foreach ([$headerName, ...$alternateHeaders] as $header) {
+            if ($id = $request->header($header)) {
+                return $id;
+            }
+        }
+
+        // Generate a new correlation ID
+        return match (config('correlation.generator', 'uuid')) {
+            'timestamp' => now()->timestamp . Str::random(5),
+            'hash' => hash('sha256', Str::uuid()->toString()),
+            default => Str::uuid()->toString(),
+        };
+    }
+
     protected function addLogContext(string $correlationId): void
     {
         if (method_exists(\Log::class, 'shareContext')) {

src/helpers.php

@@ -1,10 +1,8 @@
 <?php
 
-use Illuminate\Contracts\Foundation\Application;
-
-if (! function_exists('correlation_id')) {
-    function correlation_id(): ?string
+if (!function_exists('correlation_id')) {
+    function correlation_id()
     {
-        return app()->has('correlation.id') ? app('correlation.id') : null;
+        return app('correlation.id');
     }
-}
+}