PSR-3 日志接口

Psr-3.jpg

日志接口

本文制定了日志类库的通用接口规范。

本规范的主要目的是允许库接收一个 Psr\Log\LoggerInterface 对象，并以一种简单而且通用的方式将日志写入其中。有需要的框架和 CMS 系统可以 继承这个接口进行扩展，但 应该 遵循本规范。以确保应用程序使用这个第三方库时能够集中化地写入应用程序日志。

文档中的 implementor 一词可以理解为在与日志相关的库或框架中实现 LoggerInterface 的人。日志记录器的用户称为 user。

1. 详述(Specification)

1.1. 基本规范

• LoggerInterface 接口对外定义了八个方法，分别用来记录 RFC 5424 中定义的八个等级的日志：debug, info, notice,warning, error, critical, alert, emergency。

• 第九个方法 —— log 接收日志级别作为第一个参数。使用某个日志级别常量调用 log 方法 必须 要与直接调用此特定级别方法得到相同的结果。若使用这种以日志级别常量作参数的方式调用 log 方法，如果传入的日志级别常量参数没有预先定义，则 必须 抛出一个 Psr\Log\InvalidArgumentException 异常。在不确定当前接口实现是否支持该日志级别的情况下， 用户 不应该 使用自定义的日志级别。

1.2 消息(Message)

• LoggerInterface 接口的每一个方法接受一个字符串作为消息，或者一个带有 __toString() 方法的对象。实现者 可以 对传的对象进行特殊处理。如果不是这样，实现者( implementors )必须将其转换为字符串。

• 消息参数 可以 携带占位符，实现者 可以 用上下文数组中的值替换这些占位符。

其中占位符的名称 必须 与上下文数组的键名保持一致。

占位符的名称 必须 由一个开始花括号 { 与 一个结束花括号 } 包围着。并且花括号与占位符名称之间 一定不可 有任何空格。

占位符的名称 应该 只由 A-Z 、 a-z 、 0-9 、下划线 _ 以及英文的句号 . 组成，其它字符用作将来占位符规范的保留。

实现者( implementors ) 可以 使用占位符来实现各种转义策略并翻译日志以供显示。用户(users) 在不知道数据将在哪个上下文中显示的情况下， 不该 预转义占位符的值。

举一个占位符使用的例子：

<?php

/**
 *  将上下文值插入到消息占位符中
 */
function interpolate($message, array $content = array())
{
    // 构建一个花括号包含的键名的替换数组
    $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');

// 输出 "Username bolivar created"
echo interpolate($message, $context);

1.3. 上下文(Context)

• LoggerInterface 的每一个函数都接受一个上下文数组参数。用来装载字符串类型无法表示的信息。它 可以 装载任何信息。实现者(implementors) 必须 确保尽可能宽松的处理上下文数据，上下文中的给定值 一定不可 抛出任何异常，也不能引发任何 PHP 的错误、警告或 提醒信息。

• 如需通过上下文参数传入一个 Exception 对象，必须 以 exception 作为键名。记录异常信息是很普遍的，如果它能够在记录类库的底层实现，就能够让实现者从异常信息中抽丝剥茧。实现者在使用它时，必须 确保键名为 exception 的键值是否真的是一个 Exception，毕竟它 可以 装载任何信息。

1.4. 助手类和接口

• Psr\Log\AbstractLogger 助手类使你只需继承它和实现其中的 log 方法，就能够很轻易地实现 LoggerInterface 接口，而另外八个方法就能够把记录信息和上下文信息传给它。

• 同样地，使用 Psr\Log\LoggerTrait 也只需实现其中的 log 方法。注意，由于 traits 不能实现接口，在这种情况下，您仍然必须实现 LoggerInterface。

• Psr\Log\NullLogger 连同接口 Psr\Log\LoggerInterface 一起提供。如果没有提供日志记录程序，接口的用户可以使用它来提供回退的「黑洞」实现。但是，如果上下文数据创建的开销很大，那么条件日志记录可能是更好的方法。

• Psr\Log\ LoggerAwareInterface 只包含一个 setLogger(LoggerInterface $logger) 方法，框架可以使用该方法自动将任意实例与一个 logger 连接起来。

• Psr\Log\LoggerAwareTrait trait 可复用代码块可以在任何的类里面使用，只需要通过它提供的 $this->logger ，就可以轻松地实现等同的接口。

• Psr\Log\LogLevel 类装载了八个记录等级常量。

2. 包(Package)

接口和类的描述、相关的异常类以及用于验证你所写代码的测试套件都将作为 psr/log 包的一部分提供。

3. Psr\Log\LoggerInterface

<?php

namespace Psr\Log;

/**
 * 描述一个日志记录器实例
 *
 * 该消息必须实现一个__toString()的字符串或者对象.
 *
 * 该消息可能包含以下形式的占位符: {foo}  
 * foo 将会被关键词 "foo"中的上下文数据替换.
 *
 * 上下文数组可以包含任意数据, 我们只能假设代码实现者
 * 如果给出一个生成堆栈跟踪的异常实例, 那么它的键名
 * 必须为 "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());

    /**
     * 临界条件。
     *
     * 例如: 应用组件不可用，意外的异常。
     *
     * @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());

    /**
     * 可任意级别记录日志。
     *
     * @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;

/**
 * logger-aware 定义实例
 */
interface LoggerAwareInterface
{
    /**
     * 设置一个日志记录实例
     *
     * @param LoggerInterface $logger
     * @return void
     */
    public function setLogger(LoggerInterface $logger);
}

5. Psr\Log\LogLevel

<?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';
}

---

真正了解 PSR-3 还需要更多的在编程中实践

鉴于我是第一次了解 PSR-3 ，暂时只作认识和记录

后面我会尽量多做一些知识复盘。

---

参考文献

psr/log Package: https://packagist.org/packages/psr/log

GitHub: https://github.com/php-fig/fig-standards

php-fig： https://www.php-fig.org/psr/

社区翻译： https://learnku.com/docs/psr