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) 在不知道数据将在哪个上下文中显示的情况下， 不该 预转义占位符的值。

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

 $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

4. Psr\Log\LoggerAwareInterface

5. Psr\Log\LogLevel

---

真正了解 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