Ir al contenido
Documentación

Behavior de logging

Registra en el log las llamadas a métodos, sus resultados y sus fallos con un solo atributo. Un behavior #[Loggable] con un logger PSR-3 que mantiene el código de logging y las dependencias del logger fuera de tus clases de dominio.

Traducido del inglés. La página en inglés es la referencia. Leer el original

Un cliente dice que una retirada de fondos falló, y nadie sabe explicar por qué. La respuesta debería estar en los logs, pero registrar a mano cada método importante entierra la lógica de negocio. Esta página traslada el logging a un behavior (comportamiento): marcas un método con #[Loggable] y el framework ejecuta el logging como middleware a su alrededor. Los términos behavior class (clase de comportamiento), behavior y matching rule (regla de coincidencia) se explican en la tabla de términos.

Una cuenta bancaria con dos operaciones:

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

Una estrategia de log útil: escribir una línea cuando un método empieza y otra cuando termina. Un inicio sin final señala el fallo, incluso cuando el proceso muere y no llega a ejecutarse ningún bloque catch. Hecho a mano, queda así:

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
}

El logging pesa más que la lógica de negocio, y la cosa empeora:

  • La clase de dominio depende de un logger. Una cuenta no necesita uno para guardar dinero. Cada llamada al constructor y cada test tienen que pasárselo.
  • El mismo bloque se copia en cada método importante. Las copias se van distanciando: mensajes distintos, claves de contexto distintas, una rama de fallo olvidada.
  • Se filtran secretos. Una copia que registra todos los argumentos registra también el PIN.

El logging va a una sola behavior class. Los métodos que lo necesitan se marcan con un atributo.

src/Attribute/Loggable.php
namespace App\Attribute;
use Attribute;
#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
final readonly class Loggable {}

Un simple marcador, sin dependencia del framework. Puede ir en un método o en una clase (consulta Registra una clase entera).

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

La dependencia del logger ha desaparecido, y el atributo sigue diciendo a quien lea el código que estas llamadas se registran. withdraw() recibe ahora un PIN, marcado con el propio #[\SensitiveParameter] de 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] envuelve el método, y @execution(App\Attribute\Loggable) selecciona todos los métodos que llevan el atributo. Por dentro:

  • (string) $invocation nombra la llamada, por ejemplo execution(App\Bank\Account->withdraw()).
  • arguments() empareja cada argumento con el nombre de su parámetro y oculta los parámetros marcados con #[\SensitiveParameter]. Es un helper privado sin atributo de behavior, así que no es un behavior en sí.
  • proceed() ejecuta el método original. Un fallo se registra y se vuelve a lanzar, así que quien llama ve exactamente la misma excepción que veía antes. El behavior captura \Throwable, así que también se registran los errores, no solo las excepciones.
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)),
);
}
}

Sirve cualquier logger PSR-3, Monolog incluido. El logger sale del contenedor de tu aplicación una vez conectado con setDelegate() (consulta Dependencias). Con el bridge de Symfony, Laravel o Yii3, la behavior class es un servicio con autowiring y este paso desaparece (Integraciones).

$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]"}
  • Las clases de dominio quedan limpias. Sin logger en el constructor, sin try/catch para el logging, y los tests construyen la clase como antes.
  • Un único formato en todas partes. Los mensajes, las claves de contexto y la rama de fallo se escriben una sola vez, en LoggingAspect.
  • Los secretos se quedan fuera. El PIN nunca llega al logger.
  • Funciona en cualquier método. También se pueden registrar los métodos privados, final y estáticos de las clases compiladas; consulta Intercept anything.

Cuando hay que registrar todos los métodos públicos de una clase, pon el atributo en la clase y amplía la regla:

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) por sí solo selecciona todos los miembros de la clase marcada, propiedades incluidas. La segunda mitad, execution(public **->*(*)), lo restringe a los métodos públicos. Hay más combinaciones en Matching rules.

  • Solo los fallos. Un behavior #[AfterThrowing] recibe la excepción y solo se ejecuta cuando el método la lanza. Consulta AfterThrowing.
  • Tiempos. Mide hrtime(true) alrededor de proceed() y registra la duración, como en el ejemplo de behavior class.
  • Niveles de log por método. Dale una propiedad al atributo, por ejemplo #[Loggable(level: LogLevel::DEBUG)], y léela con $invocation->getMethod()->getAttributes(Loggable::class), igual que el behavior de caché lee su tiempo de vida.

© 2026 Alexander Lisachenko