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

PSR (PHP Standards Recommendations) - это набор рекомендаций по программированию на языке PHP.
PSR-3 - этот стандарт позволяет библиотекам получать Psr\Log\LoggerInterface объект и записывать в него логи простым и универсальным способом. Фреймворки и CMS, имеющие индивидуальные потребности, могут расширять интерфейс для своих целей, но должны оставаться совместимыми с этим интерфейсом. Это гарантирует, что сторонние библиотеки, используемые приложением, смогут записывать данные в централизованные журналы приложений.

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

1.1 Основы

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

1.2 Сообщение

Каждый метод принимает строку в качестве сообщения или объект с методом __toString(). Разработчики могут иметь специальную обработку для переданных объектов. Если это не так, разработчики должны привести его к строке.
Сообщение может содержать псевдоэлементы (placeholders), которые разработчики могут заменить значениями из массива контекстов.

Имена псевдоэлементов должны соответствовать ключам в массиве контекстов.

Имена псевдоэлементов должны быть разделены одной открывающей { и одной закрывающей скобкой }. Между разделителями и именем псевдоэлемента не должно быть пробелов.

Имена псевдоэлементов должны состоять только из символов 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\LoggerTraitonly требует реализации универсального log метода. Обратите внимание: поскольку трейты (traits) не могут реализовывать интерфейсы, в этом случае вам все равно придется реализовать 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';
}

Ссылка на источник: https://www.php-fig.org/psr/psr-3/

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

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

1.1 Основы

1.2 Сообщение

1.3 Контекст

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

2. Пакет

3. Psr\Log\LoggerInterface

4. Psr\Log\LoggerAwareInterface

5. Psr\Log\LogLevel

Предыдущая статья:

Следующая статья:

Комментарии: