错误与日志

简介

当你开始一个新的 Laravel 项目时，Laravel 已经帮你配置好错误和异常处理的操作。另外，Laravel 也集成了 Monolog 日志函数库，Monolog 支持和提供多种强大的日志处理功能。

设置

错误细节

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

在开发的时候，你应该将 APP_DEBUG 环境变量设置为 true。在你的上线环境中，这个值应该永远为 false。

日志模式

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

  1. 'log' => 'daily'

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

  1. 'log_max_files' => 30

自定义 Monolog 设置

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

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

默认情况下，Laravel 对所有的错误级别进行记录，你可以通过定制 app.php 的 log_level 设置项来限制错误记录级别。Laravel 会记录大于或者等于你设置的 log_level 的值，例如：设置 log_level 为 error 级别的话，Laravel 会记录 error, critical, alert, 和 emergency 级别的错误。

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

错误处理

所有的异常处理都是通过 App\Exceptions\Handler 类。这个类包含了两个方法：report 和 render。我们将具体研究这些方法的细节。

报告方法

report 方法用来记录异常或将它们发送到像是 BugSnag 的外部服务上。默认情况下，当异常被记录时，report 方法只是简单的发送异常到基类，当然你也可以随意的来记录这些异常。

例如，如果你需要以不同的方式报告不同类型的异常，则可以使用 PHP instanceof 比较运算符：

  1. /**
  2.  * 报告或记录一个异常。
  3.  *
  4.  * 这里是个把异常送至 Sentry、Bugsnag 等等的好地方。
  5.  *
  6.  * @param  \Exception  $e
  7.  * @return void
  8.  */
  9. public function report(Exception $e)
  10. {
  11.     if ($e instanceof CustomException) {
  12.         //
  13.     }
  15.     return parent::report($e);
  16. }

借助类型忽略异常

异常处理中的 $dontReport 属性是一个数组，包含不需要被记录的异常类型。默认情况下，由 404 错误导致的异常结果并不会被记录到日志文件。你可以根据你的需求增加其它异常类型到这个数组中。

render 方法

render 方法负责将指定的异常转换成 HTTP 响应再发送到浏览器。默认情况下，异常会被发送到基类并帮你生成响应。但你可以随意检查异常类型或返回自定义的响应：

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

HTTP 异常

有一些异常是用于描述来自服务器的 HTTP 错误码。例如，这可能是个「找不到页面」错误（404），「未授权错误」（401），或甚至是开发者导致的 500 错误。你可以使用以下方法在应用程序的任何地方生成响应：

  1. abort(404);

abort 方法通过错误处理将会立即引发异常，并且呈现错误。或者，你可以提供响应的文本消息：

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

你可以在请求的生命周期中的任何时间点使用这个方法。

自定义 HTTP 错误页面

你可以简单的对于各种不同的 HTTP 状态码返回自定义的错误视图。例如，如果你想要自定义 HTTP 404 状态码的错误视图，则可以创建一个 resources/views/errors/404.blade.php 文件。应用程序将会使用这个视图处理所有发生的 404 错误。

产生的异常在视图里面会以变量 $exception 存在，你可以利用其来显示错误信息：

  1. $exception->getMessage()

在这个目录下的视图，命名应该匹配对应到 HTTP 状态码。

日志

Laravel 日志工具在强大的 Monolog 函数库上提供多一层简单的功能。Laravel 默认为应用程序创建每日的日志文件并保存在 storage/logs 目录。你可以使用 Log facade 来将信息写入到日志上：

  1. <?php
  3. namespace App\Http\Controllers;
  5. use Log;
  6. use App\User;
  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($error);
  2. Log::alert($error);
  3. Log::critical($error);
  4. Log::error($error);
  5. Log::warning($error);
  6. Log::notice($error);
  7. Log::info($error);
  8. Log::debug($error);

上下文消息

传入上下文相关的数据数组到日志方法里。此上下文的相关数据会进行格式化并显示在日志消息上：

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

访问 Monolog 底层实例

Monolog 支持各式各样的附加处理方法。如果需要的话，可以访问 Laravel 底层的 Monolog 实例：

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

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

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

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