Пакет · logger

Справочник API

Каждый публичный класс и метод в Winter Logger. Все типы живут в пространстве имён Flytachi\Winter\Logger.

LoggerManager

Строит и кэширует по одному каналу Monolog на запись конфига. Иммутабелен на уровне конфига — методы with* возвращают новые экземпляры. Каждый построенный канал автоматически получает ContextInjectingProcessor.

Конструктор

php

new LoggerManager(
  ContextStorage $contextStorage,
  array          $channels = []
)

Параметр	Тип	По умолчанию	Описание
`$contextStorage`	`ContextStorage`	—	Изоляция контекста под рантайм (`ProcessContext` / `CoroutineContext`).
`$channels`	`array<string, array>`	`[]`	Конфиги каналов по имени канала. См. Конфиг канала.

Методы

Метод	Возвращает	Описание
`channel(string $name)`	`LoggerInterface`	Лениво строит и кэширует логгер канала. Бросает `InvalidArgumentException`, если `$name` не настроен. Возвращает `NullLogger`, если Monolog отсутствует.
`hasChannel(string $name)`	`bool`	Зарегистрирован ли `$name`.
`contextStorage()`	`ContextStorage`	Текущее хранилище контекста.
`withContextStorage(ContextStorage $s)`	`self`	Новый менеджер, те же каналы, другое хранилище.
`withChannel(string $name, array $config)`	`self`	Новый менеджер с добавленным или переопределённым каналом.
`flush()`	`void`	Сбрасывает все закэшированные экземпляры каналов; пересоберутся лениво при следующем `channel()`.

Лениво и с кэшем

channel() строит экземпляр Monolog при первом вызове и кэширует его; последующие вызовы возвращают тот же объект. flush() очищает этот кэш — полезно после перезагрузки конфига в демоне.

LoggerFactory

Статический Java-подобный фасад. Не инстанцируется. Хранит активный менеджер, канал по умолчанию (изначально 'cli') и поклассовый кэш логгеров по ключу "channel:FQCN".

Методы настройки

Метод	Возвращает	Описание
`setManager(LoggerManager $m)`	`void`	Регистрирует менеджер. Вызывать один раз на бутстрапе. Очищает кэш.
`setDefaultChannel(string $ch)`	`void`	Задаёт канал, используемый когда канал не указан. Очищает кэш.
`setContextStorage(ContextStorage $s)`	`void`	Подменяет хранилище на текущем менеджере (те же каналы). Очищает кэш.
`addChannel(string $name, array $cfg)`	`void`	Добавляет/переопределяет канал на текущем менеджере. Очищает кэш.
`reset()`	`void`	Очищает только поклассовый кэш логгеров.

Методы доступа

php

getLogger(string|object $class, ?string $channel = null): LoggerInterface

Логгер на класс. $class может быть строкой FQCN, константой ::class или объектом (используется его класс). Кэшируется по "channel:FQCN".

Если $channel задан и зарегистрирован → используется он.
Если $channel равен null или не зарегистрирован → откат к каналу по умолчанию (без исключения).
Отрисовывает (ShortName) в строке; хранит полный FQCN в context['class'].

Метод	Возвращает	Описание
`channel(string $name)`	`LoggerInterface`	Сырой логгер канала, без метки класса. Бросает, если `$name` не зарегистрирован.
`logger()`	`LoggerInterface`	Сырой логгер текущего канала по умолчанию (используется `Log`).
`contextStorage()`	`ContextStorage`	Хранилище контекста текущего менеджера.

getLogger откатывается, channel — нет

getLogger($c, 'missing') молча использует канал по умолчанию. channel('missing') бросает InvalidArgumentException. Неинициализированная фабрика (setManager не вызывался) бросает RuntimeException.

Log

Статический фасад — однострочный шорткат к каналу по умолчанию через LoggerFactory::logger(). Не инстанцируется, метка класса не прикрепляется.

Метод	Сигнатура
`Log::debug`	`(string $message, array $context = []): void`
`Log::info`	`(string $message, array $context = []): void`
`Log::notice`	`(string $message, array $context = []): void`
`Log::warning`	`(string $message, array $context = []): void`
`Log::error`	`(string $message, array $context = []): void`
`Log::critical`	`(string $message, array $context = []): void`
`Log::alert`	`(string $message, array $context = []): void`

Нет Log::emergency

Фасад Log покрывает уровни от debug до alert. Для уровня emergency используйте экземпляр логгера — например, LoggerFactory::logger()->emergency(...) или getLogger(self::class)->emergency(...), это полноценные PSR-3-логгеры.

Logger

PSR-3-обёртка, возвращаемая менеджером и фабрикой. Реализует Flytachi\Winter\Logger\Contracts\LoggerInterface (расширяющий Psr\Log\LoggerInterface). Вливает привязанный контекст в каждый вызов.

Конструктор

php

new Logger(
  \Monolog\Logger  $monolog,
  ContextStorage   $contextStorage,
  array            $boundContext = []
)

Методы

Метод	Возвращает	Описание
`withContext(array $context)`	`static`	Новый логгер с `$context`, влитым в каждый вызов. Не мутирует исходный.
`log(mixed $level, string\|Stringable $message, array $context = [])`	`void`	PSR-3-лог. Привязанный контекст вливается под `context` вызова (при конфликте ключей побеждает вызов).
`monolog()`	`\Monolog\Logger`	Нижележащий экземпляр Monolog (чтобы навесить процессоры/обработчики).

Плюс все шорткаты уровней PSR-3 (debug, info, notice, warning, error, critical, alert, emergency) через трейт LoggerTrait из Monolog.

php

$log = LoggerFactory::getLogger(self::class)->withContext(['request_id' => $id]);
$log->info('processing');   // несёт request_id

ContextStorage

Интерфейс контекста на единицу исполнения. Пространство имён Flytachi\Winter\Logger\Contracts.

Метод	Возвращает	Описание
`set(string $key, mixed $value)`	`void`	Сохранить поле.
`get(string $key, mixed $default = null)`	`mixed`	Прочитать поле.
`all()`	`array`	Снимок всех полей.
`forget(string $key)`	`void`	Удалить одно поле.
`clear()`	`void`	Удалить все поля. Вызывать в конце каждого запроса/задачи/корутины.

ProcessContext

Один плоский массив на процесс. Безопасен для FPM (запрос = процесс) и разовых CLI-задач. В демонах-циклах — clear() между итерациями. Небезопасен для Swoole.

CoroutineContext

Хранит контекст в Swoole\Coroutine::getContext() — один мешок на корутину, автоматически уничтожаемый при её завершении. Откатывается к статическому массиву вне корутины (бутстрап, onWorkerStart). Требует ext-swoole. См. Корутины Swoole.

Процессоры

Пространство имён Flytachi\Winter\Logger\Processor. Оба реализуют ProcessorInterface из Monolog.

ContextInjectingProcessor

Добавляется к каждому каналу автоматически. Вливает снимок ContextStorage в extra каждой записи. Раннее завершение (нулевая нагрузка), когда контекст не задан.

php

new ContextInjectingProcessor(ContextStorage $storage)

SensitiveMaskingProcessor

Опционален. Скрывает чувствительные ключи (регистронезависимо, рекурсивно) в context и extra, заменяя значения на ***.

php

new SensitiveMaskingProcessor(array $extraKeys = [])

$extraKeys объединяются со значениями по умолчанию. См. Маскируемые ключи и Маскирование данных.

Фабрики

Пространство имён Flytachi\Winter\Logger\Factory.

HandlerFactory

php

HandlerFactory::make(array $config): \Monolog\Handler\HandlerInterface

Отображает output на обработчик: stdout/stderr → SafeStreamHandler, syslog → SyslogHandler, file → RotatingFileHandler, null → NullHandler. Бросает InvalidArgumentException при неизвестном output или при output=file без file_path.

FormatterFactory

php

FormatterFactory::make(string $format, bool $appendNewline = true): \Monolog\Formatter\FormatterInterface

'line' → SpringLineFormatter, 'json' → JsonFormatter из Monolog (режим построчной пачки). Передайте $appendNewline = false для syslog (он сам обрамляет сообщения). Бросает InvalidArgumentException при неизвестном формате.

Обработчик и форматтер

SafeStreamHandler (Flytachi\Winter\Logger\Handler) — расширяет StreamHandler из Monolog; переопределяет streamWrite(), чтобы использовать @fwrite и никогда не бросать на разорванном потоке. См. Вывод и broken pipe.
SpringLineFormatter (Flytachi\Winter\Logger\Formatter) — однострочный формат в стиле Spring Boot. Конструктор: new SpringLineFormatter(bool $appendNewline = true). См. Формат логов.