错误与日志

简介

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

设置

错误细节

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

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

日志模式

Laravel 提供可立即使用的 singledailysyslogerrorlog 日志模式。例如,如果你想要每天保存一个日志文件,而不是单个文件,则可以在 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. });
  4. return $app;

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

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

错误处理

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

报告方法

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. }
  14. return parent::report($e);
  15. }

借助类型忽略异常

异常处理中的 $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. }
  13. return parent::render($request, $e);
  14. }

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
  2. namespace App\Http\Controllers;
  3. use Log;
  4. use App\User;
  5. use App\Http\Controllers\Controller;
  6. class UserController extends Controller
  7. {
  8. /**
  9. * 显示指定用户的个人数据。
  10. *
  11. * @param int $id
  12. * @return Response
  13. */
  14. public function showProfile($id)
  15. {
  16. Log::info('Showing user profile for user: '.$id);
  17. return view('user.profile', ['user' => User::findOrFail($id)]);
  18. }
  19. }

日志工具提供了定义在 RFC 5424 的八个级别: emergencyalertcriticalerrorwarningnoticeinfodebug

  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