Перейти к содержимому
Документация

Логирование вызовов

Логируйте вызовы методов, результаты и сбои одним атрибутом. Поведение #[Loggable] с логгером PSR-3, которое держит код логирования и зависимость от логгера вне ваших доменных классов.

Перевод с английского. Эталоном считается английская версия страницы. Читать оригинал

Клиент сообщает, что снятие денег не прошло, и никто не может сказать почему. Ответ должен быть в логах, но если вручную логировать каждый важный метод, бизнес-логика тонет в этом коде. На этой странице логирование переезжает в behavior (поведение): вы помечаете метод атрибутом #[Loggable], и фреймворк выполняет логирование как middleware (промежуточный слой) вокруг него. Слова behavior class (класс поведений), behavior и matching rule (правило выбора) объяснены в таблице терминов.

Банковский счёт с двумя операциями:

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

Полезная стратегия логирования: писать одну строку, когда метод начинается, и одну, когда он заканчивается. Начало без конца указывает на сбой, даже если процесс упал и ни один блок catch не выполнился. Вручную это выглядит так:

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
}

Логирования здесь больше, чем бизнес-логики, и дальше становится только хуже:

  • Доменный класс зависит от логгера. Счёту логгер не нужен, чтобы хранить деньги. Теперь его передают в каждый вызов конструктора и в каждый тест.
  • Один и тот же блок копируется в каждый важный метод. Копии расходятся: разные сообщения, разные ключи контекста, забытая ветка для сбоя.
  • Утекают секреты. Копия, которая логирует все аргументы, заодно логирует и PIN-код.

Логирование переезжает в один behavior class. Методы, которым оно нужно, помечаются атрибутом.

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

Простой маркер, не зависящий от фреймворка. Его можно поставить на метод или на класс (см. Логирование всего класса).

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

Зависимости от логгера больше нет, а атрибут по-прежнему сообщает каждому читателю, что эти вызовы логируются. Теперь withdraw() принимает PIN-код, помеченный встроенным в PHP атрибутом #[\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] оборачивает метод, а @execution(App\Attribute\Loggable) выбирает каждый метод с этим атрибутом. Внутри:

  • (string) $invocation даёт имя вызова, например execution(App\Bank\Account->withdraw()).
  • arguments() сопоставляет каждый аргумент с именем его параметра и скрывает параметры, помеченные #[\SensitiveParameter]. Это приватный вспомогательный метод без атрибута behavior, поэтому сам он behavior не является.
  • proceed() выполняет исходный метод. Сбой логируется, а исключение выбрасывается снова, так что вызывающий код видит ровно то же исключение, что и раньше. Behavior перехватывает \Throwable, поэтому логируются и ошибки, а не только исключения.
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)),
);
}
}

Подойдёт любой логгер PSR-3, включая Monolog. Логгер берётся из контейнера вашего приложения, как только тот подключён через setDelegate() (см. Зависимости). С мостом (bridge) для Symfony, Laravel или Yii3 behavior class становится автоматически связываемым (autowired) сервисом, и этот шаг исчезает (Интеграции).

$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]"}
  • Доменные классы остаются чистыми. Никакого логгера в конструкторе, никаких try/catch ради логирования, а тесты создают класс как раньше.
  • Один формат везде. Сообщения, ключи контекста и ветка для сбоя написаны один раз — в LoggingAspect.
  • Секреты не утекают. PIN-код никогда не попадает в логгер.
  • Работает на любом методе. Логировать можно и приватные, final и статические методы скомпилированных классов; см. Intercept anything.

Если логировать нужно каждый публичный метод класса, поставьте атрибут на класс и расширьте правило:

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) само по себе выбирает все члены помеченного класса, включая свойства. Вторая половина, execution(public **->*(*)), сужает выбор до публичных методов. Другие комбинации — в разделе Matching rules.

  • Только сбои. Behavior с #[AfterThrowing] получает исключение и выполняется, только когда метод его выбрасывает. См. AfterThrowing.
  • Время выполнения. Замерьте hrtime(true) вокруг proceed() и залогируйте длительность, как в примере behavior class.
  • Уровни логирования для отдельных методов. Добавьте атрибуту свойство, например #[Loggable(level: LogLevel::DEBUG)], и прочитайте его через $invocation->getMethod()->getAttributes(Loggable::class) — так же, как behavior со страницы Кеширование результатов читает время жизни.

© 2026 Alexander Lisachenko