PSR-3: Интерфейс логирования

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

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

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

Слово implementorв этом документе следует интерпретировать как кто-то, реализующий LoggerInterfaceв связанной с журналом библиотеке или фреймворке. Пользователи логгеров называются user.

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

1.1 Основы

Предоставляет LoggerInterfaceвосемь методов записи журналов на восемь уровней RFC 5424 (отладка, информация, уведомление, предупреждение, ошибка, критическое, предупреждение, аварийное).
Девятый метод logпринимает уровень журнала в качестве первого аргумента. Вызов этого метода с одной из констант уровня журнала ДОЛЖЕН иметь тот же результат, что и вызов метода, зависящего от уровня. Вызов этого метода с уровнем, не определенным в этой спецификации, ДОЛЖЕН вызывать, Psr\Log\InvalidArgumentException если реализация не знает об уровне. Пользователи НЕ ДОЛЖНЫ использовать настраиваемый уровень, не зная наверняка, что текущая реализация поддерживает его.

1.2 Сообщение

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

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

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

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

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

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

/**
 * Interpolates context values into the message placeholders.
 */
function interpolate($message, array $context = array())
{
    // build a replacement array with braces around the context keys
    $replace = array();
    foreach ($context as $key => $val) {
        // check that the value can be cast to string
        if (!is_array($val) && (!is_object($val) || method_exists($val, '__toString'))) {
            $replace['{' . $key . '}'] = $val;
        }
    }

    // interpolate replacement values into the message and return
    return strtr($message, $replace);
}

// a message with brace-delimited placeholder names
$message = "User {username} created";

// a context array of placeholder names => replacement values
$context = array('username' => 'bolivar');

// echoes "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. Пакет

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

3. `Psr\Log\LoggerInterface`

<?php

namespace Psr\Log;

/**
 * Describes a logger instance.
 *
 * The message MUST be a string or object implementing __toString().
 *
 * The message MAY contain placeholders in the form: {foo} where foo
 * will be replaced by the context data in key "foo".
 *
 * The context array can contain arbitrary data, the only assumption that
 * can be made by implementors is that if an Exception instance is given
 * to produce a stack trace, it MUST be in a key named "exception".
 *
 * See https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md
 * for the full interface specification.
 */
interface LoggerInterface
{
    /**
     * System is unusable.
     *
     * @param string $message
     * @param array $context
     * @return void
     */
    public function emergency($message, array $context = array());

    /**
     * Action must be taken immediately.
     *
     * Example: Entire website down, database unavailable, etc. This should
     * trigger the SMS alerts and wake you up.
     *
     * @param string $message
     * @param array $context
     * @return void
     */
    public function alert($message, array $context = array());

    /**
     * Critical conditions.
     *
     * Example: Application component unavailable, unexpected exception.
     *
     * @param string $message
     * @param array $context
     * @return void
     */
    public function critical($message, array $context = array());

    /**
     * Runtime errors that do not require immediate action but should typically
     * be logged and monitored.
     *
     * @param string $message
     * @param array $context
     * @return void
     */
    public function error($message, array $context = array());

    /**
     * Exceptional occurrences that are not errors.
     *
     * Example: Use of deprecated APIs, poor use of an API, undesirable things
     * that are not necessarily wrong.
     *
     * @param string $message
     * @param array $context
     * @return void
     */
    public function warning($message, array $context = array());

    /**
     * Normal but significant events.
     *
     * @param string $message
     * @param array $context
     * @return void
     */
    public function notice($message, array $context = array());

    /**
     * Interesting events.
     *
     * Example: User logs in, SQL logs.
     *
     * @param string $message
     * @param array $context
     * @return void
     */
    public function info($message, array $context = array());

    /**
     * Detailed debug information.
     *
     * @param string $message
     * @param array $context
     * @return void
     */
    public function debug($message, array $context = array());

    /**
     * Logs with an arbitrary level.
     *
     * @param mixed $level
     * @param string $message
     * @param array $context
     * @return void
     */
    public function log($level, $message, array $context = array());
}

4. `Psr\Log\LoggerAwareInterface`

<?php

namespace Psr\Log;

/**
 * Describes a logger-aware instance.
 */
interface LoggerAwareInterface
{
    /**
     * Sets a logger instance on the object.
     *
     * @param LoggerInterface $logger
     * @return void
     */
    public function setLogger(LoggerInterface $logger);
}

5. `Psr\Log\LogLevel`

<?php

namespace Psr\Log;

/**
 * Describes log levels.
 */
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';
}