【翻譯】Monolog使用說明

前言

最近項目中使用的 Monolog 出了點小問題，去翻其文檔，發現竟然只有英文的。趁業餘時間，翻譯一下吧。
如下是其使用說明的中文翻譯。更多翻譯內容見 clarence-pan/monolog-zh-doc.

使用 Monolog

• 安裝

• 核心概念

• 日誌級別

• 配置一個日誌服務

• 爲記錄添加額外的數據

• 使用通道

• 自定義日誌格式

<!-- more -->

安裝

Monolog 在 Packagist (monolog/monolog) 上可用，而且能夠經過 Composer 安裝:

composer require monolog/monolog

若是你不使用 Composer, 那你能夠從 GitHub 上獲取代碼，而後使用任何兼容 PSR-0 的自動加載器（好比Symfony2 ClassLoader 組件）來加載 Monolog 的類

核心概念

每個日誌服務實例 (Logger) 都有一個通道（名稱），並有一個處理器 (Handler)棧. 不管什麼時候你添加一條 記錄 到對應的日誌服務實例，這個處理器棧將被遍歷一遍：每一個處理器都將依次決定是否要處理這條記錄，而若是要處理，則遍歷結束（譯註：相似DOM事件冒泡）。

這樣子能夠建立很是靈活的日誌配置。好比一個 StreamHandler 能夠把全部日誌都寫入磁盤，而上面加個MailHandler 能夠把錯誤日誌做爲郵件發送出去。處理器還有一個 $bubble 屬性定義了是否屏蔽某條記錄或者處理了某條記錄。在這個示例中，配置 MailHandler 的 $bubble 參數爲 false 則意味着 MailHandler 將不會把本身已處理過的記錄繼續冒泡給 StreamHandler.

你能夠建立許多日誌服務實例(Logger)，每個則定義一個通道（好比數據庫、請求、路由...）。而每個日誌服務實例均可以組合各類各樣的處理器，能夠共享處理器也能夠不共享。這個通道將會在日誌中反映出來，從而容許你能夠很容易地查看或者篩選記錄。

每個處理還會有一個格式化器（Formatter）。若是你沒有配置一個，則一個有意義的默認的格式化器將被建立。格式化器用來規範化並格式化輸入的記錄，以便處理器能輸出一些有用的信息。

不支持自定義的嚴重性級別。只支持使用RFC 5424中定義的八個級別（調試/Debug、信息/Info、提示/Notice、警告/Warning、錯誤/Error、嚴重/Critical、警報/Alert、緊急/Emergency）來做爲基本的篩選目的。不過，若是爲了排序或者其餘須要靈活性的使用場景，你能夠添加加工程序（Processor）從而能夠在（處理器）處理前添加額外的信息（標籤、用戶IP...）。

日誌級別

Monolog 支持一下 RFC 5424 中的日誌級別：

• 調試/DEBUG (100): 詳細的調試信息。

• 信息/INFO (200): 有意義的事件，好比用戶登陸、SQL日誌。

• 提示/NOTICE (250): 正常可是值得注意的事件。

• 警告/WARNING (300): 異常事件，可是並非錯誤。好比使用了廢棄了的API，錯誤地使用了一個API，以及其餘不但願發生可是並不是必要的錯誤。

• 錯誤/ERROR (400): 運行時的錯誤，不須要當即注意到，可是須要被專門記錄並監控到。

• 嚴重/CRITICAL (500): 邊界條件/危篤場景。好比應用組件不可用了，未預料到的異常。

• 警報/ALERT (550): 必須當即採起行動。好比整個網站都掛了，數據庫不可用了等。這種狀況應該發送短信警報，並把你叫醒。

• 緊急/EMERGENCY (600): 緊急請求：系統不可用了。

配置一個日誌服務

這裏有一個基本的配置，能夠記錄日誌到文件，並在 DEBUG 級別下記錄到 firephp 中:

<?php

use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Monolog\Handler\FirePHPHandler;

// 建立日誌服務
$logger = new Logger('my_logger');

// 添加一些處理器
$logger->pushHandler(new StreamHandler(__DIR__.'/my_app.log', Logger::DEBUG));
$logger->pushHandler(new FirePHPHandler());

// 如今你就能夠用日誌服務了
$logger->info('My logger is now ready');

解釋一下。第一步是建立日誌服務實例，這個實例後將在代碼中用到。惟一的參數是通道的名稱，它在你有多個日誌服務實例的時候頗有用。（更多詳情參見下面）

這個日誌服務實例本身是否是知道如何處理一條日誌記錄的。它把記錄代理給了一些處理器。上面的代碼中註冊了兩個處理器到棧中，以便容許使用兩種不一樣的方式來處理日誌記錄。

注意，FirePHPHandler 是被先調用的，於是它被添加到了棧頂。這容許你臨時添加一個禁止冒泡的處理器從而容許你覆蓋其餘配置的日誌（處理器）。

若是你單獨使用 Monolog, 而且在尋找一種簡單的方式來配置許多處理器，那能夠用
theorchard/monolog-cascade 。
它能夠幫你使用PHP數組、YAML或者JSON來構建複雜的日誌配置。

爲記錄添加額外的數據

Monolog 提供了兩種不一樣的方式來爲簡單的文本消息增長額外的信息

使用上下文(context)

第一種方式是使用上下文（context），這容許你在傳遞記錄的時候傳遞一個數組格式的數據：

<?php

$logger->info('Adding a new user', array('username' => 'Seldaek'));

簡單的處理器（好比StreamHandler）將只是把數組轉換成字符串。而複雜的處理器則能夠利用上下文的優勢（如 FirePHP 則將以一種優美的方式顯示數組）。

使用加工程序(Processor)

第二種方式是使用加工程序來爲全部的記錄添加額外數據。加工程序能夠是任何能夠調用的函數。
加工程序接收日誌記錄做爲參數，而且須要在修改了extra字段後再返回日誌記錄。讓咱們來寫一個添加一些假數據的加工程序：

<?php

$logger->pushProcessor(function ($record) {
    $record['extra']['dummy'] = 'Hello world!';

    return $record;
});

Monolog提供了一些內置的加工程序，你能夠在你的項目中使用它們。請參見對應的章節.

小技巧：加工程序能夠被註冊到一個特定的處理器上而不是直接在日誌服務實例上，從而能夠只在對應的處理器上生效。

使用通道

通道是一種很是棒的方式來區分是應用的哪一個部分的日誌被記錄下來的。這一般在大型項目中很是有用（並且被Symfony2的MonologBundle所使用）。

假設有兩個日誌服務實例共享了一個處理器，這個處理器將日誌寫入單個日誌文件。通道則將容許你來區分是哪一個日誌服務實例記錄了哪條日誌。你能夠很簡單地經過通道來篩選日誌。

<?php

use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Monolog\Handler\FirePHPHandler;

// 建立一些處理器
$stream = new StreamHandler(__DIR__.'/my_app.log', Logger::DEBUG);
$firephp = new FirePHPHandler();

// 建立應用的主要日誌服務實例
$logger = new Logger('my_logger');
$logger->pushHandler($stream);
$logger->pushHandler($firephp);

// 使用另外的通道來建立安全相關的日誌服務示例
$securityLogger = new Logger('security');
$securityLogger->pushHandler($stream);
$securityLogger->pushHandler($firephp);

// 或者克隆第一個，只是改變下通道
$securityLogger = $logger->withName('security');

自定義日誌格式

在Monolog中，能夠很簡單地來自定義日誌的格式，不管是寫入文件、套接字、郵件、數據庫仍是其餘處理器。大多數處理器都是用 $record['formatted'] 這個值來自動寫入日誌設備。這個值依賴格式化器的配置。你能夠選擇預約義的格式化器類，也能夠本身寫一個（好比一個可讀的多行文本文件）。

想要配置一個預約義的格式化器類，能夠直接把它設置爲處理器的字段：

// 默認的日期格式是 "Y-m-d H:i:s"
$dateFormat = "Y n j, g:i a";
// 默認的輸出格式是 "[%datetime%] %channel%.%level_name%: %message% %context% %extra%\n"
$output = "%datetime% > %level_name% > %message% %context% %extra%\n";
// 最後建立一個格式化器
$formatter = new LineFormatter($output, $dateFormat);

// 建立一個處理器
$stream = new StreamHandler(__DIR__.'/my_app.log', Logger::DEBUG);
$stream->setFormatter($formatter);

// 將其綁定到日誌服務對象上
$securityLogger = new Logger('security');
$securityLogger->pushHandler($stream);

// 你還能夠在多個處理器之間複用同一個格式化器，而且在多個日誌服務實例間共享這些處理器。

處理器、格式化器和加工程序 →

---

說明：本文首發地址：https://www.clarencep.com/201...，轉載請註明出處，若有翻譯得不當之處歡迎指正。