错误处理

Yii 内置了一个[[yii\web\ErrorHandler|error handler]]错误处理器，它使错误处理更方便，
Yii错误处理器做以下工作来提升错误处理效果：

  • 所有非致命PHP错误（如，警告，提示）会转换成可获取异常；
  • 异常和致命的PHP错误会被显示，
    在调试模式会显示详细的函数调用栈和源代码行数。
  • 支持使用专用的 控制器操作 来显示错误；
  • 支持不同的错误响应格式；

[[yii\web\ErrorHandler|error handler]] 错误处理器默认启用，
可通过在应用的入口脚本中定义常量YII_ENABLE_ERROR_HANDLER来禁用。

" class="reference-link">使用错误处理器

[[yii\web\ErrorHandler|error handler]] 注册成一个名称为errorHandler应用组件，
可以在应用配置中配置它类似如下：

  1. return [
  2.     'components' => [
  3.         'errorHandler' => [
  4.             'maxSourceLines' => 20,
  5.         ],
  6.     ],
  7. ];

使用如上代码，异常页面最多显示20条源代码。

如前所述，错误处理器将所有非致命PHP错误转换成可获取异常，
也就是说可以使用如下代码处理PHP错误：

  1. use Yii;
  2. use yii\base\ErrorException;
  4. try {
  5.     10/0;
  6. } catch (ErrorException $e) {
  7.     Yii::warning("Division by zero.");
  8. }
  10. // execution continues...

如果你想显示一个错误页面告诉用户请求是无效的或无法处理的，
可简单地抛出一个 [[yii\web\HttpException|HTTP exception]]异常，
如 [[yii\web\NotFoundHttpException]]。
错误处理器会正确地设置响应的HTTP状态码并使用合适的错误视图页面来显示错误信息。

  1. use yii\web\NotFoundHttpException;
  3. throw new NotFoundHttpException();

" class="reference-link">自定义错误显示

[[yii\web\ErrorHandler|error handler]]错误处理器根据常量YII_DEBUG的值来调整错误显示，
当YII_DEBUG 为 true (表示在调试模式)，
错误处理器会显示异常以及详细的函数调用栈和源代码行数来帮助调试，
当YII_DEBUG 为 false，只有错误信息会被显示以防止应用的敏感信息泄漏。

Info: 如果异常是继承 [[yii\base\UserException]]，
不管YII_DEBUG为何值，函数调用栈信息都不会显示，
这是因为这种错误会被认为是用户产生的错误，开发人员不需要去修正。

[[yii\web\ErrorHandler|error handler]] 错误处理器默认使用两个视图显示错误:

  • @yii/views/errorHandler/error.php: 显示不包含函数调用栈信息的错误信息是使用，
    当YII_DEBUG 为 false时，所有错误都使用该视图。
  • @yii/views/errorHandler/exception.php: 显示包含函数调用栈信息的错误信息时使用。

可以配置错误处理器的 [[yii\web\ErrorHandler::errorView|errorView]] 和 [[yii\web\ErrorHandler::exceptionView|exceptionView]] 属性
使用自定义的错误显示视图。

" class="reference-link">使用错误动作

使用指定的错误操作 来自定义错误显示更方便，
为此，首先配置errorHandler组件的 [[yii\web\ErrorHandler::errorAction|errorAction]] 属性，
类似如下： 

  1. return [
  2.     'components' => [
  3.         'errorHandler' => [
  4.             'errorAction' => 'site/error',
  5.         ],
  6.     ]
  7. ];

[[yii\web\ErrorHandler::errorAction|errorAction]] 属性使用
路由到一个操作，
上述配置表示不用显示函数调用栈信息的错误会通过执行site/error操作来显示。

可以创建 site/error 动作如下所示：

  1. namespace app\controllers;
  3. use Yii;
  4. use yii\web\Controller;
  6. class SiteController extends Controller
  7. {
  8.     public function actions()
  9.     {
  10.         return [
  11.             'error' => [
  12.                 'class' => 'yii\web\ErrorAction',
  13.             ],
  14.         ];
  15.     }
  16. }

上述代码定义error 操作使用[[yii\web\ErrorAction]] 类，
该类渲染名为error视图来显示错误。

除了使用[[yii\web\ErrorAction]], 可定义error 动作使用类似如下的操作方法：

  1. public function actionError()
  2. {
  3.     $exception = Yii::$app->errorHandler->exception;
  4.     if ($exception !== null) {
  5.         return $this->render('error', ['exception' => $exception]);
  6.     }
  7. }

现在应创建一个视图文件为views/site/error.php，在该视图文件中，如果错误动作定义为[[yii\web\ErrorAction]]，
可以访问该动作中定义的如下变量：

  • name: 错误名称
  • message: 错误信息
  • exception: 更多详细信息的异常对象，如HTTP 状态码，
    错误码，错误调用栈等。

Note: 如果你使用 基础应用模板 或 高级应用模板,
错误动作和错误视图已经定义好了。

Note: 如果您需要在错误处理程序中重定向，请执行以下操作：

  1. Yii::$app->getResponse()->redirect($url)->send();
  2. return;

" class="reference-link">自定义错误格式

错误处理器根据响应设置的格式来显示错误，
如果[[yii\web\Response::format|response format]] 响应格式为html,
会使用错误或异常视图来显示错误信息，如上一小节所述。
对于其他的响应格式，错误处理器会错误信息作为数组赋值
给[[yii\web\Response::data]]属性，然后转换到对应的格式，
例如，如果响应格式为json，可以看到如下响应信息：

  1. HTTP/1.1 404 Not Found
  2. Date: Sun, 02 Mar 2014 05:31:43 GMT
  3. Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y
  4. Transfer-Encoding: chunked
  5. Content-Type: application/json; charset=UTF-8
  7. {
  8.     "name": "Not Found Exception",
  9.     "message": "The requested resource was not found.",
  10.     "code": 0,
  11.     "status": 404
  12. }

可在应用配置中响应response组件的
beforeSend事件来自定义错误响应格式。

  1. return [
  2.     // ...
  3.     'components' => [
  4.         'response' => [
  5.             'class' => 'yii\web\Response',
  6.             'on beforeSend' => function ($event) {
  7.                 $response = $event->sender;
  8.                 if ($response->data !== null) {
  9.                     $response->data = [
  10.                         'success' => $response->isSuccessful,
  11.                         'data' => $response->data,
  12.                     ];
  13.                     $response->statusCode = 200;
  14.                 }
  15.             },
  16.         ],
  17.     ],
  18. ];

上述代码会重新格式化错误响应，类似如下：

  1. HTTP/1.1 200 OK
  2. Date: Sun, 02 Mar 2014 05:31:43 GMT
  3. Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y
  4. Transfer-Encoding: chunked
  5. Content-Type: application/json; charset=UTF-8
  7. {
  8.     "success": false,
  9.     "data": {
  10.         "name": "Not Found Exception",
  11.         "message": "The requested resource was not found.",
  12.         "code": 0,
  13.         "status": 404
  14.     }
  15. }