Behavior de logging
Registre em log chamadas de métodos, resultados e falhas com um único atributo. Um behavior #[Loggable] com um logger PSR-3 que mantém o código de logging e a dependência do logger fora das suas classes de domínio.
Traduzido do inglês. A página em inglês é a referência. Ler o original
Um cliente diz que um saque falhou, e ninguém consegue dizer por quê. A resposta deveria estar nos logs, mas fazer logging à mão em todo método importante soterra a lógica de negócio. Esta página leva o logging para um behavior (comportamento): você marca um método com #[Loggable], e o framework roda o logging como middleware em torno dele. Os termos behavior class (classe de comportamento), behavior e matching rule (regra de correspondência) são explicados na tabela de termos.
O problema
Seção intitulada “O problema”Uma conta bancária com duas operações:
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; }}Uma estratégia de log útil: escrever uma linha quando um método começa e outra quando termina. Um início sem fim aponta para a falha, mesmo quando o processo morre e nenhum bloco catch roda. Feito à mão, fica assim:
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}O logging pesa mais que a lógica de negócio, e fica pior:
- A classe de domínio depende de um logger. Uma conta não precisa de um para guardar dinheiro. Toda chamada do construtor e todo teste agora precisam passar um.
- O mesmo bloco é copiado em todo método importante. As cópias vão divergindo: mensagens diferentes, chaves de contexto diferentes, um ramo de falha esquecido.
- Segredos vazam. Uma cópia que registra todos os argumentos registra também o PIN.
O behavior de logging
Seção intitulada “O behavior de logging”O logging vai para uma behavior class. Os métodos que precisam dele são marcados com um atributo.
1. O atributo
Seção intitulada “1. O atributo”namespace App\Attribute;
use Attribute;
#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]final readonly class Loggable {}Um marcador simples, sem dependência do framework. Pode ir num método ou numa classe (veja Logging de uma classe inteira).
2. Marque os métodos
Seção intitulada “2. Marque os métodos”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; }}A dependência do logger sumiu, e o atributo continua dizendo a quem lê que essas chamadas são registradas em log. withdraw() agora recebe um PIN, marcado com o #[\SensitiveParameter] do próprio PHP.
3. A behavior class
Seção intitulada “3. A 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] envolve o método, e @execution(App\Attribute\Loggable) seleciona todo método que tem o atributo. Por dentro:
(string) $invocationdá nome à chamada, por exemploexecution(App\Bank\Account->withdraw()).arguments()associa cada argumento ao nome do seu parâmetro e oculta os parâmetros marcados com#[\SensitiveParameter]. É um helper privado sem atributo de behavior, então não é um behavior.proceed()roda o método original. Uma falha é registrada e relançada, então quem chama vê exatamente a mesma exceção de antes. O behavior captura\Throwable, então os errors também são registrados, não só as exceptions.
4. Registre a behavior class
Seção intitulada “4. Registre a 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)), ); }}Qualquer logger PSR-3 serve, inclusive o Monolog. O logger vem do container da sua aplicação depois que ele é ligado com setDelegate() (veja Dependências). Com a bridge de Symfony, Laravel ou Yii3, a behavior class é um serviço com autowiring e este passo desaparece (Integrações).
O que você ganha
Seção intitulada “O que você ganha”$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]"}- As classes de domínio ficam limpas. Nada de logger no construtor, nada de
try/catchpara logging, e os testes constroem a classe como antes. - Um só formato em todo lugar. Mensagens, chaves de contexto e o ramo de falha são escritos uma vez, em
LoggingAspect. - Os segredos ficam de fora. O PIN nunca chega ao logger.
- Funciona em qualquer método. Métodos privados,
finale estáticos de classes compiladas também podem ser registrados em log; veja Intercept anything.
Logging de uma classe inteira
Seção intitulada “Logging de uma classe inteira”Quando todo método público de uma classe deve ser registrado em log, coloque o atributo na classe e amplie a regra:
#[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) sozinho seleciona todo membro da classe marcada, inclusive as propriedades. A segunda metade, execution(public **->*(*)), restringe a seleção aos métodos públicos. Mais combinações em Matching rules.
Variações
Seção intitulada “Variações”- Só falhas. Um behavior
#[AfterThrowing]recebe a exceção e roda só quando o método lança uma. Veja AfterThrowing. - Tempo de execução. Meça
hrtime(true)em torno deproceed()e registre a duração, como no exemplo de behavior class. - Nível de log por método. Dê uma propriedade ao atributo, por exemplo
#[Loggable(level: LogLevel::DEBUG)], e leia-a com$invocation->getMethod()->getAttributes(Loggable::class), como o behavior de cache lê o seu tempo de vida.
© 2026 Alexander Lisachenko
