错误处理


简介

Laravel 默认已经为我们配置好了错误和异常处理,我们在 App\Exceptions\Handler 类中触发异常并将响应返回给用户。在本文档中我们将深入探讨这个类。

注:关于 Laravel 异常处理底层原理和实现可以参考学院的这篇教程了解更多 —— 《深入探讨 PHP 错误异常处理机制及 Laravel 框架底层的相应实现》

配置

配置文件 config/app.php 中的 debug 配置项控制浏览器显示的错误信息数量。默认情况下,该配置项通过 .env 文件中的环境变量 APP_DEBUG 进行设置。

对本地开发而言,你应该设置环境变量 APP_DEBUG 值为 true。在生产环境,该值应该被设置为 false。如果在生产环境被设置为 true,就有可能将一些敏感的配置值暴露给终端用户。

异常处理器

报告异常

所有异常都由 App\Exceptions\Handler 类处理。这个类包含了一个 register 方法用于注册自定义的异常报告器和渲染器回调,接下来我们会详细介绍这些概念。我们可以通过异常报告记录异常或者将它们发送给外部服务,比如 FlareBugsnag 以及 Sentry。默认情况下,会基于日志配置记录异常,不过,你也可以按照自己期望的方式进行自定义。

例如,如果你需要以不同方式报告不同类型的异常,可以使用 reportable 方法注册一个闭包,该闭包会在给定类型异常需要被报告时执行。Laravel 会通过检查闭包的参数类型提示推断该闭包报告的异常类型:

use App\Exceptions\CustomException;

/**
 * Register the exception handling callbacks for the application.
 *
 * @return void
 */
public function register()
{
    $this->reportable(function (CustomException $e) {
        //
    });
}

当你使用 reportable 方法注册自定义异常报告回调时,Laravel 仍然会使用应用默认的日志配置记录异常。如果你想要停止异常传播到默认的日志栈(不记录到日志系统),可以 在定义异常回调时使用 stop 方法:

$this->reportable(function (CustomException $e) {
    //
})->stop();

注:可以考虑使用可报告的异常来取代在 reports 方法中进行大量的 instanceof 检查。

全局日志上下文

如果当前用户 ID 可用的话,Laravel 会自动将其添加到每一条异常日志信息中作为上下文数据。你也可以通过重写 App\Exceptions\Handler 类的 context 方法来定义自己的全局上下文数据,该信息会被包含在应用写入的每一条异常日志信息中:

/**
 * Get the default context variables for logging.
 *
 * @return array
 */
protected function context()
{
    return array_merge(parent::context(), [
        'foo' => 'bar',
    ]);
}

report 辅助函数

有时候你可能需要报告一个异常并继续处理当前请求。辅助函数 report 允许你使用异常处理器的 report 方法快速报告一个异常而不会渲染错误页:

public function isValid($value)
{
    try {
        // Validate the value...
    } catch (Exception $e) {
        report($e);
    
        return false;
    }
}

通过类型忽略异常

异常处理器的 $dontReport 属性包含一个不会被记录的异常类型数组,默认情况下,404 错误异常不会被写到日志文件,如果需要的话你可以添加其他异常类型到这个数组:

/**
 * 不应该被报告的异常类型列表.
 *
 * @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,
];

渲染异常

默认情况下,Laravel 异常处理器会将异常转化为 HTTP 响应,不过,你也可以为给定类型异常注册自定义的渲染闭包。这可以通过定义异常处理器的 renderable 方法来实现,Laravel 会检查闭包的参数类型提示推断该闭包要渲染的异常类型:

use App\Exceptions\CustomException;

/**
 * Register the exception handling callbacks for the application.
 *
 * @return void
 */
public function register()
{
    $this->renderable(function (CustomException $e, $request) {
        return response()->view('errors.custom', [], 500);
    });
}

可报告 & 可渲染的异常

除了在异常处理器的 reportrender 方法中进行异常类型检查外,还可以在自定义异常中直接定义 reportrender 方法。当异常中存在这些方法时,框架会自动调用它们:

<?php

namespace App\Exceptions;

use Exception;

class RenderException extends Exception
{
    /**
     * Report the exception.
     *
     * @return void
     */
    public function report()
    {
        //
    }

    /**
     * Render the exception into an HTTP response.
     *
     * @param  \Illuminate\Http\Request
     * @return \Illuminate\Http\Response
     */
    public function render($request)
    {
        return response(...);
    }
}

如果你的异常包含只有在特定条件才会出现的自定义报告逻辑,需要告知 Laravel 使用默认的异常处理配置报告这个异常。要实现这个功能,可以从异常的 report 方法中返回 false

/**
 * Report the exception.
 *
 * @return bool|void
 */
public function report()
{
    // Determine if the exception needs custom reporting...

    return false;
}

注:你可以在 report 方法中注入任何需要的依赖,它们会通过 Laravel 服务容器自动解析。

HTTP 异常

有些异常描述来自服务器的 HTTP 错误码,例如,这可能是一个“页面未找到”错误(404),“认证失败错误”(401)亦或是程序出错造成的 500 错误,为了在应用中生成这样的响应,可以使用 abort 辅助函数:

abort(404);

abort 辅助函数会立即引发一个会被异常处理器渲染的异常,此外,你还可以像这样提供响应描述:

abort(403, '未授权操作');

该方法可在请求生命周期的任何时间点使用。

自定义 HTTP 错误页面

在 Laravel 中,返回不同 HTTP 状态码的错误页面很简单,例如,如果你想要自定义 404 错误页面,创建一个 resources/views/errors/404.blade.php 文件,该视图文件用于渲染程序返回的所有 404 错误。需要注意的是,该目录下的视图命名应该和相应的 HTTP 状态码相匹配。abort 函数触发的 HttpException 异常会以 $exception 变量的方式传递给视图:

<h2>{{ $exception->getMessage() }}</h2>

你可以使用 Artisan 命令 vendor:publish 发布 Laravel 的错误页面模板:

php artisan vendor:publish --tag=laravel-errors

模板被发布后,就可以按照自己的喜好对其进行自定义。

相关教程


Vote Vote Cancel Collect Collect Cancel

<< 上一篇: 验证

>> 下一篇: 日志