错误与日志

简介

当你创建一个新的 Laravel 项目时，Laravel 已经将错误和异常处理帮你配置好了。 App\Exceptions\Handler 类会将触发异常记入日志并返回给用户。本文会深入的对这个类进行探讨。

日志记录，Laravel 利用 Monolog 函数库提供多样而强大的日志处理。 Laravel 配置了几个处理程序给你，允许你选择单个日志文件或多个来系统记录错误信息。

设置

错误细节

你的应用程序通过 config/app.php 配置文件中的 debug 设置选项来控制浏览器对错误的细节显示。默认情况下，此设置选项是参照于保存在 .env 文件的 APP_DEBUG 环境变量。

在开发的时候，你应该将 APP_DEBUG 环境变量设置为 true。在你的上线环境中，这个值应该永远为 false。 如果在生产环境中将这个值设置为 true，你将冒风险将一些敏感配置信息暴露给最终用户。

日志存储

Laravel 提供可立即使用的 single、daily、syslog 和 errorlog 日志模式。例如，如果你想要每天保存一个日志文件，而不是单个文件，则可以在 config/app.php 配置文件内设置 log 变量：

  1. 'log' => 'daily'

日志保存天数限制

当使用 daily 日志模式时，默认情况下会保存 5 天的日志，你可通过 app.php 配置文件里的配置项 log_max_files 来定制日志保存天数：

  1. 'log_max_files' => 30

日志记录级别

使用 Monolog 时，log 信息可以有不同的严重级别。默认，Laravel 将所有级别日志写到 storage ，然而在你的生产环境中，你可能希望配置一个最小严重级别，那么你应该添加 log_level 选项到你的 app.php 配置文件。

一旦该选项被配置，Laravel 会记录所有大于或等于这个级别的日志。例如，一个默认 log_level 是 error 那么将会记录 error, critical, alert 和 emergency 信息：

  1. 'log_level' => env('APP_LOG_LEVEL', 'error'),

{tip} Monolog 辨识以下严重级别 - 最低到高为： debug, info, notice, warning, error, critical, alert, emergency 。

自定义 Monolog 设置

如果你想要完全控制 Monolog，则使用应用程序的 configureMonologUsing 方法。此方法应该在 bootstrap/app.php 文件返回 $app 变量之前被调用：

  1. $app->configureMonologUsing(function($monolog) {
  2.     $monolog->pushHandler(...);
  3. });
  5. return $app;

异常处理

Report 方法

所有异常处理都由 App\Exceptions\Handler 类进行。这个类包含两个方法：report 和 render。 我们将研究这些方法的细节。report 方法用于记录异常或将异常寄给外部服务如 Bugsnag 或 Sentry 。默认 report 方法简单地通过传递异常到基类进行处理。然而，你可以自由选择任何方式进行处理。

例如，如果你需要将不同的异常类型报告给不同的方法，你可以使用 PHP instanceof 比较操作符：

  1. /**
  2.  * 报告或记录异常。
  3.  *
  4.  * 这是一个很棒的位置将异常发送到 Sentry ，Bugsnag ，etc 。
  5.  *
  6.  * @param  \Exception  $exception
  7.  * @return void
  8.  */
  9. public function report(Exception $exception)
  10. {
  11.     if ($exception instanceof CustomException) {
  12.         //
  13.     }
  15.     return parent::report($exception);
  16. }

通过类型忽略异常

$dontReport 属性包含一个不会被记录的异常类型数组。例如 404 异常以及其他几个类型异常不会被写到你的日志文件中，如果需要你可以添加其他异常类型这个数组：

  1. /**
  2.  * 不需要报告的异常类型列表。
  3.  *
  4.  * @var array
  5.  */
  6. protected $dontReport = [
  7.     \Illuminate\Auth\AuthenticationException::class,
  8.     \Illuminate\Auth\Access\AuthorizationException::class,
  9.     \Symfony\Component\HttpKernel\Exception\HttpException::class,
  10.     \Illuminate\Database\Eloquent\ModelNotFoundException::class,
  11.     \Illuminate\Validation\ValidationException::class,
  12. ];

Render 方法

render 方法负责将异常转换成 HTTP 响应发送给浏览器。默认，异常传递给生成响应的基类，然而你也可以自由的想检查异常类型或返回自定义响应：

  1. /**
  2.  * 渲染异常并添加到响应中。
  3.  *
  4.  * @param  \Illuminate\Http\Request  $request
  5.  * @param  \Exception  $exception
  6.  * @return \Illuminate\Http\Response
  7.  */
  8. public function render($request, Exception $exception)
  9. {
  10.     if ($exception instanceof CustomException) {
  11.         return response()->view('errors.custom', [], 500);
  12.     }
  14.     return parent::render($request, $exception);
  15. }

HTTP 异常

一些异常描述来自服务器的 HTTP 错误码。例如这个方法可以是一个「页面未找到」 错误 (404)，一个 「认证失败错误」 (401) 或者一个开发人员生成的 500 错误。为了在应用中生成一个这样的响应，你可以使用 abort 辅助函数：

  1. abort(404);

abort 辅助函数将会立即引发一个被异常处理器渲染的异常。此外，你还可以提供响应文本：

  1. abort(403, 'Unauthorized action.');

自定义 HTTP 错误页面

Laravel 制作自定义的 HTTP 错误显示页面很简单。例如，如果你想定义一个 404 页面，创建一个 resources/views/errors/404.blade.php 。这个文件将会用于渲染所有的 404 错误。这个视图目录中的视图命名应该和对应的 HTTP 状态码相匹配。 HttpException 实例会将 abort 函数传递到视图作为 $exception 变量。

日志

Laravel 用强大的 Monolog 函数库提供一个简单日志抽象层。默认，Laravel 会在 storage/logs 目录下创建一个日志文件。你可以使用 Log facade 写入信息：

  1. <?php
  3. namespace App\Http\Controllers;
  5. use App\User;
  6. use Illuminate\Support\Facades\Log;
  7. use App\Http\Controllers\Controller;
  9. class UserController extends Controller
  10. {
  11.     /**
  12.      * 显示指定用户的详情。
  13.      *
  14.      * @param  int  $id
  15.      * @return Response
  16.      */
  17.     public function showProfile($id)
  18.     {
  19.         Log::info('Showing user profile for user: '.$id);
  21.         return view('user.profile', ['user' => User::findOrFail($id)]);
  22.     }
  23. }

该日志记录器提供八种 RFC 5424 定义的日志级别： emergency ，alert ，critical ，error ，warning ，notice ，info 和 debug 。

  1. Log::emergency($message);
  2. Log::alert($message);
  3. Log::critical($message);
  4. Log::error($message);
  5. Log::warning($message);
  6. Log::notice($message);
  7. Log::info($message);
  8. Log::debug($message);

上下文信息

一个数组上下文信息数据也会传递给日志方法，上下文信息数据也会被格式化记录在日志信息中：

  1. Log::info('User failed to login.', ['id' => $user->id]);

访问底层 Monolog 实例

Monolog 有一个多样的日志处理器，如果你需要，你可以访问 Laravel 底层的 Monolog 实例：

  1. $monolog = Log::getMonolog();

译者署名

用户名 头像 职能 签名
@麦索 错误与日志 - 图1 翻译 程序界的小学生，目前生活在北京，希望能够多结交大牛。Follow me @dongm2ez at Github

{note} 欢迎任何形式的转载，但请务必注明出处，尊重他人劳动共创开源社区。

转载请注明：本文档由 Laravel China 社区 [laravel-china.org] 组织翻译，详见 翻译召集帖。

文档永久地址： http://d.laravel-china.org