日志接口規(guī)范
本文制定了日志類庫的通用接口規(guī)范。
本規(guī)范的主要目的，是為了讓日志類庫以簡(jiǎn)單通用的方式，通過接收一個(gè) Psr\Log\LoggerInterface 對(duì)象，來記錄日志信息。
框架以及CMS內(nèi)容管理系統(tǒng)如有需要，可以 對(duì)此接口進(jìn)行擴(kuò)展，但需遵循本規(guī)范，
這才能保證在使用第三方的類庫文件時(shí)，日志接口仍能正常對(duì)接。
關(guān)于「能愿動(dòng)詞」的使用
為了避免歧義，文檔大量使用了「能愿動(dòng)詞」，對(duì)應(yīng)的解釋如下：
-
必須 (MUST)：絕對(duì)，嚴(yán)格遵循，請(qǐng)照做，無條件遵守； -
一定不可 (MUST NOT)：禁令，嚴(yán)令禁止； -
應(yīng)該 (SHOULD)：強(qiáng)烈建議這樣做，但是不強(qiáng)求； -
不該 (SHOULD NOT)：強(qiáng)烈不建議這樣做，但是不強(qiáng)求； -
可以 (MAY)和可選 (OPTIONAL)：選擇性高一點(diǎn)，在這個(gè)文檔內(nèi)，此詞語使用較少；
參見：RFC 2119
1. 規(guī)范說明
1.1 基本規(guī)范
LoggerInterface接口對(duì)外定義了八個(gè)方法，分別用來記錄 RFC 5424 中定義的八個(gè)等級(jí)的日志：debug、 info、 notice、 warning、 error、 critical、 alert 以及 emergency 。第九個(gè)方法 ——
log，其第一個(gè)參數(shù)為記錄的等級(jí)?？墒褂靡粋€(gè)預(yù)先定義的等級(jí)常量作為參數(shù)來調(diào)用此方法，必須 與直接調(diào)用以上八個(gè)方法具有相同的效果。如果傳入的等級(jí)常量參數(shù)沒有預(yù)先定義，則 必須 拋出Psr\Log\InvalidArgumentException類型的異常。在不確定的情況下，使用者 不該 使用未支持的等級(jí)常量來調(diào)用此方法。
1.2 記錄信息
以上每個(gè)方法都接受一個(gè)字符串類型或者是有
__toString()方法的對(duì)象作為記錄信息參數(shù)，這樣，實(shí)現(xiàn)者就能把它當(dāng)成字符串來處理，否則實(shí)現(xiàn)者 必須 自己把它轉(zhuǎn)換成字符串。-
記錄信息參數(shù) 可以 攜帶占位符，實(shí)現(xiàn)者 可以 根據(jù)上下文將其它替換成相應(yīng)的值。
其中占位符 必須 與上下文數(shù)組中的鍵名保持一致。
占位符的名稱 必須 由一個(gè)左花括號(hào)
{以及一個(gè)右括號(hào)}包含。但花括號(hào)與名稱之間 一定不可有空格符。占位符的名稱 應(yīng)該 只由
A-Z、a-z、0-9、下劃線_、以及英文的句號(hào).組成，其它字符作為將來占位符規(guī)范的保留。實(shí)現(xiàn)者 可以 通過對(duì)占位符采用不同的轉(zhuǎn)義和轉(zhuǎn)換策略，來生成最終的日志。
而使用者在不知道上下文的前提下，不該 提前轉(zhuǎn)義占位符。以下是一個(gè)占位符使用的例子：
/** * 用上下文信息替換記錄信息中的占位符 */ function interpolate($message, array $context = array()) { // 構(gòu)建一個(gè)花括號(hào)包含的鍵名的替換數(shù)組 $replace = array(); foreach ($context as $key => $val) { $replace['{' . $key . '}'] = $val; } // 替換記錄信息中的占位符，最后返回修改后的記錄信息。 return strtr($message, $replace); } // 含有帶花括號(hào)占位符的記錄信息。 $message = "User {username} created"; // 帶有替換信息的上下文數(shù)組，鍵名為占位符名稱，鍵值為替換值。 $context = array('username' => 'bolivar'); // 輸出 "Username bolivar created" echo interpolate($message, $context);
1.3 上下文
每個(gè)記錄函數(shù)都接受一個(gè)上下文數(shù)組參數(shù)，用來裝載字符串類型無法表示的信息。它 可以 裝載任何信息，所以實(shí)現(xiàn)者 必須 確保能正確處理其裝載的信息，對(duì)于其裝載的數(shù)據(jù)， 一定不可 拋出異常，或產(chǎn)生PHP出錯(cuò)、警告或提醒信息（error、warning、notice）。
如需通過上下文參數(shù)傳入了一個(gè)
Exception對(duì)象，必須 以exception作為鍵名。
記錄異常信息是很普遍的，所以如果它能夠在記錄類庫的底層實(shí)現(xiàn)，就能夠讓實(shí)現(xiàn)者從異常信息中抽絲剝繭。
當(dāng)然，實(shí)現(xiàn)者在使用它時(shí)，必須 確保鍵名為exception的鍵值是否真的是一個(gè)Exception，畢竟它 可以 裝載任何信息。
1.4 助手類和接口
Psr\Log\AbstractLogger類使得只需繼承它和實(shí)現(xiàn)其中的log方法，就能夠很輕易地實(shí)現(xiàn)LoggerInterface接口，而另外八個(gè)方法就能夠把記錄信息和上下文信息傳給它。同樣地，使用
Psr\Log\LoggerTrait也只需實(shí)現(xiàn)其中的log方法。不過，需要特別注意的是，在 traits 可復(fù)用代碼塊還不能實(shí)現(xiàn)接口前，還需要implement LoggerInterface。在沒有可用的日志記錄器時(shí)，
Psr\Log\NullLogger接口 可以 為使用者提供一個(gè)備用的日志「黑洞」。不過，當(dāng)上下文的構(gòu)建非常消耗資源時(shí)，帶條件檢查的日志記錄或許是更好的辦法。Psr\Log\LoggerAwareInterface接口僅包括一個(gè)
setLogger(LoggerInterface $logger)方法，框架可以使用它實(shí)現(xiàn)自動(dòng)連接任意的日志記錄實(shí)例。Psr\Log\LoggerAwareTraittrait可復(fù)用代碼塊可以在任何的類里面使用，只需通過它提供的$this->logger，就可以輕松地實(shí)現(xiàn)等同的接口。Psr\Log\LogLevel類裝載了八個(gè)記錄等級(jí)常量。
2. 包
上述的接口、類和相關(guān)的異常類，以及一系列的實(shí)現(xiàn)檢測(cè)文件，都包含在 psr/log 文件包中。
3. Psr\Log\LoggerInterface
<?php
namespace Psr\Log;
/**
* 日志記錄實(shí)例
*
* 日志信息變量 —— message，**必須** 是一個(gè)字符串或是實(shí)現(xiàn)了 __toString() 方法的對(duì)象。
*
* 日志信息變量中 **可以** 包含格式如 “{foo}” (代表 foo) 的占位符，
* 它將會(huì)由上下文數(shù)組中鍵名為「foo」的鍵值替代。
*
* 上下文數(shù)組可以攜帶任意的數(shù)據(jù)，唯一的限制是，當(dāng)它攜帶的是一個(gè) exception 對(duì)象時(shí)，它的鍵名 **必須** 是 "exception"。
*
* 詳情可參閱： https://github.com/PizzaLiu/PHP-FIG/blob/master/PSR-3-logger-interface-cn.md
*/
interface LoggerInterface
{
/**
* 系統(tǒng)不可用
*
* @param string $message
* @param array $context
* @return null
*/
public function emergency($message, array $context = array());
/**
* **必須** 立刻采取行動(dòng)
*
* 例如：在整個(gè)網(wǎng)站都垮掉了、數(shù)據(jù)庫不可用了或者其他的情況下， **應(yīng)該** 發(fā)送一條警報(bào)短信把你叫醒。
*
* @param string $message
* @param array $context
* @return null
*/
public function alert($message, array $context = array());
/**
* 緊急情況
*
* 例如：程序組件不可用或者出現(xiàn)非預(yù)期的異常。
*
* @param string $message
* @param array $context
* @return null
*/
public function critical($message, array $context = array());
/**
* 運(yùn)行時(shí)出現(xiàn)的錯(cuò)誤，不需要立刻采取行動(dòng)，但必須記錄下來以備檢測(cè)。
*
* @param string $message
* @param array $context
* @return null
*/
public function error($message, array $context = array());
/**
* 出現(xiàn)非錯(cuò)誤性的異常。
*
* 例如：使用了被棄用的API、錯(cuò)誤地使用了API或者非預(yù)想的不必要錯(cuò)誤。
*
* @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
*/
public function debug($message, array $context = array());
/**
* 任意等級(jí)的日志記錄
*
* @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 定義實(shí)例
*/
interface LoggerAwareInterface
{
/**
* 設(shè)置一個(gè)日志記錄實(shí)例
*
* @param LoggerInterface $logger
* @return null
*/
public function setLogger(LoggerInterface $logger);
}
5. Psr\Log\LogLevel
<?php
namespace Psr\Log;
/**
* 日志等級(jí)常量定義
*/
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';
}
