十一、基础组件 —— 异常处理

简介

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

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

配置

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

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

异常处理器

   所有异常都由类 AppExceptionsHandler 处理，该类包含两个方法：report 和 render。下面我们详细阐述这两个方法。

report 方法

  report 方法用于记录异常并将其发送给外部服务如Bugsnag 或 Sentry，默认情况下，report 方法只是将异常传递给异常被记录的基类，当然你也可以按自己的需要记录异常并进行相关处理。

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

/**
 * 报告或记录异常
 *
 * This is a great spot to send exceptions to Sentry, Bugsnag, etc.
 *
 * @param  Exception  $e
 * @return void
 * @translator laravelacademy.org
 */
public function report(Exception $e){
    if ($e instanceof CustomException) {
        //
    }

    return parent::report($e);
}

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

   全局日志上下文

     如果当前用户 ID 可用的话，Laravel 会自动将其添加到每一条异常日志信息中作为上下文数据。你也可以通过重写 AppExceptionsHandler 类的 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 = [
    IlluminateAuthAuthenticationException::class,
    IlluminateAuthAccessAuthorizationException::class,
    SymfonyComponentHttpKernelExceptionHttpException::class,
    IlluminateDatabaseEloquentModelNotFoundException::class,
    IlluminateValidationValidationException::class,
];

   render 方法

   render 方法负责将给定异常转化为发送给浏览器的 HTTP 响应，默认情况下，异常被传递给为你生成响应的基类。当然，你也可以按照自己的需要检查异常类型或者返回自定义响应：

/**
 * 将异常渲染到HTTP响应中
 *
 * @param  IlluminateHttpRequest  $request
 * @param  Exception  $exception
 * @return IlluminateHttpResponse
 */
public function render($request, Exception $exception){
    if ($e instanceof CustomException) {
        return response()->view('errors.custom', [], 500);
    }

    return parent::render($request, $exception);
}

   可报告 & 可渲染的异常

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

<?php

namespace AppExceptions;

use Exception;

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

    /**
     * Render the exception into an HTTP response.
     *
     * @param  IlluminateHttpRequest
     * @return IlluminateHttpResponse
     */
    public function render($request)
    {
        return response(...);
    }
}

注：你可以在 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