Behavior de journalisation
Journalisez les appels de méthodes, leurs résultats et leurs échecs avec un seul attribut. Un behavior #[Loggable] avec un logger PSR-3, qui garde le code de journalisation et les dépendances au logger hors de vos classes métier.
Traduit de l’anglais. La page anglaise fait référence. Lire l’original
Un client signale qu’un retrait a échoué, et personne ne sait dire pourquoi. La réponse devrait se trouver dans les logs, mais journaliser à la main chaque méthode importante noie la logique métier. Cette page déplace la journalisation dans un behavior (comportement) : vous marquez une méthode avec #[Loggable], et le framework exécute la journalisation comme middleware autour d’elle. Les termes behavior class (classe de comportement), behavior et matching rule (règle de correspondance) sont expliqués dans le tableau des termes.
Le problème
Section intitulée « Le problème »Un compte bancaire avec deux opérations :
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; }}Une stratégie de log utile : écrire une ligne au début d’une méthode et une autre à la fin. Un début sans fin désigne l’échec, même quand le processus meurt et qu’aucun bloc catch ne s’exécute. Écrit à la main, cela donne ceci :
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}La journalisation pèse plus lourd que la logique métier, et la situation empire :
- La classe métier dépend d’un logger. Un compte n’en a pas besoin pour détenir de l’argent. Chaque appel du constructeur et chaque test doit désormais lui en passer un.
- Le même bloc est recopié dans chaque méthode importante. Les copies divergent : messages différents, clés de contexte différentes, branche d’échec oubliée.
- Les secrets fuient. Une copie qui journalise tous les arguments journalise aussi le code PIN.
Le behavior de journalisation
Section intitulée « Le behavior de journalisation »La journalisation va dans une seule behavior class. Les méthodes qui en ont besoin sont marquées par un attribut.
1. L’attribut
Section intitulée « 1. L’attribut »namespace App\Attribute;
use Attribute;
#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]final readonly class Loggable {}Un simple marqueur, sans aucune dépendance au framework. Il peut se placer sur une méthode ou sur une classe (voir Journaliser toute une classe).
2. Marquer les méthodes
Section intitulée « 2. Marquer les méthodes »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; }}La dépendance au logger a disparu, et l’attribut indique toujours à chaque lecteur que ces appels sont journalisés. withdraw() prend maintenant un code PIN, marqué avec l’attribut natif de PHP #[\SensitiveParameter].
3. La behavior class
Section intitulée « 3. La behavior class »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] enveloppe la méthode, et @execution(App\Attribute\Loggable) sélectionne toutes les méthodes qui portent l’attribut. À l’intérieur :
(string) $invocationnomme l’appel, par exempleexecution(App\Bank\Account->withdraw()).arguments()associe chaque argument au nom de son paramètre et masque les paramètres marqués#[\SensitiveParameter]. C’est une méthode d’aide privée sans attribut de behavior : ce n’est donc pas elle-même un behavior.proceed()exécute la méthode d’origine. Un échec est journalisé puis relancé : les appelants voient exactement la même exception qu’avant. Le behavior intercepte\Throwable: les erreurs sont donc journalisées elles aussi, pas seulement les exceptions.
4. Enregistrer la behavior class
Section intitulée « 4. Enregistrer la behavior class »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)), ); }}N’importe quel logger PSR-3 convient, Monolog compris. Le logger vient du conteneur de votre application, une fois celui-ci rattaché avec setDelegate() (voir Dépendances). Avec le bridge Symfony, Laravel ou Yii3, la behavior class est un service autowiré et cette étape disparaît (Intégrations).
Ce que vous y gagnez
Section intitulée « Ce que vous y gagnez »$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]"}- Les classes métier restent propres. Pas de logger dans le constructeur, pas de
try/catchpour journaliser, et les tests construisent la classe comme avant. - Un seul format partout. Les messages, les clés de contexte et la branche d’échec sont écrits une seule fois, dans
LoggingAspect. - Les secrets restent à l’écart. Le code PIN n’atteint jamais le logger.
- Cela fonctionne sur n’importe quelle méthode. Les méthodes privées,
finalet statiques des classes compilées peuvent elles aussi être journalisées ; voir Intercept anything.
Journaliser toute une classe
Section intitulée « Journaliser toute une classe »Quand toutes les méthodes publiques d’une classe doivent être journalisées, placez l’attribut sur la classe et étendez la règle :
#[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) seul sélectionne tous les membres de la classe marquée, propriétés comprises. La seconde moitié, execution(public **->*(*)), restreint la sélection aux méthodes publiques. D’autres combinaisons sont décrites dans Matching rules.
Variantes
Section intitulée « Variantes »- Uniquement les échecs. Un behavior
#[AfterThrowing]reçoit l’exception et ne s’exécute que lorsque la méthode en lève une. Voir AfterThrowing. - Mesure du temps. Mesurez
hrtime(true)autour deproceed()et journalisez la durée, comme dans l’exemple de behavior class. - Un niveau de log par méthode. Donnez une propriété à l’attribut, par exemple
#[Loggable(level: LogLevel::DEBUG)], et lisez-la avec$invocation->getMethod()->getAttributes(Loggable::class), comme le behavior de mise en cache lit sa durée de vie.
© 2026 Alexander Lisachenko
