version: "1.0.1" name: create-structured-logger description: Generates Structured Logger for PHP 8.4. Creates PSR-3 structured logging setup with Monolog processors, correlation ID propagation, and context middleware. Includes unit tests.

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