[TOC=2] ## 1. 規格 ### 1.1 基礎知識 * 該LoggerInterface自曝八種方法來寫日志八個 RFC 5424 倍的水平（調試，信息，通知，警告，錯誤，嚴重警告，緊急）。 * 第九種方法，log 接受日志級別作為第一個參數。使用其中一個日志級別常量調用此方法必須與調用特定級別的方法具有相同的結果。 如果實現不知道該級別，則必須使用此規范未定義的級別調用此方法 Psr\Log\InvalidArgumentException。用戶不應該在不確定當前實現是否支持的情況下使用自定義級別。 ### 1.2 消息 * 每個方法都接受一個字符串作為消息，或接受一個帶有 __toString() 方法的對象。實現者可以對傳遞的對象進行特殊處理。如果不是這樣，實現者必須將其轉換為字符串。 * 消息可以包含占位符，實現者可以替換上下文數組中的值。 * 占位符名稱必須對應于上下文數組中的鍵。 * 占位符名稱必須用單個左大括號{和單個右大括號分隔}。 * 分隔符和占位符名稱之間不能有任何空格。 * 占位符名稱應該只字符組成 A-Z，a-z，0-9，下劃線 _ 和句點 . 。其他字符的使用保留用于將來修改占位符規范。 實現者可以使用占位符來實現各種轉義策略并轉換日志以供顯示。用戶不應預先轉義占位符值，因為他們無法知道數據將在哪個上下文中顯示。 以下是占位符插值的示例實現， 僅供參考： ~~~php <?php /** * Interpolates context values into the message placeholders. */ function interpolate($message, array $context = array()) { // build a replacement array with braces around the context keys $replace = array(); foreach ($context as $key => $val) { // check that the value can be casted to string if (!is_array($val) && (!is_object($val) || method_exists($val, '__toString'))) { $replace['{' . $key . '}'] = $val; } } // interpolate replacement values into the message and return return strtr($message, $replace); } // a message with brace-delimited placeholder names $message = "User {username} created"; // a context array of placeholder names => replacement values $context = array('username' => 'bolivar'); // echoes "User bolivar created" echo interpolate($message, $context); ~~~ ### 1.3 背景 * 每個方法都接受一個數組作為上下文數據 這意味著保存任何不適合字符串的無關信息。該數組可以包含任何內容。實現者必須確保他們盡可能地對待上下文數據。上下文中的給定值絕不能拋出異常，也不會引發任何 php 錯誤，警告或通知。 * 如果Exception在上下文數據中傳遞了一個對象，它必須在 'exception' 鍵中。記錄異常是一種常見模式，這允許實現者在日志后端支持時從異常中提取堆棧跟蹤。實現者必須在使用它之前確認 'exception' 密鑰實際上是一個 Exception，因為它可能包含任何東西。 ### 1.4 助手類和接口 * 本 Psr\Log\AbstractLogger 類，可以實現 LoggerInterface * 通過擴展，并實現通用很容易 log 的方法。 * 其他八種方法是將消息和上下文轉發給它。 * 同樣，使用 Psr\Log\LoggerTrait 只需要您實現泛型 log 方法。請注意，由于 traits 無法實現接口，因此在這種情況下仍需要實現 LoggerInterface。 * 它 Psr\Log\NullLogger 與界面一起提供。 如果沒有為它們提供記錄器，接口的用戶可以使用它來提供后備“黑洞” 實現。但是，如果上下文數據創建很昂貴，則條件記錄可能是更好的方法。 * 的 Psr\Log\LoggerAwareInterface 僅包含一個 setLogger(LoggerInterface $logger) 方法，并且可以通過框架被用于自動絲任意實例用記錄器。 * 該 Psr\Log\LoggerAwareTrait 特征可用于在任何類中輕松實現等效接口。它讓您訪問 $this->logger。 * 在 Psr\Log\LogLevel 此類包含八個日志級別常量。 ## 2. 包裝 * 描述的接口和類以及相關的異常類和用于驗證實現的測試套件是作為 psr / log 包的一部分提供的。 ## 3. `Psr \ Log \ LoggerInterface` ~~~php <?php namespace Psr\Log; /** * Describes a logger instance * * The message MUST be a string or object implementing __toString(). * * The message MAY contain placeholders in the form: {foo} where foo * will be replaced by the context data in key "foo". * * The context array can contain arbitrary data, the only assumption that * can be made by implementors is that if an Exception instance is given * to produce a stack trace, it MUST be in a key named "exception". * * See https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md * for the full interface specification. */ interface LoggerInterface { /** * System is unusable. * * @param string $message * @param array $context * @return void */ public function emergency($message, array $context = array()); /** * Action must be taken immediately. * * Example: Entire website down, database unavailable, etc. This should * trigger the SMS alerts and wake you up. * * @param string $message * @param array $context * @return void */ public function alert($message, array $context = array()); /** * Critical conditions. * * Example: Application component unavailable, unexpected exception. * * @param string $message * @param array $context * @return void */ public function critical($message, array $context = array()); /** * Runtime errors that do not require immediate action but should typically * be logged and monitored. * * @param string $message * @param array $context * @return void */ public function error($message, array $context = array()); /** * Exceptional occurrences that are not errors. * * Example: Use of deprecated APIs, poor use of an API, undesirable things * that are not necessarily wrong. * * @param string $message * @param array $context * @return void */ public function warning($message, array $context = array()); /** * Normal but significant events. * * @param string $message * @param array $context * @return void */ public function notice($message, array $context = array()); /** * Interesting events. * * Example: User logs in, SQL logs. * * @param string $message * @param array $context * @return void */ public function info($message, array $context = array()); /** * Detailed debug information. * * @param string $message * @param array $context * @return void */ public function debug($message, array $context = array()); /** * Logs with an arbitrary level. * * @param mixed $level * @param string $message * @param array $context * @return void */ public function log($level, $message, array $context = array()); } ~~~ ## 4. `Psr \ Log \ LoggerAwareInterface` ~~~php <?php namespace Psr\Log; /** * Describes a logger-aware instance */ interface LoggerAwareInterface { /** * Sets a logger instance on the object * * @param LoggerInterface $logger * @return void */ public function setLogger(LoggerInterface $logger); } ~~~ ## 5. `Psr \ Log \ LogLevel` ~~~php <?php namespace Psr\Log; /** * Describes log levels */ 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'; } ~~~