錯誤與日志 · Laravel 5.4 完全開發手冊

* * * * * [TOC] ## 簡介當您啟動一個新的 Laravel 項目時，錯誤和異常處理就已為您配置。應用程序觸發的所有異常都被?`App\Exceptions\Handler`?類記錄下來，然后渲染給用戶。我們將在本文檔中深入介紹此類。 Laravel 使用功能強大的?[Monolog](https://github.com/Seldaek/monolog)?庫進行日志處理。Laravel 配置了多幾種日志處理 handler ，方便您在單個日志文件、多個交替日志文件之間進行選擇寫入或將錯誤信息寫入系統日志。 ## 配置 ### 顯示錯誤信息 `config/app.php`?文件的?`debug`?選項，決定了是否向用戶顯示錯誤信息。默認情況下，此選項設置為存儲在?`.env`?文件中的 ?`APP_DEBUG`?環境變量中。開發環境下，應該將?`APP_DEBUG`?環境變量設置為?`true`?。在您的生產環境中，此值應始終為?`false`?。如果在生產中將該值設置為?`true`?，則可能會將敏感的配置值暴露給應用程序的最終用戶。 ### 日志存儲開箱即用，Laravel 支持?`single`?、`daily`?、?`syslog`?和?`errorlog`?日志模式。要配置 Laravel 使用的存儲機制，應該修改?`config/app.php`?配置文件中的?`log`?選項。例如，如果您希望使用每日一個日志文件而不是單個文件，則應將?`app`?配置文件中的?`log`?值設置為?`daily`： ~~~ 'log' => 'daily' ~~~ #### 日志保存天數限制使用?`daily`?日志模式時，Laravel 將只保留五天默認的日志文件。如果你想調整保留文件的數量，您可以添加一個?`log_max_files`?配置項目到?`APP`?配置文件： ~~~ 'log_max_files' => 30 ~~~ ### 日志等級使用 Monolog 時，日志消息可能具有不同的日志等級。默認情況下，Laravel 將所有日志級別寫入存儲。但是，在生產環境中，您可能希望通過將?`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`。 ### 自定義 Monolog 設置如果你想讓你的應用程序完全控制 Monolog ，可以使用應用程序的?`configureMonologUsing`?方法。你應該放置一個回調方法到?`bootstrap/app.php`?文件中，在文件返回?`$app`?變量之前，調用這個方法： ~~~ $app->configureMonologUsing(function ($monolog) { $monolog->pushHandler(...); }); return $app; ~~~ ## 異常處理 ### Report 方法所有異常都由?`App\Exceptions\Handler`?類處理。這個類包含兩個方法：`report`?和?`render`?。我們將詳細研究這些方法。?`report`?方法用于記錄異常或將其發送到外部服務，如?[Bugsnag](https://bugsnag.com/)?或?[Sentry](https://github.com/getsentry/sentry-laravel)?。默認情況下，`report`?方法只是將異常傳遞給記錄異常的基類。然而，你可以自由選擇任何方式進行處理。例如，如果您需要以不同的方式報告不同類型的異常，您可以使用 PHP?`instanceof`?比較運算符： ~~~ /** * 報告或記錄異常 * * 這是一個很棒的位置向 Sentry ，Bugsnag 等發送異常。 * * @param \Exception $exception * @return void */ public function report(Exception $exception) { if ($exception instanceof CustomException) { // } return parent::report($exception); } ~~~ #### 通過類型忽略異常異常 handler 的?`$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, ]; ~~~ ### Render 方法 `render`?方法負責將異常轉換成 HTTP 響應發送給瀏覽器。默認情況下，異常會傳遞給為您生成響應的基類。但是，您可以自由檢查異常類型或返回您自己的自定義響應： ~~~ /** * 渲染異常并添加到 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); } ~~~ ## HTTP 異常一些異常描述了來自服務器的 HTTP 錯誤代碼。例如這可能是「找不到頁面」錯誤（404），「未授權錯誤」（401）或甚至開發者生成的500錯誤。你可以使用?`abort`?函數，在應用程序中的任何地方生成這樣的響應： ~~~ abort(404); ~~~ `abort`函數將立即創建一個被渲染的異常。此外，您還可以提供響應文本： ~~~ abort(403, 'Unauthorized action.'); ~~~ ### 自定義錯誤頁面 Laravel 可以輕松地顯示各種HTTP狀態代碼的自定義錯誤頁面。例如，如果您要自定義404 HTTP狀態代碼的錯誤頁面，請創建一個?`resources/views/errors/404.blade.php`?。此文件將會用于渲染所有404錯誤。此目錄中的視圖文件命名應與它們對應的HTTP狀態代碼匹配。由?`abort`?函數引發的?`HttpException`?實例將作為?`$exception`?變量傳遞給視圖。 ## 記錄 Laravel 在強大的?[Monolog](https://github.com/seldaek/monolog)?庫上提供了一個簡單的抽象層。默認情況下，Laravel 日志目錄為?`storage/logs`?。您可以使用?`Log`?[facade](Facades.md)?:將信息寫入日志： ~~~ <?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](https://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 還有多種其他的處理 handler ，你可以用來記錄。如果需要，您可以訪問 Laravel 底層的 Monolog 實例： ~~~ $monolog = Log::getMonolog(); ~~~