A Domain Logger Port: Decoupling From PSR-3 Without Losing Context

#php #architecture #hexagonal #logging

Book: Decoupled PHP — Clean and Hexagonal Architecture for Applications That Outlive the Framework
Also by me: Thinking in Go (2-book series) — Complete Guide to Go Programming + Hexagonal Architecture in Go
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

You open a use case that places an order. Near the top of the constructor, alongside the repositories and the payment gateway, sits a Psr\Log\LoggerInterface. The method body calls $this->logger->info(...) three times. It looks harmless. It is the most common way framework concerns leak back into a domain you spent weeks keeping clean.

PSR-3 is a fine standard. Monolog is the default implementation in most PHP projects, and it earns that spot. The problem is not the library. The problem is where you point it. When LoggerInterface is a constructor argument in your application layer, your use case now depends on a package whose surface area you do not control, whose log levels you may not want, and whose context conventions are someone else's. The dependency arrow points the wrong way.

What PSR-3 drags in

Psr\Log\LoggerInterface is eight level methods plus a generic log(). The level taxonomy comes from RFC 5424 syslog: emergency, alert, critical, error, warning, notice, info, debug. That is a system-administration vocabulary. Your domain does not speak it.

When a use case calls $this->logger->warning('payment retry'), you have to ask: is a retry a warning or a notice? The answer is an infrastructure judgment call wearing a domain costume. The method signature also accepts an arbitrary array $context and a string|Stringable $message with {placeholder} interpolation. None of that is something your application code should be deciding.

<?php

declare(strict_types=1);

namespace App\Application\Order;

use Psr\Log\LoggerInterface;

final readonly class PlaceOrder
{
    public function __construct(
        private OrderRepository $orders,
        private PaymentGateway $payments,
        private LoggerInterface $logger,
    ) {}

    public function execute(PlaceOrderInput $in): void
    {
        // ... domain work ...
        $this->logger->info('order.placed', [
            'order_id' => $orderId->value,
            'customer_id' => $in->customerId,
        ]);
    }
}

Open this file and you import Psr\Log. Run static analysis on the domain boundary and the import shows up. The use case now knows a logging package exists, knows its level names, and knows its context-array shape. That is three pieces of infrastructure knowledge living in a layer that is supposed to know none.

A port stated in your language

The fix is the same one you apply to persistence and payments: state the requirement as an interface in your own namespace, in your own vocabulary. The application layer owns the contract. Infrastructure implements it.

<?php

declare(strict_types=1);

namespace App\Application\Port;

interface DomainLogger
{
    /** @param array<string, scalar|null> $context */
    public function event(string $name, array $context = []): void;

    /** @param array<string, scalar|null> $context */
    public function failure(
        string $name,
        \Throwable $cause,
        array $context = [],
    ): void;
}

Two methods. event records something that happened in the domain. failure records something that went wrong, with the throwable attached. No debug, no notice, no emergency. Those are operator-facing severities, and the adapter decides them, not the use case.

The name is an event name, not a sentence. order.placed, payment.declined, order.cancellation_rejected. Stable, greppable, dot-namespaced. The context is typed: a flat map of scalars, the kind of thing that survives JSON encoding without surprises. No nested objects, no closures, no Stringable ambiguity.

The use case after the swap

The constructor argument changes type. The import changes namespace. The call site reads as domain language.

<?php

declare(strict_types=1);

namespace App\Application\Order;

use App\Application\Port\DomainLogger;

final readonly class PlaceOrder
{
    public function __construct(
        private OrderRepository $orders,
        private PaymentGateway $payments,
        private DomainLogger $log,
    ) {}

    public function execute(PlaceOrderInput $in): void
    {
        // ... domain work ...
        $this->log->event('order.placed', [
            'order_id' => $orderId->value,
            'customer_id' => $in->customerId,
            'total_cents' => $total->amountInMinorUnits,
        ]);
    }
}

Nothing in this file imports Psr\Log. The use case states what happened (order.placed) and the facts that matter (ids, amount). Whether that becomes a Monolog info line, a structured JSON record, or a span attribute is a decision made one layer out. The same CI grep that fails the build on use Doctrine in src/Domain/ now also fails on use Psr\Log in the application layer, and the boundary holds.

The Monolog adapter

Infrastructure is the only place that knows PSR-3 exists. The adapter takes a LoggerInterface and maps your two domain methods onto it.

<?php

declare(strict_types=1);

namespace App\Infrastructure\Logging;

use App\Application\Port\DomainLogger;
use Psr\Log\LoggerInterface;

final readonly class PsrDomainLogger implements DomainLogger
{
    public function __construct(
        private LoggerInterface $psr,
    ) {}

    public function event(string $name, array $context = []): void
    {
        $this->psr->info($name, $this->normalize($context));
    }

    public function failure(
        string $name,
        \Throwable $cause,
        array $context = [],
    ): void {
        $this->psr->error($name, $this->normalize($context) + [
            'exception' => $cause::class,
            'message' => $cause->getMessage(),
        ]);
    }

    /**
     * @param array<string, scalar|null> $in
     * @return array<string, scalar|null>
     */
    private function normalize(array $in): array
    {
        $in['event'] = true;
        return $in;
    }
}

This is where the syslog-level decision lives, where it belongs. A domain event becomes PSR info; a failure becomes PSR error with the exception class and message folded into context. If your operations team later wants payment.declined at warning instead, you change the adapter, and not one use case moves.

Wiring is one binding in the composition root. Monolog gets configured with its handlers and processors there; the application never sees that configuration.

<?php

use App\Application\Port\DomainLogger;
use App\Infrastructure\Logging\PsrDomainLogger;
use Monolog\Handler\StreamHandler;
use Monolog\Logger;
use Monolog\Processor\PsrLogMessageProcessor;

$monolog = new Logger('app');
$monolog->pushHandler(new StreamHandler('php://stderr'));
$monolog->pushProcessor(new PsrLogMessageProcessor());

$container->set(
    DomainLogger::class,
    static fn (): DomainLogger => new PsrDomainLogger($monolog),
);

Keeping context across a request

The objection comes fast: PSR-3 has no idea what request it is in, and you do not want every use case threading a request_id through every event call. Correct. That plumbing is an adapter concern, so put it in the adapter.

Monolog solves cross-cutting context with processors. A processor runs on every record and can attach fields. Register one that reads a request-scoped context holder, and the request_id, tenant_id, and trace_id ride along on every line without a single use case knowing they exist.

<?php

declare(strict_types=1);

namespace App\Infrastructure\Logging;

use Monolog\LogRecord;

final class RequestContextProcessor
{
    /** @param array<string, scalar|null> $context */
    public function __construct(private array $context = []) {}

    public function __invoke(LogRecord $record): LogRecord
    {
        return $record->with(
            extra: $record->extra + $this->context,
        );
    }
}

You populate the holder once, in the HTTP entry point, from a middleware that reads or generates the correlation id. The CLI entry point populates it from the command name and a fresh run id. The queue worker populates it from the message headers. Three inbound adapters, three ways to fill context, one processor that does not care which one ran. The use case in the middle stays a pure function of its inputs and its ports.

The test fake costs nothing

A domain logger you own is a domain logger you can record against in a unit test. No Monolog handler, no log-file assertions, no TestHandler from the vendor package.

<?php

declare(strict_types=1);

namespace App\Tests\Fake;

use App\Application\Port\DomainLogger;

final class RecordingLogger implements DomainLogger
{
    /** @var list<array{name: string, context: array}> */
    public array $events = [];

    public function event(string $name, array $context = []): void
    {
        $this->events[] = ['name' => $name, 'context' => $context];
    }

    public function failure(
        string $name,
        \Throwable $cause,
        array $context = [],
    ): void {
        $this->events[] = ['name' => $name, 'context' => $context];
    }
}

Now a test can assert that placing an order emits order.placed with the right ids, the same way it asserts the order was saved. Logging stops being an untested side channel and becomes part of the contract you verify.

public function test_place_order_logs_the_event(): void
{
    $log = new RecordingLogger();
    $useCase = new PlaceOrder($orders, $payments, $log);

    $useCase->execute($input);

    self::assertSame('order.placed', $log->events[0]['name']);
    self::assertSame('c-1', $log->events[0]['context']['customer_id']);
}

When the narrow port is overkill

This is not a rule for every class. A controller, a Monolog processor, a piece of glue that is already infrastructure: let those take LoggerInterface directly. They live in the layer that owns the dependency, so importing PSR-3 there costs nothing. The port exists to protect the domain and application layers, the code you want to outlive Monolog, the framework, and the logging conventions of whatever team owns the project three years from now.

The test is one question. If the file lives where use Psr\Log would fail your boundary check, it gets the port. If it lives in infrastructure, it can speak PSR-3 in its native tongue. The line is the same line you already draw for repositories and HTTP clients. Logging is not special; it just looks harmless enough that most codebases forget to draw it.

If this was useful

The logging port is a small instance of the same move the book makes everywhere: name the thing your domain needs in your own words, then let an adapter speak the vendor's dialect at the edge. Decoupled PHP works through the ports your application actually needs (persistence, messaging, clocks, HTTP, and the cross-cutting ones like this) and the migration path for pulling them out of a codebase that wired them straight into the framework.