PSR-3 日志接口

2019-03-26  本文已影响0人  DragonsLong
Psr-3.jpg

日志接口

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

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

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

1. 详述(Specification)

1.1. 基本规范

1.2 消息(Message)

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

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

占位符的名称 应该 只由 A-Za-z0-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)

1.4. 助手类和接口

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

上一篇 下一篇

猜你喜欢

热点阅读