Логирование вызовов
Логируйте вызовы методов, результаты и сбои одним атрибутом. Поведение #[Loggable] с логгером PSR-3, которое держит код логирования и зависимость от логгера вне ваших доменных классов.
Перевод с английского. Эталоном считается английская версия страницы. Читать оригинал
Клиент сообщает, что снятие денег не прошло, и никто не может сказать почему. Ответ должен быть в логах, но если вручную логировать каждый важный метод, бизнес-логика тонет в этом коде. На этой странице логирование переезжает в behavior (поведение): вы помечаете метод атрибутом #[Loggable], и фреймворк выполняет логирование как middleware (промежуточный слой) вокруг него. Слова behavior class (класс поведений), behavior и matching rule (правило выбора) объяснены в таблице терминов.
Банковский счёт с двумя операциями:
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 не выполнился. Вручную это выглядит так:
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 для логирования
Заголовок раздела «Behavior для логирования»Логирование переезжает в один behavior class. Методы, которым оно нужно, помечаются атрибутом.
1. Атрибут
Заголовок раздела «1. Атрибут»namespace App\Attribute;
use Attribute;
#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]final readonly class Loggable {}Простой маркер, не зависящий от фреймворка. Его можно поставить на метод или на класс (см. Логирование всего класса).
2. Помечаем методы
Заголовок раздела «2. Помечаем методы»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].
3. Behavior class
Заголовок раздела «3. 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] оборачивает метод, а @execution(App\Attribute\Loggable) выбирает каждый метод с этим атрибутом. Внутри:
(string) $invocationдаёт имя вызова, напримерexecution(App\Bank\Account->withdraw()).arguments()сопоставляет каждый аргумент с именем его параметра и скрывает параметры, помеченные#[\SensitiveParameter]. Это приватный вспомогательный метод без атрибута behavior, поэтому сам он behavior не является.proceed()выполняет исходный метод. Сбой логируется, а исключение выбрасывается снова, так что вызывающий код видит ровно то же исключение, что и раньше. Behavior перехватывает\Throwable, поэтому логируются и ошибки, а не только исключения.
4. Регистрация behavior class
Заголовок раздела «4. Регистрация 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)), ); }}Подойдёт любой логгер 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.
Логирование всего класса
Заголовок раздела «Логирование всего класса»Если логировать нужно каждый публичный метод класса, поставьте атрибут на класс и расширьте правило:
#[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) само по себе выбирает все члены помеченного класса, включая свойства. Вторая половина, 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
