# 错误处理
Yii 内置了一个yii\web\ErrorHandler错误处理器，它使错误处理更方便， Yii错误处理器做以下工作来提升错误处理效果：
* 所有非致命PHP错误（如，警告，提示）会转换成可获取异常；
* 异常和致命的PHP错误会被显示，在调试模式会显示详细的函数调用栈和源代码行数。
* 支持使用专用的 [控制器操作](http://www.yiichina.com/doc/guide/2.0/structure-controllers#actions) 来显示错误；
* 支持不同的错误响应格式；
yii\web\ErrorHandler 错误处理器默认启用， 可通过在应用的[入口脚本](http://www.yiichina.com/doc/guide/2.0/structure-entry-scripts)中定义常量`YII_ENABLE_ERROR_HANDLER`来禁用。
## 使用错误处理器
yii\web\ErrorHandler 注册成一个名称为`errorHandler`[应用组件](http://www.yiichina.com/doc/guide/2.0/structure-application-components)， 可以在应用配置中配置它类似如下：
~~~
return [
'components' => [
'errorHandler' => [
'maxSourceLines' => 20,
],
],
];
~~~
使用如上代码，异常页面最多显示20条源代码。
如前所述，错误处理器将所有非致命PHP错误转换成可获取异常，也就是说可以使用如下代码处理PHP错误：
~~~
use Yii;
use yii\base\ErrorException;
try {
10/0;
} catch (ErrorException $e) {
Yii::warning("Division by zero.");
}
// execution continues...
~~~
如果你想显示一个错误页面告诉用户请求是无效的或无法处理的，可简单地抛出一个 yii\web\HttpException异常， 如 yii\web\NotFoundHttpException。错误处理器会正确地设置响应的HTTP状态码并使用合适的错误视图页面来显示错误信息。
~~~
use yii\web\NotFoundHttpException;
throw new NotFoundHttpException();
~~~
## 自定义错误显示
yii\web\ErrorHandler错误处理器根据常量`YII_DEBUG`的值来调整错误显示， 当`YII_DEBUG` 为 true (表示在调试模式)，错误处理器会显示异常以及详细的函数调用栈和源代码行数来帮助调试， 当`YII_DEBUG` 为 false，只有错误信息会被显示以防止应用的敏感信息泄漏。
> 补充: 如果异常是继承 yii\base\UserException，不管`YII_DEBUG`为何值，函数调用栈信息都不会显示， 这是因为这种错误会被认为是用户产生的错误，开发人员不需要去修正。
yii\web\ErrorHandler 错误处理器默认使用两个[视图](http://www.yiichina.com/doc/guide/2.0/structure-views)显示错误:
* `@yii/views/errorHandler/error.php`: 显示不包含函数调用栈信息的错误信息是使用， 当`YII_DEBUG` 为 false时，所有错误都使用该视图。
* `@yii/views/errorHandler/exception.php`: 显示包含函数调用栈信息的错误信息时使用。
可以配置错误处理器的 yii\web\ErrorHandler::errorView 和 yii\web\ErrorHandler::exceptionView 属性 使用自定义的错误显示视图。
### 使用错误操作
使用指定的错误[操作](http://www.yiichina.com/doc/guide/2.0/structure-controllers) 来自定义错误显示更方便， 为此，首先配置`errorHandler`组件的 yii\web\ErrorHandler::errorAction 属性，类似如下：
~~~
return [
'components' => [
'errorHandler' => [
'errorAction' => 'site/error',
],
]
];
~~~
yii\web\ErrorHandler::errorAction 属性使用[路由](http://www.yiichina.com/doc/guide/2.0/structure-controllers#routes)到一个操作， 上述配置表示不用显示函数调用栈信息的错误会通过执行`site/error`操作来显示。
可以创建`site/error` 操作如下所示：
~~~
namespace app\controllers;
use Yii;
use yii\web\Controller;
class SiteController extends Controller
{
public function actions()
{
return [
'error' => [
'class' => 'yii\web\ErrorAction',
],
];
}
}
~~~
上述代码定义`error` 操作使用yii\web\ErrorAction 类，该类渲染名为`error`视图来显示错误。
除了使用yii\web\ErrorAction, 可定义`error` 操作使用类似如下的操作方法：
~~~
public function actionError()
{
$exception = Yii::$app->errorHandler->exception;
if ($exception !== null) {
return $this->render('error', ['exception' => $exception]);
}
}
~~~
现在应创建一个视图文件为`views/site/error.php`，在该视图文件中，如果错误操作定义为yii\web\ErrorAction， 可以访问该操作中定义的如下变量：
* `name`: 错误名称
* `message`: 错误信息
* `exception`: 更多详细信息的异常对象，如HTTP 状态码，错误码，错误调用栈等。
> 补充: 如果你使用 [基础应用模板](http://www.yiichina.com/doc/guide/2.0/start-installation) 或 [高级应用模板](http://www.yiichina.com/doc/guide/2.0/tutorial-advanced-app), 错误操作和错误视图已经定义好了。
### 自定义错误格式
错误处理器根据[响应](http://www.yiichina.com/doc/guide/2.0/runtime-responses)设置的格式来显示错误， 如果yii\web\Response::format 响应格式为`html`, 会使用错误或异常视图来显示错误信息，如上一小节所述。 对于其他的响应格式，错误处理器会错误信息作为数组赋值给yii\web\Response::data属性，然后转换到对应的格式， 例如，如果响应格式为`json`，可以看到如下响应信息：
~~~
HTTP/1.1 404 Not Found
Date: Sun, 02 Mar 2014 05:31:43 GMT
Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y
Transfer-Encoding: chunked
Content-Type: application/json; charset=UTF-8
{
"name": "Not Found Exception",
"message": "The requested resource was not found.",
"code": 0,
"status": 404
}
~~~
可在应用配置中响应`response`组件的`beforeSend`事件来自定义错误响应格式。
~~~
return [
// ...
'components' => [
'response' => [
'class' => 'yii\web\Response',
'on beforeSend' => function ($event) {
$response = $event->sender;
if ($response->data !== null) {
$response->data = [
'success' => $response->isSuccessful,
'data' => $response->data,
];
$response->statusCode = 200;
}
},
],
],
];
~~~
上述代码会重新格式化错误响应，类似如下：
~~~
HTTP/1.1 200 OK
Date: Sun, 02 Mar 2014 05:31:43 GMT
Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y
Transfer-Encoding: chunked
Content-Type: application/json; charset=UTF-8
{
"success": false,
"data": {
"name": "Not Found Exception",
"message": "The requested resource was not found.",
"code": 0,
"status": 404
}
}
~~~
- 介绍（Introduction）
- 关于 Yii（About Yii）
- 从 Yii 1.1 升级（Upgrading from Version 1.1）
- 入门（Getting Started）
- 安装 Yii（Installing Yii）
- 运行应用（Running Applications）
- 第一次问候（Saying Hello）
- 使用 Forms（Working with Forms）
- 玩转 Databases（Working with Databases）
- 用 Gii 生成代码（Generating Code with Gii）
- 更上一层楼（Looking Ahead）
- 应用结构（Application Structure）
- 结构概述（Overview）
- 入口脚本（Entry Scripts）
- 应用（Applications）
- 应用组件（Application Components）
- 控制器（Controllers）
- 模型（Models）
- 视图（Views）
- 模块（Modules）
- 过滤器（Filters）
- 小部件（Widgets）
- 前端资源（Assets）
- 扩展（Extensions）
- 请求处理（Handling Requests）
- 运行概述（Overview）
- 引导（Bootstrapping）
- 路由引导与创建 URL（Routing and URL Creation）
- 请求（Requests）
- 响应（Responses）
- Sessions and Cookies
- 错误处理（Handling Errors）
- 日志（Logging）
- 关键概念（Key Concepts）
- 组件（Components）
- 属性（Properties）
- 事件（Events）
- 行为（Behaviors）
- 配置（Configurations）
- 别名（Aliases）
- 类自动加载（Class Autoloading）
- 服务定位器（Service Locator）
- 依赖注入容器（Dependency Injection Container）
- 配合数据库工作（Working with Databases）
- 数据库访问（Data Access Objects）: 数据库连接、基本查询、事务和模式操作
- 查询生成器（Query Builder）: 使用简单抽象层查询数据库
- 活动记录（Active Record）: 活动记录对象关系映射（ORM），检索和操作记录、定义关联关系
- 数据库迁移（Migrations）: 在团体开发中对你的数据库使用版本控制
- Sphinx
- Redis
- MongoDB
- ElasticSearch
- 接收用户数据（Getting Data from Users）
- 创建表单（Creating Forms）
- 输入验证（Validating Input）
- 文件上传（Uploading Files）
- 收集列表输入（Collecting Tabular Input）
- 多模型同时输入（Getting Data for Multiple Models）
- 显示数据（Displaying Data）
- 格式化输出数据（Data Formatting）
- 分页（Pagination）
- 排序（Sorting）
- 数据提供器（Data Providers）
- 数据小部件（Data Widgets）
- 操作客户端脚本（Working with Client Scripts）
- 主题（Theming）
- 安全（Security）
- 认证（Authentication）
- 授权（Authorization）
- 处理密码（Working with Passwords）
- 客户端认证（Auth Clients）
- 安全领域的最佳实践（Best Practices）
- 缓存（Caching）
- 概述（Overview）
- 数据缓存（Data Caching）
- 片段缓存（Fragment Caching）
- 分页缓存（Page Caching）
- HTTP 缓存（HTTP Caching）
- RESTful Web 服务
- 快速入门（Quick Start）
- 资源（Resources）
- 控制器（Controllers）
- 路由（Routing）
- 格式化响应（Response Formatting）
- 授权验证（Authentication）
- 速率限制（Rate Limiting）
- 版本化（Versioning）
- 错误处理（Error Handling）
- 开发工具（Development Tools）
- 调试工具栏和调试器（Debug Toolbar and Debugger）
- 使用 Gii 生成代码（Generating Code using Gii）
- TBD 生成 API 文档（Generating API Documentation）
- 测试（Testing）
- 概述（Overview）
- 搭建测试环境（Testing environment setup）
- 单元测试（Unit Tests）
- 功能测试（Functional Tests）
- 验收测试（Acceptance Tests）
- 测试夹具（Fixtures）
- 高级专题（Special Topics）
- 高级应用模版（Advanced Project Template）
- 从头构建自定义模版（Building Application from Scratch）
- 控制台命令（Console Commands）
- 核心验证器（Core Validators）
- 国际化（Internationalization）
- 收发邮件（Mailing）
- 性能优化（Performance Tuning）
- 共享主机环境（Shared Hosting Environment）
- 模板引擎（Template Engines）
- 集成第三方代码（Working with Third-Party Code）
- 小部件（Widgets）
- Bootstrap 小部件（Bootstrap Widgets）
- jQuery UI 小部件（jQuery UI Widgets）
- 助手类（Helpers）
- 助手一览（Overview）
- Array 助手（ArrayHelper）
- Html 助手（Html）
- Url 助手（Url）