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


Deprecated: Function create_function() is deprecated in /home/worldhel/public_html/wp-content/plugins/codecolorer/lib/geshi.php on line 4698

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

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

Основная цель — позволить библиотекам получать 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, подчеркивания _ . Использование других символов зарезервировано для будущих модификаций спецификации заполнителей.

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
<?php

/**
 * Подстановка значений из контекста в плейсхолдеры логируемого сообщения
 */

function interpolate($message, array $context = array())
{
    // Построение массива подстановки с фигурными скобками вокруг значений ключей массива context.
    $replace = array();
    foreach ($context as $key => $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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
<?php

namespace Psr\Log;

/**
 * LoggerInterface описывает экземпляр логгера.
 *
 * Сообщение ДОЛЖНО быть строкой или объектом, реализующим метод __toString ().
 *
 * Сообщение МОЖЕТ содержать плейсхолдеры в форме: {foo}, где foo
 * будет заменено значением из массива контекста с ключом "foo".
 *
 * Массив контекста может содержать произвольные данные. Единственное условие,
 * делается в том случае, что если задан экземпляр Exception,
 * то он ДОЛЖЕН быть в ключе с именем «exception».
 *
 * Для знакомства с полной спецификацией интерфейса,
 * смотрите описание https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md
 */

interface LoggerInterface
{
    /**
     * Система не работает.
     *
     * @param string $message
     * @param array $context
     * @return void
     */

    public function emergency($message, array $context = array());

    /**
     * Требуется немедленные действия
     *
     * Например: вебсайт отключен, БД недоступна, и т.д.
     * Такой лог должен вызывать СМС оповещение и побуждать Вас к немедленным действиям.
     *
     * @param string $message
     * @param array $context
     * @return void
     */

    public function alert($message, array $context = array());

    /**
     * Критическая ситуация.
     *
     * Пример: недоступен компонент приложения, неожиданный Exception.
     *
     * @param string $message
     * @param array $context
     * @return void
     */

    public function critical($message, array $context = array());

    /**
     * Ошибка на стадии выполнения, не требующая немедленных действий,
     * но требующая быть залогированной и дальнейшего изучения.
     *
     * @param string $message
     * @param array $context
     * @return void
     */

    public function error($message, array $context = array());

    /**
     * Исключительные случаи, которые не являются ошибками.
     *
     * Пример: использование устаревших API, неверное использование API, другие нежелательные эффекты
     * такие случаи не всегда говорят, о неверной работе приложения.
     *
     * @param string $message
     * @param array $context
     * @return void
     */

    public function warning($message, array $context = array());

    /**
     * Нормальные события в работе приложения, но значимые и требуют логирования.
     *
     * @param string $message
     * @param array $context
     * @return void
     */

    public function notice($message, array $context = array());

    /**
     * Полезные значимые события.
     *
     * Пример: логи пользователей, логи SQL.
     *
     * @param string $message
     * @param array $context
     * @return void
     */

    public function info($message, array $context = array());

    /**
     * Подробная отладочная информация.
     *
     * @param string $message
     * @param array $context
     * @return void
     */

    public function debug($message, array $context = array());

    /**
     * Логи с произвольным уровнем.
     * В переменную $log передается нужный уровень логирования.
     *
     * @param mixed $level
     * @param string $message
     * @param array $context
     * @return void
     */

    public function log($level, $message, array $context = array());
}

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<?php

namespace Psr\Log;

/**
 * Описывает экземпляр, поддерживающий логирование
 */

interface LoggerAwareInterface
{
    /**
     * Устанавливает экземпляр логгера для объекта
     *
     * @param LoggerInterface $logger
     * @return void
     */

    public function setLogger(LoggerInterface $logger);
}

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<?php

namespace Psr\Log;

/**
 * Описывает уровни логирования
 */

class LogLevel
{
    const EMERGENCY = 'emergency';
    const ALERT     = 'alert';
    const CRITICAL  = 'critical';
    const ERROR     = 'error';
    const WARNING   = 'warning';
    const NOTICE    = 'notice';
    const INFO      = 'info';
    const DEBUG     = 'debug';
}

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

Ваш адрес email не будет опубликован. Обязательные поля помечены *