PHP編碼規範(PSR-3)-日誌接口規範

PSR-3 日誌接口規範

本文制定了日誌類庫的通用接口規範。 本規範的主要目的，是爲了讓日誌類庫以簡單通用的方式，經過接收一個 Psr\Log\LoggerInterface 對象，來記錄日誌信息。 框架以及CMS內容管理系統若有須要，能夠對此接口進行擴展，但需遵循本規範， 這才能保證在使用第三方的類庫文件時，日誌接口仍能正常對接。 本文中的 實現者 指的是實現了 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 類裝載了八個記錄等級常量。

2. 包

上述的接口、類和相關的異常類，以及一系列的實現檢測文件，都包含在 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';
}

參考文檔

• PSR-3 日誌接口規範 (中文版)
• PHP PSR-3(英文版)