# 控制器
控制器是 [MVC](http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) 模式中的一部分， 是继承yii\base\Controller类的对象，负责处理请求和生成响应。 具体来说，控制器从[应用主体](http://www.yiichina.com/doc/guide/2.0/structure-applications)接管控制后会分析请求数据并传送到[模型](http://www.yiichina.com/doc/guide/2.0/structure-models)， 传送模型结果到[视图](http://www.yiichina.com/doc/guide/2.0/structure-views)，最后生成输出响应信息。
## 操作
控制器由 *操作* 组成，它是执行终端用户请求的最基础的单元，一个控制器可有一个或多个操作。
如下示例显示包含两个操作`view` and `create` 的控制器`post`：
~~~
namespace app\controllers;
use Yii;
use app\models\Post;
use yii\web\Controller;
use yii\web\NotFoundHttpException;
class PostController extends Controller
{
public function actionView($id)
{
$model = Post::findOne($id);
if ($model === null) {
throw new NotFoundHttpException;
}
return $this->render('view', [
'model' => $model,
]);
}
public function actionCreate()
{
$model = new Post;
if ($model->load(Yii::$app->request->post()) && $model->save()) {
return $this->redirect(['view', 'id' => $model->id]);
} else {
return $this->render('create', [
'model' => $model,
]);
}
}
}
~~~
在操作 `view` (定义为 `actionView()` 方法)中， 代码首先根据请求模型ID加载 [模型](http://www.yiichina.com/doc/guide/2.0/structure-models)， 如果加载成功，会渲染名称为`view`的[视图](http://www.yiichina.com/doc/guide/2.0/structure-views)并显示，否则会抛出一个异常。
在操作 `create` (定义为 `actionCreate()` 方法)中, 代码相似. 先将请求数据填入[模型](http://www.yiichina.com/doc/guide/2.0/structure-models)， 然后保存模型，如果两者都成功，会跳转到ID为新创建的模型的`view`操作，否则显示提供用户输入的`create`视图。
## 路由
终端用户通过所谓的*路由*寻找到操作，路由是包含以下部分的字符串：
* 模型ID: 仅存在于控制器属于非应用的[模块](http://www.yiichina.com/doc/guide/2.0/structure-modules);
* 控制器ID: 同应用（或同模块如果为模块下的控制器）下唯一标识控制器的字符串;
* 操作ID: 同控制器下唯一标识操作的字符串。
路由使用如下格式:
~~~
ControllerID/ActionID
~~~
如果属于模块下的控制器，使用如下格式：
~~~
ModuleID/ControllerID/ActionID
~~~
如果用户的请求地址为 `http://hostname/index.php?r=site/index`, 会执行`site` 控制器的`index` 操作。 更多关于处理路由的详情请参阅 [路由](http://www.yiichina.com/doc/guide/2.0/runtime-routing) 一节。
## 创建控制器
在yii\web\Application网页应用中，控制器应继承yii\web\Controller 或它的子类。 同理在yii\console\Application控制台应用中，控制器继承yii\console\Controller 或它的子类。 如下代码定义一个 `site` 控制器:
~~~
namespace app\controllers;
use yii\web\Controller;
class SiteController extends Controller
{
}
~~~
### 控制器ID
通常情况下，控制器用来处理请求有关的资源类型，因此控制器ID通常为和资源有关的名词。 例如使用`article`作为处理文章的控制器ID。
控制器ID应仅包含英文小写字母、数字、下划线、中横杠和正斜杠， 例如 `article` 和 `post-comment` 是真是的控制器ID，`article?`, `PostComment`, `admin\post`不是控制器ID。
控制器Id可包含子目录前缀，例如 `admin/article` 代表 yii\base\Application::controllerNamespace控制器命名空间下 `admin`子目录中 `article` 控制器。 子目录前缀可为英文大小写字母、数字、下划线、正斜杠，其中正斜杠用来区分多级子目录(如`panels/admin`)。
### 控制器类命名
控制器ID遵循以下规则衍生控制器类名：
* 将用正斜杠区分的每个单词第一个字母转为大写。注意如果控制器ID包含正斜杠，只将最后的正斜杠后的部分第一个字母转为大写；
* 去掉中横杠，将正斜杠替换为反斜杠;
* 增加`Controller`后缀;
* 在前面增加yii\base\Application::controllerNamespace控制器命名空间.
下面为一些示例，假设yii\base\Application::controllerNamespace控制器命名空间为 `app\controllers`:
* `article` 对应 `app\controllers\ArticleController`;
* `post-comment` 对应 `app\controllers\PostCommentController`;
* `admin/post-comment` 对应 `app\controllers\admin\PostCommentController`;
* `adminPanels/post-comment` 对应 `app\controllers\adminPanels\PostCommentController`.
控制器类必须能被 [自动加载](http://www.yiichina.com/doc/guide/2.0/concept-autoloading)，所以在上面的例子中， 控制器`article` 类应在 [别名](http://www.yiichina.com/doc/guide/2.0/concept-aliases) 为`@app/controllers/ArticleController.php`的文件中定义， 控制器`admin/post2-comment`应在`@app/controllers/admin/Post2CommentController.php`文件中。
> 补充: 最后一个示例 `admin/post2-comment` 表示你可以将控制器放在 yii\base\Application::controllerNamespace控制器命名空间下的子目录中， 在你不想用 [模块](http://www.yiichina.com/doc/guide/2.0/structure-modules) 的情况下给控制器分类，这种方式很有用。
### 控制器部署
可通过配置 yii\base\Application::controllerMap 来强制上述的控制器ID和类名对应， 通常用在使用第三方不能掌控类名的控制器上。
配置 [应用配置](http://www.yiichina.com/doc/guide/2.0/structure-applications#application-configurations) 中的[application configuration](http://www.yiichina.com/doc/guide/2.0/structure-applications#application-configurations)，如下所示：
~~~
[
'controllerMap' => [
// 用类名申明 "account" 控制器
'account' => 'app\controllers\UserController',
// 用配置数组申明 "article" 控制器
'article' => [
'class' => 'app\controllers\PostController',
'enableCsrfValidation' => false,
],
],
]
~~~
### 默认控制器
每个应用有一个由yii\base\Application::defaultRoute属性指定的默认控制器； 当请求没有指定 [路由](http://www.yiichina.com/doc/guide/2.0/structure-controllers#ids-routes)，该属性值作为路由使用。 对于yii\web\Application网页应用，它的值为 `'site'`， 对于 yii\console\Application控制台应用，它的值为 `help`， 所以URL为`http://hostname/index.php` 表示由 `site` 控制器来处理。
可以在 [应用配置](http://www.yiichina.com/doc/guide/2.0/structure-applications#application-configurations) 中修改默认控制器，如下所示：
~~~
[
'defaultRoute' => 'main',
]
~~~
## 创建操作
创建操作可简单地在控制器类中定义所谓的 *操作方法* 来完成，操作方法必须是以`action`开头的公有方法。 操作方法的返回值会作为响应数据发送给终端用户，如下代码定义了两个操作 `index` 和 `hello-world`:
~~~
namespace app\controllers;
use yii\web\Controller;
class SiteController extends Controller
{
public function actionIndex()
{
return $this->render('index');
}
public function actionHelloWorld()
{
return 'Hello World';
}
}
~~~
### 操作ID
操作通常是用来执行资源的特定操作，因此，操作ID通常为动词，如`view`, `update`等。
操作ID应仅包含英文小写字母、数字、下划线和中横杠，操作ID中的中横杠用来分隔单词。 例如`view`, `update2`, `comment-post`是真实的操作ID，`view?`, `Update`不是操作ID.
可通过两种方式创建操作ID，内联操作和独立操作. An inline action is 内联操作在控制器类中定义为方法；独立操作是继承yii\base\Action或它的子类的类。 内联操作容易创建，在无需重用的情况下优先使用； 独立操作相反，主要用于多个控制器重用，或重构为[扩展](http://www.yiichina.com/doc/guide/2.0/structure-extensions)。
### 内联操作
内联操作指的是根据我们刚描述的操作方法。
操作方法的名字是根据操作ID遵循如下规则衍生：
* 将每个单词的第一个字母转为大写;
* 去掉中横杠;
* 增加`action`前缀.
例如`index` 转成 `actionIndex`, `hello-world` 转成 `actionHelloWorld`。
> 注意: 操作方法的名字*大小写敏感*，如果方法名称为`ActionIndex`不会认为是操作方法， 所以请求`index`操作会返回一个异常，也要注意操作方法必须是公有的，私有或者受保护的方法不能定义成内联操作。
因为容易创建，内联操作是最常用的操作，但是如果你计划在不同地方重用相同的操作， 或者你想重新分配一个操作，需要考虑定义它为*独立操作*。
### 独立操作
独立操作通过继承yii\base\Action或它的子类来定义。 例如Yii发布的yii\web\ViewAction和yii\web\ErrorAction都是独立操作。
要使用独立操作，需要通过控制器中覆盖yii\base\Controller::actions()方法在*action map*中申明，如下例所示：
~~~
public function actions()
{
return [
// 用类来申明"error" 操作
'error' => 'yii\web\ErrorAction',
// 用配置数组申明 "view" 操作
'view' => [
'class' => 'yii\web\ViewAction',
'viewPrefix' => '',
],
];
}
~~~
如上所示， `actions()` 方法返回键为操作ID、值为对应操作类名或数组[configurations](http://www.yiichina.com/doc/guide/2.0/concept-configurations) 的数组。 和内联操作不同，独立操作ID可包含任意字符，只要在`actions()` 方法中申明.
为创建一个独立操作类，需要继承yii\base\Action 或它的子类，并实现公有的名称为`run()`的方法, `run()` 方法的角色和操作方法类似，例如：
~~~
<?php
namespace app\components;
use yii\base\Action;
class HelloWorldAction extends Action
{
public function run()
{
return "Hello World";
}
}
~~~
### 操作结果
操作方法或独立操作的`run()`方法的返回值非常重要，它表示对应操作结果。
返回值可为 [响应](http://www.yiichina.com/doc/guide/2.0/runtime-responses) 对象，作为响应发送给终端用户。
* 对于yii\web\Application网页应用，返回值可为任意数据, 它赋值给yii\web\Response::data， 最终转换为字符串来展示响应内容。
* 对于yii\console\Application控制台应用，返回值可为整数， 表示命令行下执行的 yii\console\Response::exitStatus 退出状态。
在上面的例子中，操作结果都为字符串，作为响应数据发送给终端用户，下例显示一个操作通过 返回响应对象（因为yii\web\Controller::redirect()方法返回一个响应对象）可将用户浏览器跳转到新的URL。
~~~
public function actionForward()
{
// 用户浏览器跳转到 http://example.com
return $this->redirect('http://example.com');
}
~~~
### 操作参数
内联操作的操作方法和独立操作的 `run()` 方法可以带参数，称为*操作参数*。 参数值从请求中获取，对于yii\web\Application网页应用， 每个操作参数的值从`$_GET`中获得，参数名作为键； 对于yii\console\Application控制台应用, 操作参数对应命令行参数。
如下例，操作`view` (内联操作) 申明了两个参数 `$id` 和 `$version`。
~~~
namespace app\controllers;
use yii\web\Controller;
class PostController extends Controller
{
public function actionView($id, $version = null)
{
// ...
}
}
~~~
操作参数会被不同的参数填入，如下所示：
* `http://hostname/index.php?r=post/view&id=123`: `$id` 会填入`'123'`，`$version` 仍为 null 空因为没有`version`请求参数;
* `http://hostname/index.php?r=post/view&id=123&version=2`: $id` 和 `$version` 分别填入 `'123'` 和 `'2'`；
* `http://hostname/index.php?r=post/view`: 会抛出yii\web\BadRequestHttpException 异常 因为请求没有提供参数给必须赋值参数`$id`；
* `http://hostname/index.php?r=post/view&id[]=123`: 会抛出yii\web\BadRequestHttpException 异常 因为`$id` 参数收到数字值 `['123']`而不是字符串.
如果想让操作参数接收数组值，需要指定$id为`array`，如下所示：
~~~
public function actionView(array $id, $version = null)
{
// ...
}
~~~
现在如果请求为 `http://hostname/index.php?r=post/view&id[]=123`, 参数 `$id` 会使用数组值`['123']`， 如果请求为`http://hostname/index.php?r=post/view&id=123`， 参数 `$id` 会获取相同数组值，因为无类型的`'123'`会自动转成数组。
上述例子主要描述网页应用的操作参数，对于控制台应用，更多详情请参阅[控制台命令](http://www.yiichina.com/doc/guide/2.0/tutorial-console)。
### 默认操作
每个控制器都有一个由 yii\base\Controller::defaultAction 属性指定的默认操作， 当[路由](http://www.yiichina.com/doc/guide/2.0/structure-controllers#ids-routes) 只包含控制器ID，会使用所请求的控制器的默认操作。
默认操作默认为 `index`，如果想修改默认操作，只需简单地在控制器类中覆盖这个属性，如下所示：
~~~
namespace app\controllers;
use yii\web\Controller;
class SiteController extends Controller
{
public $defaultAction = 'home';
public function actionHome()
{
return $this->render('home');
}
}
~~~
## 控制器生命周期
处理一个请求时，[应用主体](http://www.yiichina.com/doc/guide/2.0/structure-applications) 会根据请求[路由](http://www.yiichina.com/doc/guide/2.0/structure-controllers#routes)创建一个控制器，控制器经过以下生命周期来完成请求：
1. 在控制器创建和配置后，yii\base\Controller::init() 方法会被调用。
2. 控制器根据请求操作ID创建一个操作对象:
* 如果操作ID没有指定，会使用yii\base\Controller::defaultAction默认操作ID；
* 如果在yii\base\Controller::actions()找到操作ID，会创建一个独立操作；
* 如果操作ID对应操作方法，会创建一个内联操作；
* 否则会抛出yii\base\InvalidRouteException异常。
3. 控制器按顺序调用应用主体、模块（如果控制器属于模块）、控制器的 `beforeAction()` 方法；
* 如果任意一个调用返回false，后面未调用的`beforeAction()`会跳过并且操作执行会被取消； action execution will be cancelled.
* 默认情况下每个 `beforeAction()` 方法会触发一个 `beforeAction` 事件，在事件中你可以追加事件处理操作；
4. 控制器执行操作:
* 请求数据解析和填入到操作参数；
5. 控制器按顺序调用控制器、模块（如果控制器属于模块）、应用主体的 `afterAction()` 方法；
* 默认情况下每个 `afterAction()` 方法会触发一个 `afterAction` 事件，在事件中你可以追加事件处理操作；
6. 应用主体获取操作结果并赋值给[响应](http://www.yiichina.com/doc/guide/2.0/runtime-responses).
## 最佳实践
在设计良好的应用中，控制器很精练，包含的操作代码简短； 如果你的控制器很复杂，通常意味着需要重构，转移一些代码到其他类中。
归纳起来，控制器
* 可访问 [请求](http://www.yiichina.com/doc/guide/2.0/runtime-requests) 数据;
* 可根据请求数据调用 [模型](http://www.yiichina.com/doc/guide/2.0/structure-models) 的方法和其他服务组件;
* 可使用 [视图](http://www.yiichina.com/doc/guide/2.0/structure-views) 构造响应;
* 不应处理应被[模型](http://www.yiichina.com/doc/guide/2.0/structure-models)处理的请求数据;
* 应避免嵌入HTML或其他展示代码，这些代码最好在 [视图](http://www.yiichina.com/doc/guide/2.0/structure-views)中处理.
- 介绍（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）