搜尋

首頁  >  文章  >  後端開發  >  PHP PSR-3 日誌介面規格

PHP PSR-3 日誌介面規格

WBOY
WBOY原創
2016-07-23 08:54:41966瀏覽
複製代碼
日誌介面規範

本文制定了日誌類別庫的通用介面規格。

本規範的主要目的，是為了讓日誌類別庫以簡單通用的方式，透過接收一個 PsrLogLoggerInterface 對象，來記錄日誌資訊。
框架以及CMS內容管理系統如有需要，可以對此接口進行擴展，但需遵循本規範，
這才能保證在使用第三方的類庫文件時，日誌接口仍能正常對接。

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

本文中的 實作者 指的是實作了 LoggerInterface 介面的類別庫或框架，反過來講，他們就是 LoggerInterface 的 使用者。

規範說明

1.1 基本規範

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

第九個方法 —— log，其第一個參數為記錄的等級。可使用一個預先定義的等級常數作為參數來呼叫此方法，必須與直接呼叫以上八個方法具有相同的效果。如果傳入的等級常數參數沒有預先定義，則必須拋出 PsrLogInvalidArgumentException 類型的例外。在不確定的情況下，使用者不該使用未支援的等級常數來呼叫此方法。

1.2 記錄資訊

以上每個方法都接受一個字串類型或是有__toString() 方法的物件作為記錄資訊參數，這樣，實作者就能把它當成字串來處理，否則實作者必須自己把它轉換成字串。

記錄資訊參數可以攜帶佔位符，實現者可以根據上下文將其它替換成對應的值。

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

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

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

實作者可以透過對佔位符採取不同的轉義和轉換策略，來產生最終的日誌。
而使用者在不知道上下文的前提下，不該提前轉義佔位符。

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

  1. /**
  2. * 以上下文資訊取代記錄資訊中的佔位符
  3. */
  4. function interpolate($message, array $context = array ())
  5. {
  6. // 建立一個花括號包含的鍵名的替換數組
  7. $replace = array();
  8. foreach ($context as $key => $val) {
  9. $replace['{' . $key . '}'] = $val;
  10. }
  12. // 取代記錄資訊中的佔位符，最後傳回修改後的記錄資訊。
  13. return strtr($message, $replace);
  14. }
  16. // 含有帶花括號佔位符的記錄資訊。
  17. $message = "User {username} created";
  19. // 帶有替換資訊的上下文數組，鍵名為佔位符名稱，鍵值為替換值。
  20. $context = array('username' => 'bolivar');
  22. // 輸出"Username bolivar created"
  23. echo interpolate($message, $context);
複製程式碼
1.3 上下文

每個記錄函數都接受一個上下文陣列參數，用來裝載字串類型無法表示的資訊。它可以裝載任何信息，所以實現者必須確保能正確處理其裝載的信息，對於其裝載的數據，一定不能 拋出異常，或產生PHP出錯、警告或提醒訊息（error、warning、notice）。

如需透過上下文參數傳入了一個 Exception 對象， 必須以 'exception' 作為鍵名。
記錄異常訊息是很普遍的，所以如果它能夠在記錄類別庫的底層實現，就能夠讓實現者從異常訊息中抽絲剝繭。
當然，實現者在使用它時，必須確保鍵名為 'exception' 的鍵值是否真的是一個 Exception，畢竟它可以裝載任何資訊。

1.4 助手類別和接口

PsrLogAbstractLogger 類別使得只需繼承它和實現其中的 log 方法，就能夠很輕易地實現 LoggerInterface 接口，而另外八個方法就能夠把記錄資訊和上下文資訊傳給它。

同樣地，使用 PsrLogLoggerTrait 也只需實作其中的 log 方法。不過，要特別注意的是，在traits可重複使用程式碼區塊還不能實作介面前，還需要 implement LoggerInterface。

在沒有可用的日誌記錄器時， PsrLogNullLogger 介面可以為使用者提供一個備用的日誌「黑洞」。不過，當上下文的建置非常消耗資源時，帶條件檢查的日誌記錄或許是更好的方法。

PsrLogLoggerAwareInterface 介面僅包含一個
setLogger(LoggerInterface $logger) 方法，框架可以使用它實作自動連接任意的日誌記錄實例。

PsrLogLoggerAwareTrait trait可重複使用程式碼區塊可以在任何的類別裡面使用，只需透過它提供的 $this->logger，就可以輕鬆實現等同的介面。

PsrLogLogLevel 類別裝載了八個記錄等級常數。

包

上述的介面、類別和相關的異常類，以及一系列的實作偵測文件，都包含在 psr/log 文件包中。

PsrLogLoggerInterface

  2. 命名空間PsrLog;
  4. /**
  5. * 日誌記錄實例
  6. *
  7. * 日誌資訊變數 —— message， **必須**是一個字串或是實作了 __toString() 方法的物件。
  8. *
  9. * 日誌資訊變數中**可以**包含格式如「{foo}」 (代表foo) 的佔位符，
  10. * 它將會由上下文數組中鍵名為"foo " 的鍵值替代。
  11. *
  12. * 上下文數組可以攜帶任意的數據，唯一的限制是，當它攜帶的是一個 exception 物件時，它的鍵名 必須 是 "exception"。
  13. *
  14. * 詳情可參考： https://github.com/PizzaLiu/PHP-FIG/blob/master/PSR-3-logger-interface-cn.md
  15. */
  16. 接口LoggerInterface
  17. {
  18. /**
  19. * 系統不可用
  20. *
  21. * @param string $message
  22. * @param array $context
  23. * @return null
  24. */
  25. 公用函數Emergency($message, array $context = array());
  27. /**
  28. * **必須**立刻採取行動
  29. *
  30. * 例如：在整個網站都垮掉了、資料庫不可用了或者其他的情況下，**應該**發送一條警報短信把你叫醒。
  31. *
  32. * @param string $message
  33. * @param array $context
  34. * @return null
  35. */
  36. 公用函數>
  37. /**
  38. * 緊急情況
  39. *
  40. * 例如：程式組件無法使用或出現非預期的異常。
  41. *
  42. * @param string $message
  43. * @param array $context
  44. * @return null
  45. */
  46. 公用函數Alert($message, array $context = array());
  48. /**
  49. * 運行時出現的錯誤，不需要立刻採取行動，但必須記錄下來以備檢測。
  50. *
  51. * @param string $message
  52. * @param array $context
  53. * @return null
  54. */
  55. public function critical($message, array $context = array());
  57. /**
  58. * 出現非錯誤性的異常。
  59. *
  60. * 例如：使用了被棄用的API、錯誤地使用了API或非預想的不必要錯誤。
  61. *
  62. * @param string $message
  63. * @param array $context
  64. * @return null
  65. */
  66. 公用函數錯誤($message, array $context = array());
  68. /**
  69. * 一般性重要的事件。
  70. *
  71. * @param string $message
  72. * @param array $context
  73. * @return null
  74. */
  75. 公用函數警告($message, array $context = array());
  77. /**
  78. * 重要事件
  79. *
  80. * 例如：使用者登入和SQL記錄。
  81. *
  82. * @param string $message
  83. * @param array $context
  84. * @return null
  85. */
  86. 公用函數通知($message, array $context = array());
  88. /**
  89. * 除錯詳情
  90. *
  91. * @param string $message
  92. * @param array $context
  93. * @return null
  94. */
  95. public function info($message, array $context = array());
  97. /**
  98. * 任意等級的日誌記錄
  99. *
  100. * @param mixed $level
  101. * @param string $message
  102. * @param array $context
  103. * @return null
  104. * @param array $context
  105. * @return null
  106. */
  107. public function debug( $message, array $context = array());
/** * logger-aware 定義實例*/
public function log($level, $message, array $context = array());

}

複製程式碼
  1. PsrLogLoggerAwareInterface
  8. 命名空間PsrLog;
  10. /**
  11. * 設定一個日誌記錄實例
  12. *
  13. * @param LoggerInterface $logger
  14. * @return null
  15. */
  16. 介面LoggerAInterwareInterface>/**
* 日誌等級常數定義
*/介面LoggerAInterwareInterface> { /***/
public function setLogger(LoggerInterface $logger);

}

複製程式碼🎜>
  1. 複製碼🎜>
  7. 命名空間PsrLog;
  9. /***/
  10. class Logo>
  11. /***/
  12. class Logf
  13. Lef>Level
  14. Level const EMERGENCY = '緊急';
  15. const ALERT = '警報';
  16. const CRITICAL = '嚴重';
const ERROR = '錯誤';
const WARNING = '警告' ; const NOTICE = 'notice'; const INFO = 'info';
const DEBUG = 'debug';

}

轉自Github(PizzaLiu)
PHP、PSR

陳述：
本文內容由網友自願投稿，版權歸原作者所有。本站不承擔相應的法律責任。如發現涉嫌抄襲或侵權的內容，請聯絡admin@php.cn
上一篇：程式設計師之家-程式設計師論壇【廣告贊助報價】 - 網路資訊 程式設計師之家論壇下一篇：程式設計師之家-程式設計師論壇【廣告贊助報價】 - 網路資訊 程式設計師之家論壇

相關文章

看更多