Logging-Behavior
Loggen Sie Methodenaufrufe, Ergebnisse und Fehler mit einem einzigen Attribut. Ein #[Loggable]-Behavior mit einem PSR-3-Logger, das Logging-Code und Logger-Abhängigkeiten aus Ihren Domänenklassen heraushält.
Aus dem Englischen übersetzt. Maßgeblich ist die englische Seite. Original lesen
Ein Kunde meldet, dass eine Abhebung fehlgeschlagen ist, und niemand kann sagen, warum. Die Antwort sollte in den Logs stehen, aber jede wichtige Methode von Hand zu loggen begräbt die Geschäftslogik. Diese Seite verlagert das Logging in ein Behavior (Verhalten): Sie markieren eine Methode mit #[Loggable], und das Framework führt das Logging als Middleware um sie herum aus. Die Begriffe Behavior-Klasse (Verhaltensklasse), Behavior und Matching-Rule (Auswahlregel) erklärt die Begriffstabelle.
Das Problem
Abschnitt betitelt „Das Problem“Ein Bankkonto mit zwei Operationen:
final class Account{ public function __construct(private int $balance = 0) {}
public function deposit(int $amount): void { $this->balance += $amount; }
public function withdraw(int $amount): void { if ($amount > $this->balance) { throw new InsufficientFunds($this->balance, $amount); } $this->balance -= $amount; }}Eine nützliche Log-Strategie: eine Zeile schreiben, wenn eine Methode beginnt, und eine, wenn sie endet. Ein Beginn ohne Ende zeigt auf den Fehler, selbst wenn der Prozess abstürzt und kein catch-Block läuft. Von Hand sieht das so aus:
use Psr\Log\LoggerInterface;
final class Account{ public function __construct( private LoggerInterface $logger, private int $balance = 0, ) {}
public function withdraw(int $amount): void { $this->logger->info('Entering withdraw', ['amount' => $amount]); try { if ($amount > $this->balance) { throw new InsufficientFunds($this->balance, $amount); } $this->balance -= $amount; $this->logger->info('Finished withdraw', ['amount' => $amount]); } catch (\Throwable $exception) { $this->logger->error('Failed withdraw', ['exception' => $exception]); throw $exception; } }
// deposit(): the same wrapper again}Das Logging überwiegt die Geschäftslogik, und es wird schlimmer:
- Die Domänenklasse hängt von einem Logger ab. Ein Konto braucht keinen, um Geld zu verwahren. Jeder Konstruktoraufruf und jeder Test übergibt jetzt einen.
- Derselbe Block wird in jede wichtige Methode kopiert. Die Kopien driften auseinander: andere Meldungen, andere Kontextschlüssel, ein vergessener Fehlerzweig.
- Geheimnisse sickern durch. Eine Kopie, die alle Argumente loggt, loggt auch die PIN.
Das Logging-Behavior
Abschnitt betitelt „Das Logging-Behavior“Das Logging wandert in eine einzige Behavior-Klasse. Die Methoden, die es brauchen, werden mit einem Attribut markiert.
1. Das Attribut
Abschnitt betitelt „1. Das Attribut“namespace App\Attribute;
use Attribute;
#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]final readonly class Loggable {}Ein schlichter Marker, ohne Abhängigkeit vom Framework. Er kann an einer Methode stehen oder an einer Klasse (siehe Eine ganze Klasse loggen).
2. Die Methoden markieren
Abschnitt betitelt „2. Die Methoden markieren“use App\Attribute\Loggable;
final class Account{ public function __construct(private int $balance = 0) {}
#[Loggable] public function deposit(int $amount): void { $this->balance += $amount; }
#[Loggable] public function withdraw(int $amount, #[\SensitiveParameter] string $pin): void { if ($amount > $this->balance) { throw new InsufficientFunds($this->balance, $amount); } $this->balance -= $amount; }}Die Logger-Abhängigkeit ist verschwunden, und das Attribut sagt trotzdem jedem Leser, dass diese Aufrufe geloggt werden. withdraw() erwartet jetzt eine PIN, markiert mit dem PHP-eigenen #[\SensitiveParameter].
3. Die Behavior-Klasse
Abschnitt betitelt „3. Die Behavior-Klasse“namespace App\Aspect;
use Go\Aop\Aspect;use Go\Aop\Intercept\MethodInvocation;use Go\Lang\Attribute\Around;use Psr\Log\LoggerInterface;
final class LoggingAspect implements Aspect{ public function __construct(private readonly LoggerInterface $logger) {}
#[Around('@execution(App\Attribute\Loggable)')] public function log(MethodInvocation $invocation): mixed { $context = ['method' => (string) $invocation, 'arguments' => $this->arguments($invocation)]; $this->logger->info('Entering {method}', $context);
try { $result = $invocation->proceed(); $this->logger->info('Finished {method}', $context);
return $result; } catch (\Throwable $exception) { $this->logger->error('Failed {method}: {message}', $context + [ 'message' => $exception->getMessage(), 'exception' => $exception, ]);
throw $exception; } }
/** @return array<string, mixed> */ private function arguments(MethodInvocation $invocation): array { $values = $invocation->getArguments(); $named = []; foreach ($invocation->getMethod()->getParameters() as $i => $parameter) { $hidden = $parameter->getAttributes(\SensitiveParameter::class) !== []; $named[$parameter->name] = $hidden ? '[hidden]' : ($values[$i] ?? null); }
return $named; }}#[Around] umschließt die Methode, und @execution(App\Attribute\Loggable) wählt jede Methode aus, die das Attribut trägt. Im Inneren:
(string) $invocationbenennt den Aufruf, zum Beispielexecution(App\Bank\Account->withdraw()).arguments()ordnet jedes Argument seinem Parameternamen zu und verbirgt Parameter, die mit#[\SensitiveParameter]markiert sind. Es ist eine private Hilfsmethode ohne Behavior-Attribut und damit selbst kein Behavior.proceed()führt die ursprüngliche Methode aus. Ein Fehler wird geloggt und erneut geworfen, Aufrufer sehen also genau die Exception, die sie vorher gesehen haben. Das Behavior fängt\Throwable, sodass auch Errors geloggt werden, nicht nur Exceptions.
4. Die Behavior-Klasse registrieren
Abschnitt betitelt „4. Die Behavior-Klasse registrieren“use App\Aspect\LoggingAspect;use Go\Core\AspectContainer;use Go\Core\AspectKernel;use Psr\Log\LoggerInterface;
final class AppKernel extends AspectKernel{ protected function configureAop(AspectContainer $container): void { $container->addLazyService( LoggingAspect::class, static fn(AspectContainer $c) => new LoggingAspect($c->getService(LoggerInterface::class)), ); }}Jeder PSR-3-Logger funktioniert, Monolog eingeschlossen. Der Logger kommt aus Ihrem Anwendungscontainer, sobald dieser mit setDelegate() angebunden ist (siehe Abhängigkeiten). Mit der Bridge für Symfony, Laravel oder Yii3 ist die Behavior-Klasse ein per Autowiring erzeugter Service, und dieser Schritt entfällt (Integrationen).
Was Sie bekommen
Abschnitt betitelt „Was Sie bekommen“$account = new Account(100);$account->deposit(50);$account->withdraw(500, '1234');[info] Entering execution(App\Bank\Account->deposit()) {"amount":50}[info] Finished execution(App\Bank\Account->deposit()) {"amount":50}[info] Entering execution(App\Bank\Account->withdraw()) {"amount":500,"pin":"[hidden]"}[error] Failed execution(App\Bank\Account->withdraw()): Insufficient funds: balance 150, requested 500 {"amount":500,"pin":"[hidden]"}- Domänenklassen bleiben sauber. Kein Logger im Konstruktor, kein
try/catchfürs Logging, und Tests erzeugen die Klasse wie zuvor. - Ein Format überall. Meldungen, Kontextschlüssel und der Fehlerzweig werden einmal geschrieben, in
LoggingAspect. - Geheimnisse bleiben draußen. Die PIN erreicht den Logger nie.
- Es funktioniert an jeder Methode. Auch private,
finalund statische Methoden kompilierter Klassen lassen sich loggen; siehe Intercept anything.
Eine ganze Klasse loggen
Abschnitt betitelt „Eine ganze Klasse loggen“Wenn jede öffentliche Methode einer Klasse geloggt werden soll, setzen Sie das Attribut an die Klasse und erweitern die Regel:
#[Around('@execution(App\Attribute\Loggable) || (@within(App\Attribute\Loggable) && execution(public **->*(*)))')]public function log(MethodInvocation $invocation): mixed#[Loggable]final class Transfers{ public function send(string $to, int $amount): Receipt { /* logged */ }
private function fee(int $amount): int { /* not logged */ }}@within(App\Attribute\Loggable) allein wählt jedes Member der markierten Klasse aus, Properties eingeschlossen. Die zweite Hälfte, execution(public **->*(*)), schränkt das auf öffentliche Methoden ein. Weitere Kombinationen finden Sie unter Matching-Rules.
Varianten
Abschnitt betitelt „Varianten“- Nur Fehler. Ein
#[AfterThrowing]-Behavior erhält die Exception und läuft nur, wenn die Methode eine wirft. Siehe AfterThrowing. - Zeitmessung. Messen Sie
hrtime(true)umproceed()herum und loggen Sie die Dauer, wie im Beispiel zur Behavior-Klasse. - Log-Level pro Methode. Geben Sie dem Attribut eine Property, zum Beispiel
#[Loggable(level: LogLevel::DEBUG)], und lesen Sie sie mit$invocation->getMethod()->getAttributes(Loggable::class)aus, so wie das Caching-Behavior seine Lebensdauer ausliest.
© 2026 Alexander Lisachenko
