В этом документе описывается общий интерфейс для библиотек регистрации.
Основная цель — разрешить библиотекам получать объект Psr\Log\LoggerInterface и записывать в него журналы простым и универсальным способом. Фреймворки и CMS, имеющие собственные потребности, МОГУТ расширять интерфейс для своих собственных целей, но ДОЛЖНЫ оставаться совместимыми с этим документом. Это гарантирует, что сторонние библиотеки, используемые приложением, могут записывать в централизованные журналы приложения.
Ключевые слова «ДОЛЖЕН», «НЕ ДОЛЖЕН», «ТРЕБУЕТСЯ», «ДОЛЖЕН», «НЕ ДОЛЖЕН», «РЕКОМЕНДУЕТСЯ», «МОЖЕТ» и «НЕОБЯЗАТЕЛЬНО» в этом документе следует толковать так, как описано в RFC 2119.
Слово «implementor» (реализаторы далее) в этом документе следует толковать как того, кто реализует LoggerInterface в библиотеке или фреймворке, связанных с журналами. Пользователи регистраторов называются пользователями (user).
1. Спецификация
1.1 Основы
LoggerInterface предоставляет восемь методов для записи журналов на восьми уровнях RFC 5424 (debug, info, notification, warning, error, critical, alert, emergency).
Метод, 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 требует только реализации универсального метода журнала. Обратите внимание, что поскольку черты не могут реализовывать интерфейсы, в этом случае вам все равно придется реализовать LoggerInterface.
Psr\Log\NullLogger предоставляется вместе с интерфейсом. Он МОЖЕТ использоваться пользователями интерфейса для предоставления резервной реализации «черной дыры» (fall-back "black hole"), если им не предоставлено средство ведения журнала. Однако условное ведение журнала может быть лучшим подходом, если создание контекстных данных требует больших затрат.
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';
}
