DEV Community: Mike Georgeff

Context is Curated, Not Captured

Mike Georgeff — Mon, 22 Jun 2026 17:17:39 +0000

The Problem Part 1 Didn't Solve

Part 1 gave you consistent log line structure: every entry has a consistent envelope. But the context is still a free-for-all.

Two common anti-patterns:

Logging raw exception messages: $logger->error($e->getMessage()), a string with no structure, no machine-readable context
Dumping arbitrary data into the context: raw third-party API responses, full request payloads, deeply nested objects thrown into the context array

The second anti-pattern has real operational consequences. Log platforms have entry size limits; oversized context causes truncation or log entries being split and needing recomposition in the platform. Inconsistent field names across the codebase (userId, user_id, uid) destroy the aggregation the platform was bought to provide. The problem isn't the logger; the logger is doing its job. The problem is that the context is treated as a dumping ground rather than a contract.

Context is Curated, Not Captured

The discipline: define what fields belong on a log entry for a given exception ahead of time, not at the call site. The call site should never decide what context gets logged; the decision belongs at the domain model level.

This is the difference between:

// Captured - call site decides, schema varies everywhere
$logger->error($e->getMessage(), ['response' => $apiResponse, 'user' => $user]);

// Curated - schema defined on the exception, the reporter just delivers it
$logger->log($e->severity->value, $e->getMessage(), $e->structuredData);

structuredData is a property on the domain exception; it returns the complete structural representation of the exception: error code, severity, retryable flag, occurred_at, context, metadata. The reporter doesn't decide what gets logged; the exception does.

The reporter's job is minimal. Translate the throwable, then call the logger with the three values the domain exception already knows about itself.

$e = $this->translator->translate($exception);

$this->logger->log($e->severity->value, $e->getMessage(), $e->structuredData);

Consistency is the goal. Every PaymentFailedException that gets logged looks identical in your logging platform, regardless of where in the codebase it was thrown.

The Domain Exception Model

A domain exception is an exception that carries its own structured context. It knows severity, its error code, whether the operation is retryable, and the specific context field that describes it.

Key properties:

severity: not inferred by the logger, declared by the exception itself. severity is a backed enum (critical, error, warning, info, debug). $e->severity->value gives the string the logger expects. Type safety means no invalid severity values, no typos making it into production.
context: curated key/value data defined at construction, not at the log call.
retryable: operational metadata that belongs on the log entry.
occurredAt: RFC 3339 timestamp captured at throw time, not log time.
getErrorCode(): structured error code (e.g. DB_0001, PAYMENT_0033) that is independently queryable in your log platform.
structuredData: the complete structured representation of the exception, ready for the logger. Uses a property hook (PHP 8.4+), computed once, then cached.

Asymmetric property visibility public protected(set) (PHP 8.4+). Properties are publicly readable but only settable within the class and its subclasses. Immutable from the outside; prevents mutation after construction. getErrorCode() is abstract; every concrete exception must declare its own code. This is the contract that enforces the structured error code pattern across the codebase.

As a fallback for exceptions that have not been modeled yet, an UnknownException is defined that captures the original class, code, file and line. UNKNOWN_0000 as the error code is a signal in your log platform that something needs modeling.

The Translation Pipeline

Not every exception in your application will be a DomainException. Third-party libraries throw their own exceptions, PHP itself throws runtime errors. The translator's job is to accept any Throwable and return a DomainException.

The TranslationHandler contract has three methods.

interface TranslationHandler
{
    public function matches(Throwable $exception): bool;
    public function handle(Throwable $exception): DomainException;
    public function priority(): int;
}

matches(): does the handler know how to translate this exception?
handle(): translate the Throwable into a DomainException.
priority(): handlers are sorted once during construction, not at call time. Higher priority wins.

The translator's full constructor:

public function __construct(TranslationHandler ...$handlers)
{
    $sorted = [...$handlers];
    usort($sorted, fn($a, $b) => $b->priority() <=> $a->priority());
    $this->handlers = $sorted;
}

This is the same principle as the boot/run boundary from the kernel. Expensive work (sorting) happens once at construction; the hot path (translate()) just iterates an already-sorted list.

The translator walks the already sorted handler list and finds the first match.

$handler = array_find(
    $this->handlers,
    fn($h, $_) => $h->matches($exception)
);

array_find (PHP 8.4+) is the right tool. Find the first match and stop. No manual loops, no breaks; the intent is immediately readable.

The full pipeline: every Throwable that enters translate() follows exactly one path:

Step 1: already a domain exception, return as is

if ($exception instanceof DomainException) {
    return $exception;
}

No translation needed, no information lost.

Step 2: find the first matching handler

$handler = array_find(
    $this->handlers,
    fn($h, $_) => $h->matches($exception)
);

Step 3: no handler matched, wrap in an UnknownException and return

if (null === $handler) {
    return new UnknownException($exception);
}

Nothing is swallowed. UNKNOWN_0000 in the platform is a signal that this exception type needs a handler written for it.

Step 4: handler matched, translate and return

return $handler->handle($exception);

The handler produces a DomainException with curated context.

The pipeline is extensible. Add a handler for any third-party exception type and it gets curated context without touching the call site.

The Enricher Pattern

The enricher sits above the DomainException. It adds context fields to every log entry regardless of what is being logged. The ContextEnricher contract defines a single method: enrich(array $context): array. Enrichers are composed into the logger via the decorator pattern described in Part 1, wired at boot, invisible to the call site. The addition operator preserves caller-set values: $context + ['field' => $value]. An enricher never overwrites context that the DomainException already defined.

A concrete example: CorrelationIdEnricher

public function enrich(array $context): array
{
    return $context + ['correlation_id' => (string) $this->correlationId];
}

Every log entry now carries a correlation_id field, added once at the composition root, without a single call site change. The enricher is registered by the StructuredLoggingModule and auto-resolved by the kernel tag registry; the developer adds the module explicitly, and the enricher wires itself through the tag system with no further call site work. What correlation_id is, where it comes from, and how it connects log entries across service boundaries will be explained in Part 3.

What You Have Now and What's Still Missing

Every log entry has a consistent envelope (Part 1), every exception produces consistent curated structured context, and every log entry carries a correlation_id field. Your log platform can now aggregate by error code, filter by severity, track retryable vs non-retryable failures, and report on error rates by type. But, correlation_id is only useful if it's the same value across all log entries for a given request, and across all services that handle that request. A correlation_id that resets per service tells you nothing about the flow of the request through a distributed system.

Part 3 of this series will define what correlation IDs are, why they matter, and how they flow across service boundaries.

If you want to see a full concrete implementation of everything covered in this article, meritum/structured-logging is a domain exception model, translation pipeline, and enricher system built on these exact principles.

Natural Aristoi - dev.to/georgeff/natural-aristoi-h6j
Two Phases, Two APIs - dev.to/georgeff/two-phases-two-apis-425j

Your PHP Logs are Lying to You

Mike Georgeff — Tue, 16 Jun 2026 14:42:04 +0000

The Evolution: From Log Tails to Indexed Search

Most teams start with a stream-based log platform, such as Papertrail, Loggly, or legacy syslog viewers. These platforms are fast to set up, and work well early on, but ultimately are just live tail with grep. Unstructured logs work fine here because a human is reading and searching them manually. As the application and team grow, you graduate to an indexed search platform, such as Elastic/OpenSearch, Datadog Logs, or Loki with LogQL. This is where unstructured logs break down because these platforms expect to index fields, not parse free text. You can still ship plain text to Elastic, but you've thrown away everything that makes it powerful: field filtering, aggregations, dashboards, and alerting on specific values. If you're thinking "we write to a log file, not a stream", that's fine, and many of these stream platforms are reading a file anyway. The live tail is literally tail -f. The problem was never the destination. The problem is what the file contains. The platform didn't change your logs, it exposed what your logs already were: unstructured text. Structured logs enable trend analysis: error rate over time, errors by application version, change failure rate after a deployment. These are questions grep can't answer. "Did our error rate increase after v2.3.0 shipped?" requires version, level, and timestamp as discrete, indexed fields you can aggregate on, not substrings buried in formatted strings. These are the kinds of questions that matter at an engineering org level. Change failure rate is a DORA metric. Teams measuring engineering effectiveness need their logs to support it, and that's only possible with consistent structure.

Stdout Decouples Your Application from the Log Destination

Writing to stdout is an intentional architectural boundary, not a lack of a "real" logging setup. Your application's only concern is emitting a well-formed log entry to the stream. Where it goes after that is not the application's problem. In a Kubernetes environment, an operator (Fluentd, Fluent Bit, Logstash, Vector) captures the stdout stream from each container and routes it. Swapping log platforms is an operator configuration change. Zero application code is touched, and there is zero redeployment of your software. A Kubernetes operator can fan logs out to multiple destinations simultaneously: Elastic for search indexing, S3 for long-term archival, PagerDuty for critical-level entries. Your application emits once, and the operator handles the rest. This fan-out is something a tightly coupled or file-based logger cannot do cleanly. The application would have to be aware of every destination. The 12-factor principle formalizes this: treat logs as event streams, let the execution environment handle routing and storage.

What Structured Logging Actually Is

Each log entry is a self-describing data structure, not a formatted string. Use NDJSON (Newline Delimited JSON), one JSON object per line, independently parseable by the logging platform. The platform indexes each field, not the full string. This is the difference between "find me logs containing the word payment" and "find me all error-level logs where amount > 100 in the last 15 minutes". The platform can only be as powerful as the structure you give it.

Example comparison:

# Unstructured
[2026-06-09 14:32:01] ERROR: Payment failed for user 4321

# Structured
{"timestamp":"2026-06-15T10:28:01.123+00:00","level":"error","severity":"error","message":"Payment failed","context":{"user_id":4321,"app_version":"1.3.0"}}

What belongs on every log line:

timestamp: RFC 3339 extended, UTC (e.g. 2026-06-10T14:32:01.123+00:00)
level: original PSR-3 level name, all 8 values are preserved
severity: reduced 5-value set (debug, info, warning, error, critical) aligned with structured log sinks
message: human-readable summary, kept short
context: structured key/value object, always present even when no context is supplied

Why level and severity? PSR-3 defines 8 levels, but most sinks don't natively understand all of them. severity gives the platform a normalized field it can reliably aggregate on without knowing PSR-3's model. In short, level preserves PSR-3 fidelity, severity serves the platform. No information is lost and the sink gets what it needs. The practical side effect is the severity field ends the "when do I use emergency vs alert vs critical" debate. Those distinctions came from syslog and don't map cleanly to application logging. Your alerting dashboard runs on severity. Operationally, all three mean the same thing. The nuance lives in level for whoever needs it.

Consistency matters more than completeness. Every line must have the same shape. A version field that appears on 60% of log lines is useless for change failure rate reporting.

PSR-3 and Why It Matters

PSR-3 is the PHP standard logging contract defining 8 severity methods and log(). Context, the second argument defined by the interface, is where the structure lives.

$logger->error('Payment failed', ['user_id' => 4321, 'app_version' => '1.3.0']);

user_id and app_version will appear on every "Payment failed" log, providing the logging platform consistent data to index.

Coding to PSR-3 means your application is decoupled from the concrete logger implementation. The decorator pattern is a natural extension of PSR-3 decoupling. Because LoggerInterface is an interface, you can wrap any logger that implements the same contract. A context-enriching logger accepts a LoggerInterface, enriches the context, then delegates to the inner logger. The call site never changes.

<?php

final class ContextEnrichingLogger implements LoggerInterface
{
    /**
     * @var ContextEnricher[]
     */
    private readonly array $enrichers;

    public function __construct(
        private readonly LoggerInterface $inner,
        ContextEnricher ...$enrichers
    ) {
        $this->enrichers = $enrichers;
    }

    public function info(string $message, array $context = []): void
    {
        $enrichedContext = $this->enrichContext($context);

        $this->inner->info($message, $enrichedContext);
    }

    // Remaining LoggerInterface methods
}

This is where consistent context attributes get added once, at the composition root, rather than at every log call site. Wire the decorator at boot time and every log call in the application gets the enriched context automatically. The enrichers can globally capture values such as app_version, environment, and correlation_id. This provides a central location to build out log context, eliminating repetition at every log call. What the enricher pipeline doesn't solve is converting a thrown exception into structured context.

Writing a Minimal Structured Logger

When writing a minimal logger, implement the LoggerInterface as a first-class citizen of the implementation, not an afterthought. The psr/log package also ships with a trait defining the 8 standard methods, allowing the implementation to focus on log().

<?php

use Psr\Log\LoggerTrait;
use Psr\Log\LoggerInterface;

final class Logger implements LoggerInterface
{
    use LoggerTrait;

}

Write the output to stdout.

/**
 * @var resource
 */
private $output;

public function __construct(mixed $output = STDOUT)
{
    if (!is_resource($output)) {
        throw new \InvalidArgumentException('Logger output must be a resource');
    }

    $this->output = $output;
}

Format each entry as a JSON object.

public function log(string $level, \Stringable|string $message, array $context = []): void
{
    $severityMap = [
        'emergency' => 'critical',
        'alert'     => 'critical',
        'critical'  => 'critical',
        'error'     => 'error',
        'warning'   => 'warning',
        'notice'    => 'info',
        'info'      => 'info',
        'debug'     => 'debug',
    ];

    $logEntry = [
        'timestamp' => (new \DateTimeImmutable())->format(\DateTimeInterface::RFC3339_EXTENDED),
        'level'     => $level,
        'severity'  => $severityMap[$level],
        'message'   => (string) $message,
        'context'   => $context,
    ];

    $json = json_encode($logEntry, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);

    fwrite($this->output, $json . PHP_EOL);
}

Keep it simple. No file rotation, no handlers, no formatters. The logger's only job is to serialize a log entry and write it to the stream.

What You Have Now and What's Still Missing

You have clean, machine-readable, streamable logs that log aggregators can ingest and index without configuration. Once your logs are structured, how do you enrich them with the proper context, especially when the event being logged is an exception? And that's before we even get to the thousands of JSON lines with no way to know which lines belong to the same request.

Part 2 of this series will cover the domain exception model and translation pipeline that turns exceptions into structured log data.

If you want to see a full concrete implementation of everything covered in this article, meritum/logger is a minimal PSR-3 structured logger built on these exact principles: RFC 3339 timestamps, NDJSON to stdout, severity normalization for structured log sinks.

Two Phases, Two APIs

Mike Georgeff — Tue, 09 Jun 2026 03:01:24 +0000

Most applications have no enforced lifecycle boundaries. Services get resolved at arbitrary times, configs mutate mid-request, init logic bleeds into request handling. The result is an application that is difficult to reason about because its state is never truly settled.

The Two Phases

Boot: The period before the application handles any work. The sole purpose of the boot phase is construction, registering service definitions, merging configuration, wiring dependencies, and running initialization logic. When boot ends, the service layer is immutable, nothing new can be registered, nothing can be reconfigured.

Run: The application transforms inputs into outputs using the fully constructed service layer. No reconfiguration, no new definitions, no structural mutations, only pure transformation.

The hard boundary between boot and run is not a convention, it is a constraint.

Why the Boundary Matters

Predictability: if the service layer is immutable after boot you always know what you are working with during a request
Testability: an immutable service graph is easy to inspect and reproduce in tests
Debuggability: boot-time errors fail loud and early, they do not surface as mysterious runtime behavior
Security: a service layer that cannot be mutated at runtime prevents the injection of rogue providers or configuration overrides, shrinking the attack surface

Boot is boot, run is run, this should be enforced, not suggested.

The Two APIs

The package georgeff/kernel enforces this at the type level.

When correctly composed, kernel definitions are registered before boot is called, and the fully initialized container is available after.

$kernel = new Kernel();

$kernel->addDefinition(MyClass::class, fn() => new MyClass());
$kernel->boot();
$container = $kernel->getContainer();

$container->get(MyClass::class);

When addDefinition is called after boot, a KernelException will be thrown because the service layer is immutable.

$kernel = new Kernel();

$kernel->boot();
$kernel->addDefinition(MyClass::class, fn() => new MyClass());

If the container is accessed before boot, a KernelException will be thrown because the container has not yet been initialized.

$kernel = new Kernel();

$container = $kernel->getContainer();

$kernel->boot();

Run begins the moment boot() returns, after the kernel is a resolved, immutable service graph. The handoff from construction to transformation is complete.

Modules as Boot-Time Citizens

In the georgeff/kernel package, modules enforce the phase separation by design. ModuleInterface::register() is a boot-time method, whose purpose is to register service definitions, tags, and decorators. BootableModuleInterface::boot() is called at the tail end of the boot cycle, providing access to the built container for initialization work. New definitions cannot be registered at this stage since the service graph is already sealed. Neither has any role in run, making it structurally impossible to blur the line.

Phases as Architecture

The boot/run distinction is not a pattern unique to this kernel, it is a general principle that most applications implement accidentally and inconsistently. Making it explicit, enforcing it with hard constraints, and designing your application around it produces software that is honest about its own state.

Related: Natural Aristoi — the philosophy behind the design decisions in this package.

Natural Aristoi

Mike Georgeff — Wed, 03 Jun 2026 05:08:40 +0000

Frameworks should earn their place in your application through demonstrated merit -- not convention, not network effect, not being the path of least resistance.

The Concept

Natural Aristoi is a concept championed by Thomas Jefferson describing a governing class defined by virtue and talent, not birth or privilege. Jefferson believed in small government, states' rights over federal, power closest to the people it governs -- local, visible, accountable. Distrust of centralized authority that accumulates complexity, imposes its will and becomes impossible to remove once entrenched.

Small codebase. Components over monolith. Architecture closest to the problem it solves -- visible, intentional, accountable in its behavior. Distrust of the monolithic framework that grows, mandates, and makes decisions on your behalf whether you asked it or not.

The Problem with Full Frameworks

Frameworks force an all-or-nothing decision. Opinions are baked into every layer. This leads to abstractions that you did not ask for that hide what is actually happening. When your needs diverge, you're fighting the framework instead of engineering the solution.

Ultimately engineering comes in second, the framework's conventions come first.

The Composability Alternative

Compose only what your application needs -- nothing more, nothing less. Each component earns its place by doing precisely one thing. Shared standards serve as the contract layer -- components speak to each other through interfaces, not implementations. In PHP, PSR standards serve this exact role -- defining interfaces that components agree on without mandating how any of them are implemented. The result is small, purposeful, replaceable pieces that assemble into something cohesive.

The engineer decides the architecture, not the framework.

Principles

Define hard boundaries -- boot is boot, run is run, this should be enforced, not suggested.
Immutability as a constraint -- the service layer freezes at boot, making predictability a guarantee.
Explicit over implicit -- dependencies are declared, not located; registration is separated from resolution.
Pure transformation -- the system transforms inputs, it does not reconfigure itself.
Restraint as a signal -- 165 lines for a DI container, because that's all it needs to be.

Why this Matters

Applications built this way are predictable, testable, and honest about their own state. Implementation changes do not cause a snowball effect, they are centralized and isolated. Good software earns its place, flawed software is easily removed.

Engineers who understand their stack make better decisions.