Structured Logger Generator

Creates structured logging infrastructure for observability and request tracing.

When to Use

Component Characteristics

CorrelationId

• Value Object wrapping UUIDv4
• Immutable, self-validating
• Propagated via

  X-Request-ID

  header

CorrelationIdProcessor

• Monolog processor adding

  correlation_id

  to every record
• Reads from CorrelationIdHolder thread-local storage
• Zero-config: auto-enriches all log entries

RequestContextProcessor

• Monolog processor adding request metadata
• Captures method, URI, IP, user-agent
• Enables filtering logs by request attributes

CorrelationIdMiddleware

• PSR-15 middleware extracting or generating X-Request-ID
• Stores in CorrelationIdHolder for downstream use
• Adds correlation ID to response headers

CorrelationIdHolder

• Static thread-local storage for correlation ID
• Set once per request, available globally
• Reset after request completes

Generation Process

Step 1: Generate Core Components

Path:

src/Infrastructure/Logging/

1. CorrelationId.php

   — Value Object with UUID validation

2. CorrelationIdHolder.php

   — Thread-local correlation ID storage

Step 2: Generate Monolog Processors

Path:

src/Infrastructure/Logging/Processor/

1. CorrelationIdProcessor.php

   — Adds correlation_id to log records

2. RequestContextProcessor.php

   — Adds request context to log records

Step 3: Generate Middleware

Path:

src/Infrastructure/Logging/

1. CorrelationIdMiddleware.php

   — PSR-15 middleware for correlation ID

Step 4: Generate Tests

1. CorrelationIdTest.php

   — Value Object tests

2. CorrelationIdProcessorTest.php

   — Processor enrichment tests

3. CorrelationIdMiddlewareTest.php

   — Middleware behavior tests

File Placement

src/Infrastructure/Logging/

src/Infrastructure/Logging/Processor/

tests/Unit/Infrastructure/Logging/

Naming Conventions

CorrelationId

CorrelationId

CorrelationIdHolder

CorrelationIdHolder

{Context}Processor

CorrelationIdProcessor

CorrelationIdMiddleware

CorrelationIdMiddleware

{ClassName}Test

CorrelationIdTest

Quick Template Reference

CorrelationId

final readonly class CorrelationId
{
    public function __construct(public string $value)
    {
        // Validates UUID v4 format
    }

    public static function generate(): self;
    public function toString(): string;
}

CorrelationIdProcessor

final readonly class CorrelationIdProcessor
{
    public function __invoke(LogRecord $record): LogRecord;
}

CorrelationIdMiddleware

final readonly class CorrelationIdMiddleware implements MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface;
}

Usage Example

// Middleware extracts or generates correlation ID
$middleware = new CorrelationIdMiddleware(headerName: 'X-Request-ID');

// Monolog processor auto-enriches every log entry
$logger->pushProcessor(new CorrelationIdProcessor());
$logger->pushProcessor(new RequestContextProcessor($request));

// Log entry output:
// {"message":"Order created","correlation_id":"550e8400-...","method":"POST","uri":"/orders"}

Log Flow

Request ──→ CorrelationIdMiddleware
                │
         Extract/Generate X-Request-ID
                │
         Store in CorrelationIdHolder
                │
         CorrelationIdProcessor ──→ Adds correlation_id to every log
         RequestContextProcessor ──→ Adds method, URI, IP to every log
                │
         Response ──→ Add X-Request-ID header

Anti-patterns to Avoid

References

For complete PHP templates and examples, see:

• references/templates.md

  — CorrelationId, Processors, Middleware, Holder templates

• references/examples.md

  — Service integration examples and tests