dykyi-roman/awesome-claude-code/create-structured-logger

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

Naming Conventions

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