RUEN
Пакет · logger

Logger

Winter Logger — это PSR-3-логгер, рассчитанный на каждый рантайм, куда вы деплоите: PHP-FPM, Swoole и CLI. Он оборачивает Monolog безопасным для корутин контекстом запроса, читаемым однострочным форматом в стиле Spring Boot и Java-подобной статической фабрикой — и при этом ничего не знает о вашей инфраструктуре.

Философия

  • Не зависит от инфраструктуры — библиотека никогда не читает env-переменные, не определяет Docker, не проверяет SAPI и не ищет Swoole. Всё это решает фреймворк и передаёт готовый конфиг. Так логгер остаётся переносимым и тривиально тестируемым.
  • Monolog опционален — без установленного monolog/monolog каждый логгер молча становится PSR-3-совместимым NullLogger. Ни исключений, ни предупреждений — логирование просто выключается.
  • Безопасный для рантайма контекст — поля уровня запроса (request_id, user_id, …) никогда не протекают между конкурентными запросами, потому что хранилище контекста выбирается под рантайм.

Ключевые понятия

  • LoggerManager — строит и кэширует по одному каналу Monolog на каждую запись конфига.
  • LoggerFactory — статическая Java-подобная фасад-фабрика: getLogger(MyClass::class) возвращает именованный логгер на класс, кэшируемый по классу.
  • Log — однострочный статический шорткат к каналу по умолчанию.
  • ContextStorage — абстракция, изолирующая контекст запроса (ProcessContext для FPM/CLI, CoroutineContext для Swoole).

Ключевые возможности

  • Совместимость с PSR-3 — подставляется везде, где ожидается Psr\Log\LoggerInterface.
  • Логгеры на класс — getLogger(UserService::class) выводит (UserService) в строке и хранит полный FQCN в контексте для запросов в системах агрегации логов.
  • Контекст уровня запроса — задайте request_id один раз, и он появится в каждой строке автоматически.
  • Изоляция корутин — CoroutineContext привязывает контекст к корутине Swoole, так что конкурентные запросы никогда не смешиваются.
  • Устойчивость к broken pipe — SafeStreamHandler никогда не роняет FPM-воркер, если клиент отключился посреди записи.
  • Маскирование чувствительных данных — опциональный процессор скрывает пароли, токены и прочее.
  • Два формата — читаемый однострочный и JSON с разделением по строкам для агрегаторов.

Хорошо подходит для

Любого сервиса Winter, которому нужно исполнять один и тот же код в FPM, на сервере Swoole и в CLI-воркерах — с единым API логирования, контекстом запроса, следующим за каждым запросом, и выводом, который читается в терминале, но при этом машинно-разбираем в проде.

Требования

  • PHP ≥ 8.3
  • psr/log ^3.0
  • monolog/monolog ^3.5 — рекомендуется; без него каждый логгер — молчаливый NullLogger
  • ext-swoole (или ext-openswoole) — опционально; только для CoroutineContext

Установка

bash
composer require flytachi/winter-logger monolog/monolog

Быстрый старт

Соберите менеджер, зарегистрируйте его один раз и логируйте откуда угодно:

php
use Flytachi\Winter\Logger\LoggerFactory;

LoggerFactory::getLogger(UserService::class)->info('user created', ['id' => 42]);
text
[2024-01-01 12:00:00] [INFO ] -http- [4821] (UserService): user created {"id":42,"class":"App\\Service\\UserService"}

Пройдите весь путь целиком — от установки до живой строки лога с контекстом запроса за пять минут — в Быстром старте.

Исходники и ссылки

Продолжайте с Установки и требований, Быстрого старта и Ментальной модели.