錯誤與日志 · laravel 5.4

<article><h1>Laravel 的錯誤和日志記錄</h1><ul><li><a href="#introduction">簡介</a></li><li><a href="#configuration">配置</a><ul><li><a href="#error-detail">顯示錯誤信息</a></li><li><a href="#log-storage">日志存儲</a></li><li><a href="#log-severity-levels">日志等級</a></li><li><a href="#custom-monolog-configuration">自定義 Monolog 設置</a></li></ul></li><li><a href="#the-exception-handler">異常處理</a><ul><li><a href="#report-method">Report 方法</a></li><li><a href="#render-method">Render 方法</a></li></ul></li><li><a href="#http-exceptions">HTTP 異常</a><ul><li><a href="#custom-http-error-pages">自定義錯誤頁面</a></li></ul></li><li><a href="#logging">記錄</a></li></ul><a name="introduction"></a><h2><a href="#introduction">簡介</a></h2>當您啟動一個新的 Laravel 項目時，錯誤和異常處理就已為您配置。應用程序觸發的所有異常都被 <code class=" language-php">App\Exceptions\Handler</code> 類記錄下來，然后渲染給用戶。我們將在本文檔中深入介紹此類。Laravel 使用功能強大的 <a href="https://github.com/Seldaek/monolog">Monolog</a> 庫進行日志處理。Laravel 配置了多幾種日志處理 handler ，方便您在單個日志文件、多個交替日志文件之間進行選擇寫入或將錯誤信息寫入系統日志。<a name="configuration"></a><h2><a href="#configuration">配置</a></h2><a name="error-detail"></a><h3>顯示錯誤信息</h3><code class=" language-php">config/app.php</code> 文件的 <code class=" language-php">debug</code> 選項，決定了是否向用戶顯示錯誤信息。默認情況下，此選項設置為存儲在 <code class=" language-php">.env</code> 文件中的  <code class=" language-php">APP_DEBUG</code> 環境變量中。開發環境下，應該將 <code class=" language-php">APP_DEBUG</code> 環境變量設置為 <code class=" language-php">true</code> 。在您的生產環境中，此值應始終為 <code class=" language-php">false</code> 。如果在生產中將該值設置為 <code class=" language-php">true</code> ，則可能會將敏感的配置值暴露給應用程序的最終用戶。<a name="log-storage"></a><h3>日志存儲</h3>開箱即用，Laravel 支持 <code class=" language-php">single</code> 、<code class=" language-php">daily</code> 、 <code class=" language-php">syslog</code> 和 <code class=" language-php">errorlog</code> 日志模式。要配置 Laravel 使用的存儲機制，應該修改 <code class=" language-php">config/app.php</code> 配置文件中的 <code class=" language-php">log</code> 選項。例如，如果您希望使用每日一個日志文件而不是單個文件，則應將 <code class=" language-php">app</code> 配置文件中的 <code class=" language-php">log</code> 值設置為 <code class=" language-php">daily</code>：<pre class=" language-php"><code class=" language-php">'log' => 'daily'</code></pre><h4>日志保存天數限制</h4>使用 <code class=" language-php">daily</code> 日志模式時，Laravel 將只保留五天默認的日志文件。如果你想調整保留文件的數量，您可以添加一個 <code class=" language-php">log_max_files</code> 配置項目到 <code class=" language-php">APP</code> 配置文件：<pre class=" language-php"><code class=" language-php">'log_max_files' => 30</code></pre><a name="log-severity-levels"></a><h3>日志等級</h3>使用 Monolog 時，日志消息可能具有不同的日志等級。默認情況下，Laravel 將所有日志級別寫入存儲。但是，在生產環境中，您可能希望通過將 <code class=" language-php">log_level</code> 選項添加到 <code class=" language-php">app.php</code> 配置文件中來配置應記錄的最低日志等級。一旦配置了此選項，Laravel 將記錄大于或等于指定日志等級的所有級別。例如，默認將 <code class=" language-php">log_level</code> 設置為 <code class=" language-php">error</code> 那么將會記錄 error , critical , alert 和 emergency 日志信息：<pre class=" language-php"><code class=" language-php">'log_level' => env('APP_LOG_LEVEL', 'error'),</code></pre><blockquote class="has-icon tip"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="56.6px" height="87.5px" viewBox="0 0 56.6 87.5" enable-background="new 0 0 56.6 87.5" xml:space="preserve"><path fill="#FFFFFF" d="M28.7 64.5c-1.4 0-2.5-1.1-2.5-2.5v-5.7 -5V41c0-1.4 1.1-2.5 2.5-2.5s2.5 1.1 2.5 2.5v10.1 5 5.8C31.2 63.4 30.1 64.5 28.7 64.5zM26.4 0.1C11.9 1 0.3 13.1 0 27.7c-0.1 7.9 3 15.2 8.2 20.4 0.5 0.5 0.8 1 1 1.7l3.1 13.1c0.3 1.1 1.3 1.9 2.4 1.9 0.3 0 0.7-0.1 1.1-0.2 1.1-0.5 1.6-1.8 1.4-3l-2-8.4 -0.4-1.8c-0.7-2.9-2-5.7-4-8 -1-1.2-2-2.5-2.7-3.9C5.8 35.3 4.7 30.3 5.4 25 6.7 14.5 15.2 6.3 25.6 5.1c13.9-1.5 25.8 9.4 25.8 23 0 4.1-1.1 7.9-2.9 11.2 -0.8 1.4-1.7 2.7-2.7 3.9 -2 2.3-3.3 5-4 8L41.4 53l-2 8.4c-0.3 1.2 0.3 2.5 1.4 3 0.3 0.2 0.7 0.2 1.1 0.2 1.1 0 2.2-0.8 2.4-1.9l3.1-13.1c0.2-0.6 0.5-1.2 1-1.7 5-5.1 8.2-12.1 8.2-19.8C56.4 12 42.8-1 26.4 0.1zM43.7 69.6c0 0.5-0.1 0.9-0.3 1.3 -0.4 0.8-0.7 1.6-0.9 2.5 -0.7 3-2 8.6-2 8.6 -1.3 3.2-4.4 5.5-7.9 5.5h-4.1H28h-0.5 -3.6c-3.5 0-6.7-2.4-7.9-5.7l-0.1-0.4 -1.8-7.8c-0.4-1.1-0.8-2.1-1.2-3.1 -0.1-0.3-0.2-0.5-0.2-0.9 0.1-1.3 1.3-2.1 2.6-2.1H41C42.4 67.5 43.6 68.2 43.7 69.6zM37.7 72.5H26.9c-4.2 0-7.2 3.9-6.3 7.9 0.6 1.3 1.8 2.1 3.2 2.1h4.1 0.5 0.5 3.6c1.4 0 2.7-0.8 3.2-2.1L37.7 72.5z"></path></svg></div> Monolog 識別以下日志等級 - 從低到高為: <code class=" language-php">debug</code> , <code class=" language-php">info</code> , <code class=" language-php">notice</code> , <code class=" language-php">warning</code> , <code class=" language-php">error</code> , <code class=" language-php">critical</code> , <code class=" language-php">alert</code> , <code class=" language-php">emergency</code>。</blockquote><a name="custom-monolog-configuration"></a><h3>自定義 Monolog 設置</h3>如果你想讓你的應用程序完全控制 Monolog ，可以使用應用程序的 <code class=" language-php">configureMonologUsing</code> 方法。你應該放置一個回調方法到 <code class=" language-php">bootstrap/app.php</code> 文件中，在文件返回 <code class=" language-php">$app</code> 變量之前，調用這個方法：<pre class=" language-php"><code class=" language-php">$app->configureMonologUsing(function ($monolog) { $monolog->pushHandler(...); }); return $app;</code></pre><a name="the-exception-handler"></a><h2><a href="#the-exception-handler">異常處理</a></h2><a name="report-method"></a><h3>Report 方法</h3>所有異常都由 <code class=" language-php">App\Exceptions\Handler</code> 類處理。這個類包含兩個方法：<code class=" language-php">report</code> 和 <code class=" language-php">render</code> 。我們將詳細研究這些方法。 <code class=" language-php">report</code> 方法用于記錄異常或將其發送到外部服務，如 <a href="https://bugsnag.com">Bugsnag</a> 或 <a href="https://github.com/getsentry/sentry-laravel">Sentry</a> 。默認情況下，<code class=" language-php">report</code> 方法只是將異常傳遞給記錄異常的基類。然而，你可以自由選擇任何方式進行處理。例如，如果您需要以不同的方式報告不同類型的異常，您可以使用 PHP <code class=" language-php">instanceof</code> 比較運算符：<pre class=" language-php"><code class=" language-php">/** * 報告或記錄異常 * * 這是一個很棒的位置向 Sentry ，Bugsnag 等發送異常。 * * @param \Exception $exception * @return void */ public function report(Exception $exception) { if ($exception instanceof CustomException) { // } return parent::report($exception); }</code></pre><h4>通過類型忽略異常</h4>異常 handler 的 <code class=" language-php">$dontReport</code> 屬性包含不會記錄的異常類型數組。例如，404錯誤導致的異常以及其他幾種類型的錯誤不會寫入您的日志文件。您可以根據需要向此數組添加其他異常類型：<pre class=" language-php"><code class=" language-php">/** * 不應報告的異常類型列表 * * @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, ];</code></pre><a name="render-method"></a><h3>Render 方法</h3><code class=" language-php">render</code> 方法負責將異常轉換成 HTTP 響應發送給瀏覽器。默認情況下，異常會傳遞給為您生成響應的基類。但是，您可以自由檢查異常類型或返回您自己的自定義響應：<pre class=" language-php"><code class=" language-php">/** * 渲染異常并添加到 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); }</code></pre><a name="http-exceptions"></a><h2><a href="#http-exceptions">HTTP 異常</a></h2>一些異常描述了來自服務器的 HTTP 錯誤代碼。例如這可能是「找不到頁面」錯誤（404），「未授權錯誤」（401）或甚至開發者生成的500錯誤。你可以使用 <code class=" language-php">abort</code> 函數，在應用程序中的任何地方生成這樣的響應：<pre class=" language-php"><code class=" language-php">abort(404);</code></pre><code class=" language-php">abort</code>函數將立即創建一個被渲染的異常。此外，您還可以提供響應文本：<pre class=" language-php"><code class=" language-php">abort(403, 'Unauthorized action.');</code></pre><a name="custom-http-error-pages"></a><h3>自定義錯誤頁面</h3>Laravel 可以輕松地顯示各種HTTP狀態代碼的自定義錯誤頁面。例如，如果您要自定義404 HTTP狀態代碼的錯誤頁面，請創建一個 <code class=" language-php">resources/views/errors/404.blade.php</code> 。此文件將會用于渲染所有404錯誤。此目錄中的視圖文件命名應與它們對應的HTTP狀態代碼匹配。由 <code class=" language-php">abort</code> 函數引發的 <code class=" language-php">HttpException</code> 實例將作為 <code class=" language-php">$exception</code> 變量傳遞給視圖。<a name="logging"></a><h2><a href="#logging">記錄</a></h2>Laravel 在強大的 <a href="https://github.com/seldaek/monolog">Monolog</a> 庫上提供了一個簡單的抽象層。默認情況下，Laravel 日志目錄為 <code class=" language-php">storage/logs</code> 。您可以使用 <code class=" language-php">Log</code> <a href="/docs/5.4/facades">facade</a> :將信息寫入日志：<pre class=" language-php"><code class=" language-php"><?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)]); } }</code></pre>該日志記錄器提供八種 <a href="https://tools.ietf.org/html/rfc5424">RFC 5424</a> :定義的日志級別: emergency ，alert ，critical, error ，warning ，notice ，info 和 debug 。<pre class=" language-php"><code class=" language-php">Log::emergency($message); Log::alert($message); Log::critical($message); Log::error($message); Log::warning($message); Log::notice($message); Log::info($message); Log::debug($message);</code></pre><h4>上下文信息</h4>將上下文數據以數組格式傳遞給日志方法。此上下文數據將被格式化并與日志消息一起顯示：<pre class=" language-php"><code class=" language-php">Log::info('User failed to login.', ['id' => $user->id]);</code></pre><h4>訪問底層 Monolog 實例</h4>Monolog 還有多種其他的處理 handler ，你可以用來記錄。如果需要，您可以訪問 Laravel 底層的 Monolog 實例：<pre class=" language-php"><code class=" language-php">$monolog = Log::getMonolog();</code></pre><h2>譯者署名</h2><table><thead><tr><th>用戶名</th><th>頭像</th><th>職能</th><th>簽名</th></tr></thead><tbody><tr><td><a href="https://github.com/e421083458">@e421083458</a></td><td><img class="avatar-66 rm-style" src="https://dn-phphub.qbox.me/uploads/avatars/10802_1486368142.jpeg?imageView2/1/w/100/h/100"></td><td>翻譯</td><td>Github求star，<a href="https://github.com/e421083458/">@e421083458</a> at Github</td></tr></tbody></table></article>