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/