Search by

rafalmasiarek / dashboard-kit-addon-request-id

rafalmasiarek

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

Statistics

Installs: 6

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 2

v1.0.1 2026-09-13 02:13 UTC

README

Packagist Version Total Downloads PHP License

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

License: BUSL-1.1

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

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()

source

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()

source

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()

source

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()

source

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()

source

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()

source

public function getRequestId(): string

Returns the current request_id, or an empty string when not yet set.

Returns: string

__invoke()

RequestProcessor __invoke()

source

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