Zum Inhalt springen
Dokumentation

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.

Ein Bankkonto mit zwei Operationen:

src/Bank/Account.php
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:

src/Bank/Account.php
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 wandert in eine einzige Behavior-Klasse. Die Methoden, die es brauchen, werden mit einem Attribut markiert.

src/Attribute/Loggable.php
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).

src/Bank/Account.php
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].

src/Aspect/LoggingAspect.php
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) $invocation benennt den Aufruf, zum Beispiel execution(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.
src/AppKernel.php
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).

$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/catch fü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, final und statische Methoden kompilierter Klassen lassen sich loggen; siehe Intercept anything.

Wenn jede öffentliche Methode einer Klasse geloggt werden soll, setzen Sie das Attribut an die Klasse und erweitern die Regel:

src/Aspect/LoggingAspect.php
#[Around('@execution(App\Attribute\Loggable) || (@within(App\Attribute\Loggable) && execution(public **->*(*)))')]
public function log(MethodInvocation $invocation): mixed
src/Bank/Transfers.php
#[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.

  • 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) um proceed() 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