rafalmasiarek / dashboard-kit-addon-request-id
Per-request correlation ID addon for dashboard-kit. Injects request_id into all Monolog channels and propagates it via X-Request-ID header.
Package info
github.com/rafalmasiarek/php-dashboard-kit-addon-request-id
pkg:composer/rafalmasiarek/dashboard-kit-addon-request-id
Requires
- php: ^8.2
- monolog/monolog: ^3.0
- psr/http-server-middleware: ^1.0
- rafalmasiarek/dashboard-kit: *
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-17 23:37:09 UTC
README
Per-request correlation ID addon for dashboard-kit.
Generates or propagates a request ID from an HTTP header and injects req.id into every Monolog log record, making it possible to trace all log entries for a single request across channels.
License
Business Source License 1.1.
Source available; commercial use restricted until 2099-01-01.
See LICENSE for full details.
For alternative licensing, contact us.
Authors
Installation
composer require rafalmasiarek/dashboard-kit-addon-request-id
Usage
use rafalmasiarek\DashboardKit\Dashboard; use rafalmasiarek\DashboardKitRequestId\RequestIdAddon; $dashboard = Dashboard::create(__DIR__ . '/../', [ /* config */ ]); RequestIdAddon::register($dashboard->getApp(), $dashboard->getContainer()); $dashboard->run();
Configuration
RequestIdAddon::register($dashboard->getApp(), $dashboard->getContainer(), [ 'header' => 'X-Request-ID', // default; use 'X-Amzn-Trace-Id' behind AWS ALB ]);
| Option | Default | Description |
|---|---|---|
header |
X-Request-ID |
HTTP header to read the ID from and propagate back |
Log output
Every log record in app, audit, and error channels receives:
req.id=550e8400-e29b-41d4-a716-446655440000
When the header is absent, a UUID v4 is generated per request.
Cross-addon correlation
register() saves the processor in the container as log.processor.request_id. Other addons that create their own Monolog loggers (e.g. dashboard-kit-addon-geoip) pull this processor automatically to include req.id in their own log channels.
Register this addon before any other addon that should include req.id in its logs:
RequestIdAddon::register($dashboard->getApp(), $container); // first GeoIpAddon::register($dashboard->getApp(), $container); // picks up req.id automatically
Requirements
- PHP 8.2+
- dashboard-kit
- monolog/monolog ^3
Index
Classes
RequestIdAddon—rafalmasiarek\DashboardKitRequestIdRequestIdMiddleware—rafalmasiarek\DashboardKitRequestIdRequestProcessor—rafalmasiarek\DashboardKitRequestId
RequestIdAddon
class — rafalmasiarek\DashboardKitRequestId\RequestIdAddon · source
Dashboard Kit addon that wires per-request correlation ID logging. Registers RequestProcessor into every Monolog channel and adds RequestIdMiddleware as the outermost Slim middleware so every log entry carries request_id regardless of where it is written. Usage in public/index.php (after Dashboard::create(), before run()): RequestIdAddon::register($dashboard->getApp(), $dashboard->getContainer(), [ 'header' => 'X-Request-ID', ]); Configuration options: header (string) HTTP header to read/propagate. Default: X-Request-ID. Set to 'X-Amzn-Trace-Id' when running behind AWS ALB, or to the header your nginx/Caddy injects.
| Method | Visibility | Returns | Summary |
|---|---|---|---|
register() |
public static | void |
Registers the addon into an existing Dashboard application. Pushes RequestProcessor into all logger.* channels found in the container and adds RequestIdMiddleware as the outermost middleware layer. |
register()
RequestIdAddon register()
public static function register(App $app, ContainerInterface $container, array $config): void
Registers the addon into an existing Dashboard application. Pushes RequestProcessor into all logger.* channels found in the container and adds RequestIdMiddleware as the outermost middleware layer.
| Param | Type | Description |
|---|---|---|
$app |
App |
Slim application instance. |
$container |
ContainerInterface |
PHP-DI container from Dashboard::getContainer(). |
$config |
array<string, mixed> |
Optional configuration overrides. |
RequestIdMiddleware
class — rafalmasiarek\DashboardKitRequestId\RequestIdMiddleware · source
PSR-15 middleware that assigns a correlation ID to every request. Reads the ID from the configured request header (default: X-Request-ID); generates a UUID v4 if the header is absent. Calls RequestProcessor::boot() so every Monolog record for the request carries the same ID. Propagates the resolved ID back to the caller via the same response header.
implements MiddlewareInterface
Depends on: RequestProcessor
| Method | Visibility | Returns | Summary |
|---|---|---|---|
__construct() |
public | — | — |
process() |
public | ResponseInterface |
Boots the request context and passes the request to the next handler. |
generateUuid() |
private | string |
Generates a random UUID v4. |
__construct()
RequestIdMiddleware __construct()
public function __construct(RequestProcessor $processor, string $header)
| Param | Type | Description |
|---|---|---|
$processor |
RequestProcessor |
Monolog processor to boot with the resolved request ID. |
$header |
string |
HTTP header name to read from and write to. |
process()
RequestIdMiddleware process()
public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
Boots the request context and passes the request to the next handler.
| Param | Type | Description |
|---|---|---|
$request |
ServerRequestInterface |
PSR-7 server request. |
$handler |
RequestHandlerInterface |
Next middleware or route handler. |
Returns: ResponseInterface
generateUuid()
RequestIdMiddleware generateUuid()
private function generateUuid(): string
Generates a random UUID v4.
Returns: string
RequestProcessor
class — rafalmasiarek\DashboardKitRequestId\RequestProcessor · source
Monolog processor that injects a per-request correlation ID into every log record. Populated per-request by calling boot() from RequestIdMiddleware. Log output example: req.id=550e8400-e29b-41d4-a716-446655440000 user_id=3 email=…
| Property | Type | Visibility | Description |
|---|---|---|---|
$requestId |
string |
private | Correlation ID for the current request. |
| Method | Visibility | Returns | Summary |
|---|---|---|---|
boot() |
public | void |
Populates the correlation ID from the incoming request. Called once per request by RequestIdMiddleware. |
getRequestId() |
public | string |
Returns the current request_id, or an empty string when not yet set. |
__invoke() |
public | LogRecord |
Invoked by Monolog for every log record. Injects req.id into the record context. Log-call context takes priority — the processor only fills in the key if not already present. |
boot()
RequestProcessor boot()
public function boot(string $requestId, ServerRequestInterface $request): void
Populates the correlation ID from the incoming request. Called once per request by RequestIdMiddleware.
| Param | Type | Description |
|---|---|---|
$requestId |
string |
Correlation ID (from header or freshly generated). |
$request |
ServerRequestInterface |
Incoming PSR-7 request (reserved for future use). |
getRequestId()
RequestProcessor getRequestId()
public function getRequestId(): string
Returns the current request_id, or an empty string when not yet set.
Returns: string
__invoke()
RequestProcessor __invoke()
public function __invoke(LogRecord $record): LogRecord
Invoked by Monolog for every log record. Injects req.id into the record context. Log-call context takes priority — the processor only fills in the key if not already present.
| Param | Type | Description |
|---|---|---|
$record |
LogRecord |
— |
Returns: LogRecord