「PSR 规范」PSR-3 日志接口规范

日志接口规范


本文制定了日志类库的通用接口规范。
本规范的主要目的,是为了让日志类库以简单通用的方式,通过接收一个 Psr\Log\LoggerInterface 对象,来记录日志信息。框架以及 CMS 管理系统如有需要, 可以 对此接口进行扩展,这才能在保证使用第三方类库的文件时,日志接口仍能正常对接。

关于「能愿动词」的使用


为了避免歧义,文档使用了大量的 「能愿动词」,对应的解释如下:

  • 必须(MUST):绝对,严格遵循,请照做,无条件遵守;
  • 一定不可(MUST NOT):禁令,严令禁止;
  • 应该(SHOULD):强烈建议这样做,但不强求;
  • 不该(SHOULD NOT):强烈建议不要这样做,但不强求;
  • 可以(MAY)可选(OPTIONAL):选择性较高,在这个文档内,此词语使用较少;

1.规范说明


1.1基本规范

  • LoggerInterface RFC 5424 接口对外定义了八个方法,分别用来记录中定义的八个等级的日志:debug、info、notice、warning、error、critical、alter 和 emergency。
  • 第九个方法—— log,其第一个参数为记录的等级。可使用一个预先定义的等级常量作为参数来调用此方法, 必须 与直接调用以上八个方法具有相同的效果。如果传入的等级常量参数没有预先定义,则 必须 抛出 Psr\Log\InvalidArgumentException 类型的异常。在不确定的情况下,使用者 不该 使用未支持的等级常量来调用此方法。

1.2记录信息

  • 以上每个方法都接受一个字符串类型或者有 __toString() 方法的对象作为记录信息参数,这样,实现者就能把它当成字符串来处理,否则实现者 必须 自己把它转换成字符串。
  • 记录信息参数 可以 携带占位符,实现者 可以 根据上下文将其他替换成相应的值。
    其中占位符 必须 与上下文数组中的键保持一致。
    占位符的名称 必须 由一个左花括号 { 以及一个右花括号 } 包含。但花括号与名称之间 一定不可 有空格符。
    占位符的名称 应该 只有 A-Za-z0-9、下划线 _ 以及英文的句号 . 组成,其他字符作为将来占位符规范的保留。
    实现者 可以 通过对占位符采用不同的转义和转换策略,来生成最终的日志。而使用者在不知道上下文的前提下,不该 提前转义占位符。
    以下是占位符使用的一个例子:
/**
 * 用上下文信息替换记录信息中的占位符
 */
function interpolate($message, array $content = array ())
{
    //构建一个花括号包含的键名的替换数组
    $replace = array();
    foreach ($content as $key => $val) {
        $replace['{' . $key . '}'] = $val;
    }
    //替换记录中信息中的占位符,最后返回修改后的记录信息
    return strtr($message, $replace);
}

//含有带花括号占位符的记录信息
$message = "User {username} created";

//带有替换信息的上下文数组,键名为占位符名称,键值为替换值。
$content = array('username' => 'bolivar');

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

1.3上下文

  • 每个记录函数都接受一个上下文数组参数,用来装载字符串类型无法表示的信息。它 可以 装载任何信息,对于其装载的数据,一定不可 抛出异常,或产生 PHP 错误、警告或提醒信息(error、warning、notice)。
  • 如需通过上下文参数传入了一个 Exception 对象,必须exception 作为键名。记录异常信息是很普遍的,所以如果他能够在记录类库的底层实现,就能够让实现者从异常信息中抽丝剥茧。当然,实用者在使用它时,必须 确保键名为 exception 的键值是否是一个真的 Exception,毕竟它可以装载任何信息。

1.4助手类和接口

  • Psr\Log\AbstractLogger 使得只需继承它和实现其中的 log 方法,就能够很轻易的实现 LoggerInterface 接口,而另外八个方法就能够吧记录信息和上下文信息传给它。
  • 同样的,使用 Psr\Log\LoggerTrait 也只需实现其中的 log 方法。不过,需要特别注意的是,在 trait 可复用代码块还不能实现接口前,还需要 implement LoggerInterface
  • 在没有可用的日志记录器时, Psr\Log\NullLogger 接口 可以 为使用者提供一个备用的日志 「黑洞」。不过,当上下文的构建非常消耗资源时,带条件检查的日志记录或许是更好的办法。
  • Psr\Log\LoggerAwareInterface 接口仅包括一个 setLogger(LoggerInterface $logger) 方法,框架 可以 使用它实现自动连接任意的日志记录实例。
  • Psr\Log\LoggerAwareTrait trait 可复用代码块可以在任何的类里面使用,只需通过它提供的 $this->logger,就可以轻松的实现等同的接口。
  • Psr\Log\LogLevel 类装载了八个记录等级常量。

2.包


上述的接口、类和相关的异常类,以及一系列的实现检测文件,都包含在 psr/log 文件包中。

3. Psr\Log\LoggerInterface


<?php
/**
 *日志记录实例
 *
 * 日志信息变量—— message,**必须** 是一个字符串或是实现了 __toString() 方法的对象
 *
 * 日志信息变量中 **可以** 包含如 “{foo}” (代表 foo) 的占位符,
 * 它将会有上下文数组中键名为 「foo」的键值替代。
 *
 * 它将会由上下文数组可以携带任意的数据,唯一的限制是,当它携带的是一个 exception 对象时,它的键名必须是 "exception"
 *
 * 详情可参阅:https://github.com/PizzaLiu/PHP-FIG/blob/master/PSR-3-logger-interface-cn.md
 */
interface LoggerInterface
{
    /**
      * 系统不可用
      *
      * @param string $message
      * @param array $context
      * @return null
      */
public function emergency($message, array $context = array());

/**
  *    **必须** 立刻采取行动
  * 
  * 例如:在整个网站都垮掉了、数据库不可用了或其他的情况下, **应该** 发送一条警报信息把你叫醒。
  *
  * @param string $message
  * @param array $context
  * @return null
  */
public function alter($message, array $context = array());

/**
  * 紧急情况
  *
  * 例如 :程序组件不可用或出现非预期的异常
  *
  * @param string $message
  * @param array $context
  * @return null
  */
public function critical($message, array $context = arraay());

/**
  * 运行时出现的错误,不需要立刻采取行动,但必须记录下来以备检测。
  * 
  * @param string $message
  * @param array $context
  * @return null
  */
public function error($message, array $context = array());

/**
  * 出现非错误性的异常。
  *
  * 例如:使用了被弃用的 API、错误的使用了 API 或非预想的不必要错误。
  *
  * @param string $message
  * @param array $context
  * @return null
  */
public function warning($message, array $context = array());

/**
  * 一般性重要的事件。
  * 
  * @param string $message
  * @param array $context
  * @return null
   */
public function notice($message, array $context = array());

/**
  * 重要事件。
  *
  * 例如:用户登录和 sql 记录
  *
  * @param string $message
  * @param array $context
  * @return null
   */
public function info($message, array $context = array());

/**
  * debug 详情
  *
  * @param string $message
  * @param array $context
  * @return null
   */
punlic function debug($message, array $context = array());

/**
  * 任意等级的日志记录
  * 
  * @param mixed $level
  * @param string $message
  * @param array $context
  * @return null
   */
public function log($level, $message, array $context = array());

}

4.Psr\Log\LoggerAwareInterface

<?php
namespace Psr\Log;

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

5.Psr\Log\LogLevel

<?php

namespace Psr\Log;

/**
  * 日志等级常量定义
  */
class Loglevel
{
    const ENERGENCY = 'emergency';
    const ALTER = 'alter';
    const CRITICAL = 'critical';
    const ERROR = 'error';
    const WARNING = 'warning';
    const NOTICE= 'notice';
    const INFO = 'info';
    const DEBUG = 'debug';
}
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 216,744评论 6 502
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 92,505评论 3 392
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 163,105评论 0 353
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 58,242评论 1 292
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 67,269评论 6 389
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 51,215评论 1 299
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 40,096评论 3 418
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 38,939评论 0 274
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 45,354评论 1 311
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 37,573评论 2 333
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 39,745评论 1 348
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 35,448评论 5 344
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 41,048评论 3 327
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 31,683评论 0 22
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 32,838评论 1 269
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 47,776评论 2 369
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 44,652评论 2 354

推荐阅读更多精彩内容

  • 日志接口规范 本文制定了日志类库的通用接口规范。 本规范的主要目的,是为了让日志类库以简单通用的方式,通过接收一个...
    f09037cb27f7阅读 1,034评论 0 0
  • 日志接口规范 本文制定了日志类库的通用接口规范。 本规范的主要目的,是为了让日志类库以简单通用的方式,通过接收一个...
    零一间阅读 595评论 0 0
  • 日志接口 本文制定了日志类库的通用接口规范。 本规范的主要目的是允许库接收一个 Psr\Log\LoggerInt...
    DragonsLong阅读 773评论 0 1
  • 什么是PSR? PSR是PHP Standards Recommendation的简称,这个是php-fig[ht...
    正义的程序员阅读 47,340评论 4 34
  • 日志规范 1、日志级别 我们使用4个日志级别,分别为DEBUG、INFO、WARN、ERROR DEBUG:可以将...
    阿福德阅读 831评论 0 0