PHP日誌記錄規範PSR-3

本文制定了日誌類庫的通用接口規範。

本規範的主要目的，是爲了讓日誌類庫以簡單通用的方式，經過接收一個 Psr\Log\LoggerInterface 對象，來記錄日誌信息。 框架以及CMS內容管理系統若有須要，能夠對此接口進行擴展，但需遵循本規範， 這才能保證在使用第三方的類庫文件時，日誌接口仍能正常對接。

關鍵詞 「必須」(「MUST」)、「必定不可/必定不能」(「MUST NOT」)、「須要」(「REQUIRED」)、 「將會」(「SHALL」)、「不會」(「SHALL NOT」)、「應該」(「SHOULD」)、「不應」(「SHOULD NOT」)、 「推薦」(「RECOMMENDED」)、「能夠」(「MAY」)和」可選「(「OPTIONAL」)的詳細描述可參見 RFC 2119 。

本文中的 實現者 指的是實現了 LoggerInterface 接口的類庫或者框架，反過來說，他們就是 LoggerInterface 的 使用者。

1. 規範說明

1.1 基本規範

LoggerInterface 接口對外定義了八個方法，分別用來記錄 RFC 5424 中定義的八個等級的日誌：debug、 info、 notice、 warning、 error、 critical、 alert 以及 emergency 。

第九個方法 —— log，其第一個參數爲記錄的等級。可以使用一個預先定義的等級常量做爲參數來調用此方法，必須與直接調用以上八個方法具備相同的效果。若是傳入的等級常量參數沒有預先定義，則必須拋出 Psr\Log\InvalidArgumentException 類型的異常。在不肯定的狀況下，使用者不應使用未支持的等級常量來調用此方法。

1.2 記錄信息

以上每一個方法都接受一個字符串類型或者是有 __toString() 方法的對象做爲記錄信息參數，這樣，實現者就能把它當成字符串來處理，不然實現者必須本身把它轉換成字符串。

記錄信息參數能夠攜帶佔位符，實現者能夠根據上下文將其它替換成相應的值。

其中佔位符必須與上下文數組中的鍵名保持一致。

佔位符的名稱必須由一個左花括號 { 以及一個右括號 } 包含。但花括號與名稱之間必定不能有空格符。

佔位符的名稱應該只由 A-Z、 a-z,0-九、下劃線 _、以及英文的句號 .組成，其它字符做爲未來佔位符規範的保留。

實現者能夠經過對佔位符采用不一樣的轉義和轉換策略，來生成最終的日誌。 而使用者在不知道上下文的前提下，不應提早轉義佔位符。

如下是一個佔位符使用的例子：

/** * 用上下文信息替換記錄信息中的佔位符 */
function interpolate($message, array $context = array()){
    // 構建一個花括號包含的鍵名的替換數組
    $replace = array();
    foreach ($context as $key => $val) {
        $replace['{' . $key . '}'] = $val;
    }

    // 替換記錄信息中的佔位符，最後返回修改後的記錄信息。
    return strtr($message, $replace);
}

// 含有帶花括號佔位符的記錄信息。
$message = "User {username} created";

// 帶有替換信息的上下文數組，鍵名爲佔位符名稱，鍵值爲替換值。
$context = 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 方法。不過，須要特別注意的是，在traits可複用代碼塊還不能實現接口前，還須要 implement LoggerInterface。

在沒有可用的日誌記錄器時， Psr\Log\NullLogger 接口能夠爲使用者提供一個備用的日誌「黑洞」。不過，當上下文的構建很是消耗資源時，帶條件檢查的日誌記錄或許是更好的辦法。

Psr\Log\LoggerAwareInterface 接口僅包括一個 setLogger(LoggerInterface $logger) 方法，框架可使用它實現自動鏈接任意的日誌記錄實例。

Psr\Log\LoggerAwareTrait trait可複用代碼塊能夠在任何的類裏面使用，只需經過它提供的 $this->logger，就能夠輕鬆地實現等同的接口。

Psr\Log\LogLevel 類裝載了八個記錄等級常量。

上述的接口、類和相關的異常類，以及一系列的實現檢測文件，都包含在 psr/log 文件包中。

3. Psr\Log\LoggerInterface

<?php

namespace Psr\Log;

/** * 日誌記錄實例 * * 日誌信息變量 —— 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 alert($message, array $context = array());

    /** * 緊急狀況 * * 例如：程序組件不可用或者出現非預期的異常。 * * @param string $message * @param array $context * @return null */
    public function critical($message, array $context = array());

    /** * 運行時出現的錯誤，不須要馬上採起行動，但必須記錄下來以備檢測。 * * @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 */
    public 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 EMERGENCY = 'emergency';
    const ALERT     = 'alert';
    const CRITICAL  = 'critical';
    const ERROR     = 'error';
    const WARNING   = 'warning';
    const NOTICE    = 'notice';
    const INFO      = 'info';
    const DEBUG     = 'debug';}