Pular para o conteúdo
Documentação

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.

Uma conta bancária com duas operações:

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;
}
}

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:

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
}

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 logging vai para uma behavior class. Os métodos que precisam dele são marcados com um atributo.

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

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;
}
}

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.

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] envolve o método, e @execution(App\Attribute\Loggable) seleciona todo método que tem o atributo. Por dentro:

  • (string) $invocation dá nome à chamada, por exemplo execution(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.
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)),
);
}
}

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).

$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/catch para 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, final e estáticos de classes compiladas também podem ser registrados em log; veja Intercept anything.

Quando todo método público de uma classe deve ser registrado em log, coloque o atributo na classe e amplie a regra:

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) 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.

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