Skip to content

Метадокумент логгера

1. Резюме

Интерфейс регистратора определяет общий интерфейс для регистрации системных сообщений из приложения или библиотеки.

Этот метадокумент был написан задним числом, поскольку PSR-3 изначально был принят до того, как метадокументы стали стандартной практикой.

2. Дизайнерские решения

Статические сообщения журнала

Цель этой спецификации состоит в том, чтобы сообщение, передаваемое методу регистрации, всегда было статическим значением. Любая зависящая от контекста изменчивость (например, имя пользователя, отметка времени или другая информация) должна предоставляться только через массив $context, а строка должна использовать заполнитель для ссылки на нее.

Цель этого дизайна двояка. Во-первых, сообщение становится доступным для систем перевода для создания локализованных версий сообщений журнала. Во-вторых, данные, зависящие от контекста, могут содержать пользовательский ввод и, следовательно, требуют экранирования. Это экранирование обязательно будет другим, если сообщение журнала хранится в базе данных для последующего рендеринга в HTML, сериализуется в JSON, сериализуется в строку сообщения системного журнала и т. д. Реализация ведения журнала отвечает за то, чтобы данные $context, отображаемые пользователю, были соответствующим образом экранированы.

3 человека

3.1 Редактор(ы)

  • Хорди Богджано

4. Голоса

Голосование

5. Исправления

5.1 Добавление типов

Версия 2.0 пакета psr/log включает скалярные типы параметров. Версия пакета 3.0 включает возвращаемые типы. Эта структура использует поддержку ковариации PHP 7.2, чтобы обеспечить постепенный процесс обновления, но требует PHP 8.0 для совместимости типов.

Разработчики МОГУТ добавлять типы возвращаемых значений в свои пакеты по своему усмотрению при условии, что:

  • типы возврата совпадают с типами в пакете 3.0.
  • реализация указывает минимальную версию PHP 8.0.0 или более позднюю.

Разработчики МОГУТ добавлять типы параметров в свои собственные пакеты в новом основном выпуске либо одновременно с добавлением возвращаемых типов, либо в последующем выпуске, при условии, что:

  • типы параметров соответствуют типам в пакете 2.0.
  • реализация указывает минимальную версию PHP 8.0.0 или более позднюю.
  • реализация зависит от "psr/log": "^2.0 || ^3.0", чтобы исключить нетипизированную версию 1.0.

Разработчики поощряются, но не обязаны переводить свои пакеты на версию 3.0 при первой же возможности.