「PSR 規(guī)范」PSR-3 日志接口規(guī)范

日志接口規(guī)范

本文制定了日志類庫的通用接口規(guī)范。
本規(guī)范的主要目的，是為了讓日志類庫以簡單通用的方式，通過接收一個 Psr\Log\LoggerInterface 對象，來記錄日志信息?？蚣芤约?CMS 管理系統(tǒng)如有需要， 可以 對此接口進行擴展，這才能在保證使用第三方類庫的文件時，日志接口仍能正常對接。

關(guān)于「能愿動詞」的使用

為了避免歧義，文檔使用了大量的 「能愿動詞」，對應(yīng)的解釋如下：

  • 必須（MUST）：絕對，嚴格遵循，請照做，無條件遵守；
  • 一定不可（MUST NOT）：禁令，嚴令禁止；
  • 應(yīng)該（SHOULD）：強烈建議這樣做，但不強求；
  • 不該（SHOULD NOT）：強烈建議不要這樣做，但不強求；
  • 可以（MAY） 和 可選（OPTIONAL）：選擇性較高，在這個文檔內(nèi)，此詞語使用較少；

1.規(guī)范說明

1.1基本規(guī)范

  • LoggerInterface RFC 5424 接口對外定義了八個方法，分別用來記錄中定義的八個等級的日志：debug、info、notice、warning、error、critical、alter 和 emergency。
  • 第九個方法—— log，其第一個參數(shù)為記錄的等級?？墒褂靡粋€預(yù)先定義的等級常量作為參數(shù)來調(diào)用此方法， 必須 與直接調(diào)用以上八個方法具有相同的效果。如果傳入的等級常量參數(shù)沒有預(yù)先定義，則 必須 拋出 Psr\Log\InvalidArgumentException 類型的異常。在不確定的情況下，使用者 不該 使用未支持的等級常量來調(diào)用此方法。

1.2記錄信息

  • 以上每個方法都接受一個字符串類型或者有 __toString() 方法的對象作為記錄信息參數(shù)，這樣，實現(xiàn)者就能把它當(dāng)成字符串來處理，否則實現(xiàn)者 必須 自己把它轉(zhuǎn)換成字符串。
  • 記錄信息參數(shù) 可以 攜帶占位符，實現(xiàn)者 可以 根據(jù)上下文將其他替換成相應(yīng)的值。
    其中占位符 必須 與上下文數(shù)組中的鍵保持一致。
    占位符的名稱 必須 由一個左花括號 { 以及一個右花括號 } 包含。但花括號與名稱之間 一定不可 有空格符。
    占位符的名稱 應(yīng)該 只有 A-Z、a-z、0-9、下劃線 _ 以及英文的句號 . 組成，其他字符作為將來占位符規(guī)范的保留。
    實現(xiàn)者 可以 通過對占位符采用不同的轉(zhuǎn)義和轉(zhuǎn)換策略，來生成最終的日志。而使用者在不知道上下文的前提下，不該 提前轉(zhuǎn)義占位符。
    以下是占位符使用的一個例子：
/**
 * 用上下文信息替換記錄信息中的占位符
 */
function interpolate($message, array $content = array ())
{
    //構(gòu)建一個花括號包含的鍵名的替換數(shù)組
    $replace = array();
    foreach ($content as $key => $val) {
        $replace['{' . $key . '}'] = $val;
    }
    //替換記錄中信息中的占位符，最后返回修改后的記錄信息
    return strtr($message, $replace);
}

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

//帶有替換信息的上下文數(shù)組，鍵名為占位符名稱，鍵值為替換值。
$content = array('username' => 'bolivar');

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

1.3上下文

  • 每個記錄函數(shù)都接受一個上下文數(shù)組參數(shù)，用來裝載字符串類型無法表示的信息。它 可以 裝載任何信息，對于其裝載的數(shù)據(jù)，一定不可 拋出異常，或產(chǎn)生 PHP 錯誤、警告或提醒信息（error、warning、notice）。
  • 如需通過上下文參數(shù)傳入了一個 Exception 對象，必須 以 exception 作為鍵名。記錄異常信息是很普遍的，所以如果他能夠在記錄類庫的底層實現(xiàn)，就能夠讓實現(xiàn)者從異常信息中抽絲剝繭。當(dāng)然，實用者在使用它時，必須 確保鍵名為 exception 的鍵值是否是一個真的 Exception，畢竟它可以裝載任何信息。

1.4助手類和接口

  • Psr\Log\AbstractLogger 使得只需繼承它和實現(xiàn)其中的 log 方法，就能夠很輕易的實現(xiàn) LoggerInterface 接口，而另外八個方法就能夠吧記錄信息和上下文信息傳給它。
  • 同樣的，使用 Psr\Log\LoggerTrait 也只需實現(xiàn)其中的 log 方法。不過，需要特別注意的是，在 trait 可復(fù)用代碼塊還不能實現(xiàn)接口前，還需要 implement LoggerInterface。
  • 在沒有可用的日志記錄器時， Psr\Log\NullLogger 接口 可以 為使用者提供一個備用的日志 「黑洞」。不過，當(dāng)上下文的構(gòu)建非常消耗資源時，帶條件檢查的日志記錄或許是更好的辦法。
  • Psr\Log\LoggerAwareInterface 接口僅包括一個 setLogger(LoggerInterface $logger) 方法，框架 可以 使用它實現(xiàn)自動連接任意的日志記錄實例。
  • Psr\Log\LoggerAwareTrait trait 可復(fù)用代碼塊可以在任何的類里面使用，只需通過它提供的 $this->logger，就可以輕松的實現(xiàn)等同的接口。
  • Psr\Log\LogLevel 類裝載了八個記錄等級常量。

2.包

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

3. Psr\Log\LoggerInterface 

<?php
/**
 *日志記錄實例
 *
 * 日志信息變量—— message，**必須** 是一個字符串或是實現(xiàn)了 __toString() 方法的對象
 *
 * 日志信息變量中 **可以** 包含如 “{foo}” (代表 foo) 的占位符，
 * 它將會有上下文數(shù)組中鍵名為 「foo」的鍵值替代。
 *
 * 它將會由上下文數(shù)組可以攜帶任意的數(shù)據(jù)，唯一的限制是，當(dāng)它攜帶的是一個 exception 對象時，它的鍵名必須是 "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());

/**
  *    **必須** 立刻采取行動
  * 
  * 例如：在整個網(wǎng)站都垮掉了、數(shù)據(jù)庫不可用了或其他的情況下， **應(yīng)該** 發(fā)送一條警報信息把你叫醒。
  *
  * @param string $message
  * @param array $context
  * @return null
  */
public function alter($message, array $context = array());

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

/**
  * 運行時出現(xiàn)的錯誤，不需要立刻采取行動，但必須記錄下來以備檢測。
  * 
  * @param string $message
  * @param array $context
  * @return null
  */
public function error($message, array $context = array());

/**
  * 出現(xiàn)非錯誤性的異常。
  *
  * 例如：使用了被棄用的 API、錯誤的使用了 API 或非預(yù)想的不必要錯誤。
  *
  * @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
{
    /**
      * 設(shè)置一個日志記錄實例
      *
      * @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';
}
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時請結(jié)合常識與多方信息審慎甄別。
平臺聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點，簡書系信息發(fā)布平臺，僅提供信息存儲服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

友情鏈接更多精彩內(nèi)容