错误与日志 · 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>