錯誤與日志 · laravel 5.3 中文文檔

# 錯誤與日志 - [簡介](#introduction) - [設置](#configuration) - [錯誤細節](#error-detail) - [日志儲存](#log-storage) - [日志嚴重級別](#log-severity-levels) - [自定義 Monolog 配置](#custom-monolog-configuration) - [異常處理](#the-exception-handler) - [Report 方法](#report-method) - [render 方法](#render-method) - [HTTP 異常](#http-exceptions) - [自定義 HTTP 錯誤頁面](#custom-http-error-pages) - [日志](#logging) <a name="introduction"></a> ## 簡介當你創建一個新的 Laravel 項目時，Laravel 已經將錯誤和異常處理幫你配置好了。 `App\Exceptions\Handler` 類會將觸發異常記入日志并返回給用戶。本文會深入的對這個類進行探討。日志記錄，Laravel 利用 [Monolog](https://github.com/Seldaek/monolog) 函數庫提供多樣而強大的日志處理。 Laravel 配置了幾個處理程序給你，允許你選擇單個日志文件或多個來系統記錄錯誤信息。 <a name="configuration"></a> ## 設置 <a name="error-detail"></a> #### 錯誤細節你的應用程序通過 `config/app.php` 配置文件中的 `debug` 設置選項來控制瀏覽器對錯誤的細節顯示。默認情況下，此設置選項是參照于保存在 `.env` 文件的 `APP_DEBUG` 環境變量。在開發的時候，你應該將 `APP_DEBUG` 環境變量設置為 `true`。在你的上線環境中，這個值應該永遠為 `false`。如果在生產環境中將這個值設置為 `true`，你將冒風險將一些敏感配置信息暴露個最終用戶。 <a name="log-storage"></a> ### 日志存儲 Laravel 提供可立即使用的 `single`、`daily`、`syslog` 和 `errorlog` 日志模式。例如，如果你想要每天保存一個日志文件，而不是單個文件，則可以在 `config/app.php` 配置文件內設置 `log` 變量： 'log' => 'daily' #### 日志保存天數限制當使用 `daily` 日志模式時，默認情況下會保存 5 天的日志，你可通過 `app.php` 配置文件里的配置項 `log_max_files` 來定制日志保存天數： 'log_max_files' => 30 <a name="log-severity-levels"></a> ### 日志記錄級別使用 Monolog 時, log 信息可以有不同的嚴重級別。默認，Laravel 將所有級別日志寫到 storage ，然而在你的生產環境中，你可能希望配置一個最小嚴重級別，那么你應該添加 `log_level` 選項到你的 `app.php` 配置文件。一旦該選項被配置，Laravel 會記錄所有大于或等于這個級別的日志。例如，一個默認 `log_level` 是 `error` 那么將會記錄 **error**, **critical**, **alert** 和 **emergency** 信息： 'log_level' => env('APP_LOG_LEVEL', 'error'), > {tip} Monolog 辨識以下嚴重級別 - 最低到高為： `debug`, `info`, `notice`, `warning`, `error`, `critical`, `alert`, `emergency` 。 <a name="custom-monolog-configuration"></a> ### 自定義 Monolog 設置如果你想要完全控制 Monolog，則使用應用程序的 `configureMonologUsing` 方法。此方法應該在 `bootstrap/app.php` 文件返回 `$app` 變量之前被調用： $app->configureMonologUsing(function($monolog) { $monolog->pushHandler(...); }); return $app; <a name="the-exception-handler"></a> ## 異常處理 <a name="report-method"></a> ### Report 方法所有異常處理都由 `App\Exceptions\Handler` 類進行。這個類包含兩個方法：`report` 和 `render`。我們將研究這些方法的細節。`report` 方法方法用于記錄異常或將異常寄給外部服務如 [Bugsnag](https://bugsnag.com) 或 [Sentry](https://github.com/getsentry/sentry-laravel) 。默認， `report` 方法簡單地通過傳遞異常到基類進行處理，然而，你可以自由選擇任何方式進行處理。例如，如果你需要將不同的異常類型報告給不同的方法，你可以使用 PHP `instanceof` 比較操作符： /** * 報告或記錄異常。 * * 這是一個很棒的位置將異常發送到 Sentry ，Bugsnag ，etc 。 * * @param \Exception $exception * @return void */ public function report(Exception $exception) { if ($exception instanceof CustomException) { // } return parent::report($exception); } #### 通過類型忽略異常 `$dontReport` 屬性包含一個不會被記錄的異常類型數組。例如，404 異常以及其他幾個類型異常不會被寫到你的日志文件中，如果需要你可以添加其他異常類型這個數組： /** * 不需要報告的異常類型列表。 * * @var array */ protected $dontReport = [ \Illuminate\Auth\AuthenticationException::class, \Illuminate\Auth\Access\AuthorizationException::class, \Symfony\Component\HttpKernel\Exception\HttpException::class, \Illuminate\Database\Eloquent\ModelNotFoundException::class, \Illuminate\Validation\ValidationException::class, ]; <a name="render-method"></a> ### Render 方法 `render` 方法負責將異常轉換成 HTTP 響應發送給瀏覽器。默認，異常傳遞給生成響應的基類，然而你也可以自由的想檢查異常類型或返回自定義響應： /** * 渲染異常并添加到響應中。 * * @param \Illuminate\Http\Request $request * @param \Exception $exception * @return \Illuminate\Http\Response */ public function render($request, Exception $exception) { if ($exception instanceof CustomException) { return response()->view('errors.custom', [], 500); } return parent::render($request, $exception); } <a name="http-exceptions"></a> ## HTTP 異常一些異常描述來自服務器的 HTTP 錯誤碼。例如這個方法可以是一個「頁面未找到」錯誤 (404)，一個「認證失敗錯誤」 (401) 或者一個開發人員生成的 500 錯誤。為了在應用中生成一個這樣的響應，你可以使用 `abort` 輔助函數： abort(404); `abort` 輔助函數將會立即引發一個被異常處理器渲染的異常。此外，你還可以提供響應文本： abort(403, 'Unauthorized action.'); <a name="custom-http-error-pages"></a> ### 自定義 HTTP 錯誤頁面 Laravel 制作自定義的 HTTP 錯誤顯示頁面很簡單。例如，如果你想定義一個 404 頁面，創建一個 `resources/views/errors/404.blade.php` 。這個文件將會用于渲染所有的 404 錯誤。這個視圖目錄中的視圖命名應該和·對于的 HTTP 狀態碼相匹配。 `HttpException` 實例會將 `abort` 函數傳遞到視圖作為 `$exception` 變量. <a name="logging"></a> ## 日志 Laravel 用強大的 [Monolog](http://github.com/seldaek/monolog) 函數庫提供一個簡單日志抽象層。默認，Laravel 會在 `storage/logs` 目錄下創建一個日志文件。你可以使用 `Log` [facade](/docs/{{version}}/facades) 寫入信息： <?php namespace App\Http\Controllers; use App\User; use Illuminate\Support\Facades\Log; use App\Http\Controllers\Controller; class UserController extends Controller { /** * 顯示指定用戶的詳情。 * * @param int $id * @return Response */ public function showProfile($id) { Log::info('Showing user profile for user: '.$id); return view('user.profile', ['user' => User::findOrFail($id)]); } } 該日志記錄器提供八種 [RFC 5424](http://tools.ietf.org/html/rfc5424) 定義的日志級別: **emergency** ，**alert** ，**critical**, **error** ，**warning** ，**notice** ，**info** 和 **debug** 。 Log::emergency($message); Log::alert($message); Log::critical($message); Log::error($message); Log::warning($message); Log::notice($message); Log::info($message); Log::debug($message); #### 上下文信息一個數組上下文信息數據也會傳遞給日志方法，上下文信息數據也會被格式化記錄在日志信息中： Log::info('User failed to login.', ['id' => $user->id]); #### 訪問底層 Monolog 實例 Monolog 有一個多樣的日志處理器，如果你需要，你可以訪問 Laravel 底層的 Monolog 實例： $monolog = Log::getMonolog(); ## 譯者署名 | 用戶名 | 頭像 | 職能 | 簽名 | |---|---|---|---| | [@麥索](https://github.com/dongm2ez) | <img class="avatar-66 rm-style" src="https://avatars3.githubusercontent.com/u/9032795?v=3&s=460?imageView2/1/w/100/h/100"> | 翻譯 | 程序界的小學生，目前生活在北京，希望能夠多結交大牛。Follow me [@dongm2ez](https://github.com/dongm2ez) at Github