PSR-3. Общий интерфейс для ЛОГИРОВАНИЯ.

Данная статья, это авторский перевод, описания стандарта. С оригиналом описания Вы можете ознакомиться здесь.

Этот документ описывает общий интерфейс для библиотек логирования.

Основная цель — позволить библиотекам получать Psr\Log\LoggerInterface объект и записывать в нем логи простым и универсальным способом. Фреймворки и CMS, имеющие пользовательские потребности, МОГУТ расширять интерфейс для своих собственных целей, но ДОЛЖНЫ оставаться совместимыми с этим документом. Это гарантирует, что сторонние библиотеки, используемые приложением, могут записывать в централизованные общие логи приложения.

Встречающиеся ключевые слова «ДОЛЖЕН», «НЕ ДОЛЖЕН», «ТРЕБУЕТСЯ», «СЛЕДУЕТ», «НЕ СЛЕДУЕТ», «РЕКОМЕНДУЕТСЯ», «МОЖЕТ» и «ОПЦИОНАЛЬНО» в данном стандарте интерпретируются как описано в документе RFC 2119.

Слово implementor («реализатор», «имплементор») в текущем документе следует понимать, как любую сущность, реализующую интерфейс LoggerInterface, описываемый ниже. Например, такими «сущностями» могут являться библиотеки для логирования.

1. Спецификация.

1.1 Основы.

  • В LoggerInterface устанавливаются восемь способов логирования сообщений, что соотносится с уровнями, установленными здесь 5424 RFC. 8 уровней: debug, info, notice, warning, error, critical, alert, emergency (отладки, информация, уведомление, предупреждение, ошибка, критический, предупреждение, чрезвычайный). Этим 8 уровням соответствуют 8 методов.
  • Девятый метод log() принимает в качестве первого аргумента уровень логирования. Вызов этого метода с передачей константы одного из уровней логирования, ДОЛЖЕН приводить к тому же результату, что и вызов соответствующего специального метода логирования. Пользователям НЕ СЛЕДУЕТ использовать собственные уровни логирования, не зная наверняка, что текущая реализация его поддерживает.

1.2. Сообщения для логирования.

  • Каждый метод логирования в качестве аргумента для сообщения принимает строку или объект с методом __toString (). Реализаторы МОГУТ иметь специальную обработку для пропущенных объектов. Если это не так, разработчики ДОЛЖНЫ преобразовывать его в строку.
  • Сообщение МОЖЕТ содержать плейсхолдеры, которые реализаторы МОГУТ заменить на значения из массива контекста.

Имена плейсхолдеров ДОЛЖНЫ соответствовать ключам в массиве контекста.

Имена плейсхолдеров ДОЛЖНЫ быть разделены одной открывающей скобкой { и одной закрывающей скобкой }. НЕ ДОЛЖНО быть пробелов между разделителями и именем плейсхолдера.

Имена плейсхолдеров ДОЛЖНЫ состоять только из символов A-Z, a-z, 0-9, подчеркивания _ . Использование других символов зарезервировано для будущих модификаций спецификации заполнителей.

Реализаторы МОГУТ использовать плейсхолдеры для реализации различных стратегий экранирования и перевода журналов для отображения. Пользователям НЕ СЛЕДУЕТ предварительно избегать значений заполнителей, поскольку они не могут знать, в каком контексте будут отображаться данные.

Ниже приведен пример реализации плейсхолдера, предоставленный только для справочных целей:

$val) { // Проверка, что значение может быть приведено к строке. if (!is_array($val) && (!is_object($val) || method_exists($val, '__toString'))) { $replace['{' . $key . '}'] = $val; } } // Подстановка значений в сообщение и возврат результата. return strtr($message, $replace); } // Сообщение с плейсхолдером, имя которого заключено в фигурные скобки. $message = "User {username} created"; // Массив контекста, вида: Имя плейсхолдера => Значение для замены. $context = array('username' => 'bolivar'); // В результате выполнения функции выведется: "User bolivar created" echo interpolate($message, $context);

1.3. Контекст.

  • Каждый метод принимает массив в качестве данных контекста. Это предназначено для хранения любой посторонней информации, которая не вписывается в строку. Массив может содержать все что угодно. Реализаторы ДОЛЖНЫ гарантировать, что они обрабатывают контекстные данные с максимально возможной аккуратностью. Заданное значение в контексте НЕ ДОЛЖНО вызывать исключение и не выдавать никаких ошибок php, предупреждений или уведомлений.
  • Если объект Exception передается в данные контекста, он ДОЛЖЕН быть в значении ключа ‘exception’.  Логирование исключений является распространенным шаблоном, и это позволяет разработчикам извлекать трассировку стека из исключения, когда лог бэкенда поддерживает его. Имплементоры ДОЛЖНЫ проверять, что ключ ‘exception’ на самом деле является ключом, содержащим Exception прежде чем использовать его, поскольку он МОЖЕТ содержать любое другое значение.

1.4. Вспомогательные Классы и Интерфейсы.

  • Класс Psr\Log\AbstractLogger позволяет очень легко реализовать интерфейс LoggerInterface за счет расширения и реализации общего метода log(). Остальные восемь методов для логирования различных уровней, пересылают сообщения и контекст в этот метод.
  • Аналогично, использование трейта Psr\Log\LoggerTrait требует реализовать универсальный метод log(). Обратите внимание, что поскольку трейты не могут реализовывать интерфейсы, в этом случае вам все равно придется реализовать LoggerInterface.
  • Класс Psr\Log\NullLogger предоставляется вместе с интерфейсом. Он МОЖЕТ использоваться пользователями интерфейса для реализации «черной дыры». Тем не менее, условное ведение журнала может быть лучшим подходом, если создание данных контекста стоит дорого.
  • Класс Psr\Log\LoggerAwareInterface содержит только метод setLogger(LoggerInterface $logger) и может быть использован фреймворками для автоматического создания и передачи экземпляров классов Логгера.
  • Трейт Psr\Log\LoggerAwareTrait может быть использован для реализации эквивалентного интерфейса в любом классе. Этот трейт предоставит доступ к свойству $this->logger.
  • Класс Psr\Log\LogLevel содержит константы для восьми уровней логирования.

2. Пакет из composer.

Описанные интерфейсы и классы, а также соответствующие классы исключений и наборы тестов для проверки вашей реализации предоставляются как часть пакета psr / log , доступного в composer .

3. Интерфейс Psr\Log\LoggerInterface.

4. Интерфейс Psr\Log\LoggerAwareInterface.

5. Класс Psr\Log\LogLevel.

Добавить комментарий

Ваш адрес email не будет опубликован.