Logger Interface 日志接口

翻译自：http://www.php-fig.org/psr/psr-3/

本文档描述了一个适用于日志库的通用接口。

主要目标是让广大PHP项目可以简单并且统一的依赖 Psr\Log\LoggerInterface 接口的对象来写日志。框架和CMS们可以根据自己的需要扩展这个接口，但应该要保持对本文档的兼容。这样可以保证使用第三方库的应用可以使用中心化的日志。

The key words "MUST 必须", "MUST NOT 必须不", "REQUIRED 需要", "SHALL 将要", "SHALL NOT 将不", "SHOULD 应该", "SHOULD NOT不应该", "RECOMMENDED 推荐的", "MAY 可以", and "OPTIONAL 可选的" in this document are to be interpreted as described in .

在本文档中 implementor 实现者 这个词意味LoggerInterface 走某个日志相关的框架或库中的实现。 user 用户即日志的使用者。

1. 规范

1.1 基础

LoggerInterface 暴露了8个方法，对应RFC 5424的 8个日志级别。

第9个方法－ log, 可以接受日志级别作为第一个参数传入。调用这个方法和调另外八个方法的效果必须是一样的。调用这个方法如果传入的级别是未定义的，必须抛出Psr\Log\InvalidArgumentException . 用户不应该使用一个当前实现不支持的自定义级别。

1.2 消息Message

每个方法都接收一个字符串或具有__toString()魔术方法的对象作为消息。实现者可以对传入的对象进行特殊处理，否则实现者必须把对象转为字符串。

消息可以包含实现者可从上下文数组替换数据的占位符。

占位符名称必须和上下文数组的Key保持一致。

占位符必须使用{ }括起来。占位符名和花括号之间必不能有空格。

占位符名应该只由这些字符组成： A-Z, a-z, 0-9, _, .. 其他字符的使用有可能在将来的规范中加入规范。

实现者可以使用占位符实现各种转义和显示转换。用户不应该预先转义将要体会占位符的变量。

以下是一个占位符替换的实现的例子，供参考：

/** * 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) {
       $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 上下文 Context

日志接口的每一个方法都可以接收一个数组作为上下文。他可以表示任何不宜直接放在字符串中的信息。这个数组可以包含任何信息。实现者必须宽容的对待上下文中的数据。上下文中的值必须不能抛出异常或触发任何报错。

如果上下文传入一个 Exception 对象, 必须使用 'exception' key. 记录异常有通用的形式，如果日志的底层能够支持，实现者可以从众抽取出stack trace。实现者必须验证'exception' key 确为异常类型。

1.4 Helper classes and interfaces 助手类和接口

通过继承 Psr\Log\AbstractLogger 类并实现log方法，让你可以轻松实现 LoggerInterface 。

类似的，使用 Psr\Log\LoggerTrait 也可以让你只需要实现 log方法. 注意使用Trait并不能让你成为LoggerInterface的子类，你仍然需要实现LoggerInterface.

Psr\Log\NullLogger 和接口一起提供. 它可以让使用者（库、框架）等在没有具体日志实现的时候使用黑洞（啥也不干）模式。不过如果上线文数据创建成本较高，选择性的记录日志可能是更好的办法。

Psr\Log\LoggerAwareInterface 只包含了一个 setLogger(LoggerInterface $logger)方法，可以让框架任意装配日志实例。

Psr\Log\LoggerAwareTrait 可以在实现上述接口的类中使用. 它帮助你访问 $this->logger.

Psr\Log\LogLevel class 定义了8个日志级别的常量

2. 包 Package

接口、类（包括相关异常类）和测试你的实现的测试用例，均作为 package的一部分来提供。.

3. `Psr\Log\LoggerInterface`

4. `Psr\Log\LoggerAwareInterface`

5. `Psr\Log\LogLevel`

转载于:https://my.oschina.net/bigbigant/blog/385030

你可能感兴趣的文章