structure-controllers.md 15.9 KB
Newer Older
funson86 committed
1
控制器
2 3
===========

funson86 committed
4 5 6 7
控制器是 [MVC](http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) 模式中的一部分,
是继承[[yii\base\Controller]]类的对象,负责处理请求和生成响应。
具体来说,控制器从[应用主体](structure-applications.md)接管控制后会分析请求数据并传送到[模型](structure-models.md)
传送模型结果到[视图](structure-views.md),最后生成输出响应信息。
8 9


10
## 操作 <span id="actions"></span>
11

funson86 committed
12
控制器由 *操作* 组成,它是执行终端用户请求的最基础的单元,一个控制器可有一个或多个操作。
13

funson86 committed
14
如下示例显示包含两个操作`view` and `create` 的控制器`post`
15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52

```php
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,
            ]);
        }
    }
}
```

funson86 committed
53 54
在操作 `view` (定义为 `actionView()` 方法)中, 代码首先根据请求模型ID加载 [模型](structure-models.md)
如果加载成功,会渲染名称为`view`[视图](structure-views.md)并显示,否则会抛出一个异常。
55

funson86 committed
56 57
在操作 `create` (定义为 `actionCreate()` 方法)中, 代码相似. 先将请求数据填入[模型](structure-models.md)
然后保存模型,如果两者都成功,会跳转到ID为新创建的模型的`view`操作,否则显示提供用户输入的`create`视图。
58 59


60
## 路由 <span id="routes"></span>
61

funson86 committed
62
终端用户通过所谓的*路由*寻找到操作,路由是包含以下部分的字符串:
63

funson86 committed
64 65 66
* 模型ID: 仅存在于控制器属于非应用的[模块](structure-modules.md);
* 控制器ID: 同应用(或同模块如果为模块下的控制器)下唯一标识控制器的字符串;
* 操作ID: 同控制器下唯一标识操作的字符串。
67

funson86 committed
68
路由使用如下格式:
69 70 71 72 73

```
ControllerID/ActionID
```

funson86 committed
74
如果属于模块下的控制器,使用如下格式:
75 76 77 78 79

```php
ModuleID/ControllerID/ActionID
```

funson86 committed
80 81
如果用户的请求地址为 `http://hostname/index.php?r=site/index`, 会执行`site` 控制器的`index` 操作。
更多关于处理路由的详情请参阅 [路由](runtime-routing.md) 一节。
82 83


84
## 创建控制器 <span id="creating-controllers"></span>
85

funson86 committed
86 87 88
[[yii\web\Application|Web applications]]网页应用中,控制器应继承[[yii\web\Controller]] 或它的子类。
同理在[[yii\console\Application|console applications]]控制台应用中,控制器继承[[yii\console\Controller]] 或它的子类。
如下代码定义一个 `site` 控制器:
89 90 91 92 93 94 95 96 97 98 99 100

```php
namespace app\controllers;

use yii\web\Controller;

class SiteController extends Controller
{
}
```


101
### 控制器ID <span id="controller-ids"></span>
102

funson86 committed
103 104
通常情况下,控制器用来处理请求有关的资源类型,因此控制器ID通常为和资源有关的名词。
例如使用`article`作为处理文章的控制器ID。
105

funson86 committed
106 107
控制器ID应仅包含英文小写字母、数字、下划线、中横杠和正斜杠,
例如 `article``post-comment` 是真是的控制器ID,`article?`, `PostComment`, `admin\post`不是控制器ID。
108

funson86 committed
109 110 111
控制器Id可包含子目录前缀,例如 `admin/article` 代表
[[yii\base\Application::controllerNamespace|controller namespace]]控制器命名空间下 `admin`子目录中 `article` 控制器。
子目录前缀可为英文大小写字母、数字、下划线、正斜杠,其中正斜杠用来区分多级子目录(如 `panels/admin`)。
112 113


114
### 控制器类命名 <span id="controller-class-naming"></span>
115

funson86 committed
116
控制器ID遵循以下规则衍生控制器类名:
117

funson86 committed
118 119 120 121
* 将用正斜杠区分的每个单词第一个字母转为大写。注意如果控制器ID包含正斜杠,只将最后的正斜杠后的部分第一个字母转为大写;
* 去掉中横杠,将正斜杠替换为反斜杠;
* 增加`Controller`后缀;
* 在前面增加[[yii\base\Application::controllerNamespace|controller namespace]]控制器命名空间.
122

funson86 committed
123
下面为一些示例,假设[[yii\base\Application::controllerNamespace|controller namespace]]控制器命名空间为 `app\controllers`:
124

funson86 committed
125 126 127 128
* `article` 对应 `app\controllers\ArticleController`;
* `post-comment` 对应 `app\controllers\PostCommentController`;
* `admin/post-comment` 对应 `app\controllers\admin\PostCommentController`;
* `adminPanels/post-comment` 对应 `app\controllers\adminPanels\PostCommentController`.
129

funson86 committed
130 131 132
控制器类必须能被 [自动加载](concept-autoloading.md),所以在上面的例子中,
控制器`article` 类应在 [别名](concept-aliases.md)`@app/controllers/ArticleController.php`的文件中定义,
控制器`admin/post2-comment`应在`@app/controllers/admin/Post2CommentController.php`文件中。
133

funson86 committed
134 135 136
> 补充: 最后一个示例 `admin/post2-comment` 表示你可以将控制器放在
  [[yii\base\Application::controllerNamespace|controller namespace]]控制器命名空间下的子目录中,
  在你不想用 [模块](structure-modules.md) 的情况下给控制器分类,这种方式很有用。
137 138


139
### 控制器部署 <span id="controller-map"></span>
140

funson86 committed
141 142
可通过配置 [[yii\base\Application::controllerMap|controller map]] 来强制上述的控制器ID和类名对应,
通常用在使用第三方不能掌控类名的控制器上。
143

funson86 committed
144 145
配置 [应用配置](structure-applications.md#application-configurations) 
中的[application configuration](structure-applications.md#application-configurations),如下所示:
146 147 148 149

```php
[
    'controllerMap' => [
funson86 committed
150
        // 用类名申明 "account" 控制器
151 152
        'account' => 'app\controllers\UserController',

funson86 committed
153
        // 用配置数组申明 "article" 控制器
154 155 156 157 158 159 160 161 162
        'article' => [
            'class' => 'app\controllers\PostController',
            'enableCsrfValidation' => false,
        ],
    ],
]
```


163
### 默认控制器 <span id="default-controller"></span>
164

funson86 committed
165 166 167 168 169
每个应用有一个由[[yii\base\Application::defaultRoute]]属性指定的默认控制器;
当请求没有指定 [路由](#ids-routes),该属性值作为路由使用。
对于[[yii\web\Application|Web applications]]网页应用,它的值为 `'site'`
对于 [[yii\console\Application|console applications]]控制台应用,它的值为 `help`
所以URL为 `http://hostname/index.php` 表示由 `site` 控制器来处理。
170

funson86 committed
171
可以在 [应用配置](structure-applications.md#application-configurations) 中修改默认控制器,如下所示:
172 173 174 175 176 177 178 179

```php
[
    'defaultRoute' => 'main',
]
```


180
## 创建操作 <span id="creating-actions"></span>
181

funson86 committed
182 183
创建操作可简单地在控制器类中定义所谓的 *操作方法* 来完成,操作方法必须是以`action`开头的公有方法。
操作方法的返回值会作为响应数据发送给终端用户,如下代码定义了两个操作 `index``hello-world`:
184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204

```php
namespace app\controllers;

use yii\web\Controller;

class SiteController extends Controller
{
    public function actionIndex()
    {
        return $this->render('index');
    }

    public function actionHelloWorld()
    {
        return 'Hello World';
    }
}
```


205
### 操作ID <span id="action-ids"></span>
206

funson86 committed
207
操作通常是用来执行资源的特定操作,因此,操作ID通常为动词,如`view`, `update`等。
208

funson86 committed
209 210
操作ID应仅包含英文小写字母、数字、下划线和中横杠,操作ID中的中横杠用来分隔单词。
例如`view`, `update2`, `comment-post`是真实的操作ID,`view?`, `Update`不是操作ID.
211

funson86 committed
212 213 214 215
可通过两种方式创建操作ID,内联操作和独立操作. An inline action is
内联操作在控制器类中定义为方法;独立操作是继承[[yii\base\Action]]或它的子类的类。
内联操作容易创建,在无需重用的情况下优先使用;
独立操作相反,主要用于多个控制器重用,或重构为[扩展](structure-extensions.md)
216 217


218
### 内联操作 <span id="inline-actions"></span>
219

funson86 committed
220
内联操作指的是根据我们刚描述的操作方法。
221

funson86 committed
222
操作方法的名字是根据操作ID遵循如下规则衍生:
223

funson86 committed
224 225 226
* 将每个单词的第一个字母转为大写;
* 去掉中横杠;
* 增加`action`前缀.
227

funson86 committed
228
例如`index` 转成 `actionIndex`, `hello-world` 转成 `actionHelloWorld`
229

funson86 committed
230 231
> 注意: 操作方法的名字*大小写敏感*,如果方法名称为`ActionIndex`不会认为是操作方法,
  所以请求`index`操作会返回一个异常,也要注意操作方法必须是公有的,私有或者受保护的方法不能定义成内联操作。
232 233


funson86 committed
234 235
因为容易创建,内联操作是最常用的操作,但是如果你计划在不同地方重用相同的操作,
或者你想重新分配一个操作,需要考虑定义它为*独立操作*
236 237


238
### 独立操作 <span id="standalone-actions"></span>
239

funson86 committed
240 241
独立操作通过继承[[yii\base\Action]]或它的子类来定义。
例如Yii发布的[[yii\web\ViewAction]]和[[yii\web\ErrorAction]]都是独立操作。
242

funson86 committed
243
要使用独立操作,需要通过控制器中覆盖[[yii\base\Controller::actions()]]方法在*action map*中申明,如下例所示:
244 245 246 247 248

```php
public function actions()
{
    return [
funson86 committed
249
        // 用类来申明"error" 操作
250 251
        'error' => 'yii\web\ErrorAction',

funson86 committed
252
        // 用配置数组申明 "view" 操作
253 254 255 256 257 258 259 260
        'view' => [
            'class' => 'yii\web\ViewAction',
            'viewPrefix' => '',
        ],
    ];
}
```

funson86 committed
261 262
如上所示, `actions()` 方法返回键为操作ID、值为对应操作类名或数组[configurations](concept-configurations.md) 的数组。
和内联操作不同,独立操作ID可包含任意字符,只要在`actions()` 方法中申明.
263 264


funson86 committed
265 266
为创建一个独立操作类,需要继承[[yii\base\Action]] 或它的子类,并实现公有的名称为`run()`的方法,
`run()` 方法的角色和操作方法类似,例如:
267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283

```php
<?php
namespace app\components;

use yii\base\Action;

class HelloWorldAction extends Action
{
    public function run()
    {
        return "Hello World";
    }
}
```


284
### 操作结果 <span id="action-results"></span>
285

huoshi5151 committed
286
操作方法或独立操作的`run()`方法的返回值非常重要,它表示对应操作结果。
287

funson86 committed
288
返回值可为 [响应](runtime-responses.md) 对象,作为响应发送给终端用户。
289

funson86 committed
290 291 292 293
* 对于[[yii\web\Application|Web applications]]网页应用,返回值可为任意数据, 它赋值给[[yii\web\Response::data]],
  最终转换为字符串来展示响应内容。
* 对于[[yii\console\Application|console applications]]控制台应用,返回值可为整数,
  表示命令行下执行的 [[yii\console\Response::exitStatus|exit status]] 退出状态。
294

funson86 committed
295 296
在上面的例子中,操作结果都为字符串,作为响应数据发送给终端用户,下例显示一个操作通过
返回响应对象(因为[[yii\web\Controller::redirect()|redirect()]]方法返回一个响应对象)可将用户浏览器跳转到新的URL。
297 298 299 300

```php
public function actionForward()
{
funson86 committed
301
    // 用户浏览器跳转到 http://example.com
302 303 304 305 306
    return $this->redirect('http://example.com');
}
```


307
### 操作参数 <span id="action-parameters"></span>
308

funson86 committed
309 310 311 312
内联操作的操作方法和独立操作的 `run()` 方法可以带参数,称为*操作参数*
参数值从请求中获取,对于[[yii\web\Application|Web applications]]网页应用,
每个操作参数的值从`$_GET`中获得,参数名作为键;
对于[[yii\console\Application|console applications]]控制台应用, 操作参数对应命令行参数。
313

funson86 committed
314
如下例,操作`view` (内联操作) 申明了两个参数 `$id``$version`
315 316 317 318 319 320 321 322 323 324 325 326 327 328 329

```php
namespace app\controllers;

use yii\web\Controller;

class PostController extends Controller
{
    public function actionView($id, $version = null)
    {
        // ...
    }
}
```

funson86 committed
330
操作参数会被不同的参数填入,如下所示:
331

funson86 committed
332 333 334 335 336 337
* `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']`而不是字符串.
338

funson86 committed
339
如果想让操作参数接收数组值,需要指定$id为`array`,如下所示:
340 341 342 343 344 345 346 347

```php
public function actionView(array $id, $version = null)
{
    // ...
}
```

funson86 committed
348 349 350
现在如果请求为 `http://hostname/index.php?r=post/view&id[]=123`, 参数 `$id` 会使用数组值`['123']`
如果请求为 `http://hostname/index.php?r=post/view&id=123`
参数 `$id` 会获取相同数组值,因为无类型的`'123'`会自动转成数组。
351

funson86 committed
352
上述例子主要描述网页应用的操作参数,对于控制台应用,更多详情请参阅[控制台命令](tutorial-console.md)
353 354


355
### 默认操作 <span id="default-action"></span>
356

funson86 committed
357 358
每个控制器都有一个由 [[yii\base\Controller::defaultAction]] 属性指定的默认操作,
[路由](#ids-routes) 只包含控制器ID,会使用所请求的控制器的默认操作。
359

funson86 committed
360
默认操作默认为 `index`,如果想修改默认操作,只需简单地在控制器类中覆盖这个属性,如下所示:
361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378

```php
namespace app\controllers;

use yii\web\Controller;

class SiteController extends Controller
{
    public $defaultAction = 'home';

    public function actionHome()
    {
        return $this->render('home');
    }
}
```


379
## 控制器生命周期 <span id="controller-lifecycle"></span>
380

huoshi5151 committed
381
处理一个请求时,[应用主体](structure-applications.md) 会根据请求[路由](#routes)创建一个控制器,控制器经过以下生命周期来完成请求:
382

funson86 committed
383 384 385 386 387 388 389 390
1. 在控制器创建和配置后,[[yii\base\Controller::init()]] 方法会被调用。
2. 控制器根据请求操作ID创建一个操作对象:
   * 如果操作ID没有指定,会使用[[yii\base\Controller::defaultAction|default action ID]]默认操作ID;
   * 如果在[[yii\base\Controller::actions()|action map]]找到操作ID,会创建一个独立操作;
   * 如果操作ID对应操作方法,会创建一个内联操作;
   * 否则会抛出[[yii\base\InvalidRouteException]]异常。
3. 控制器按顺序调用应用主体、模块(如果控制器属于模块)、控制器的 `beforeAction()` 方法;
   * 如果任意一个调用返回false,后面未调用的`beforeAction()`会跳过并且操作执行会被取消;
391
     action execution will be cancelled.
funson86 committed
392 393 394 395 396 397
   * 默认情况下每个 `beforeAction()` 方法会触发一个 `beforeAction` 事件,在事件中你可以追加事件处理操作;
4. 控制器执行操作:
   * 请求数据解析和填入到操作参数;
5. 控制器按顺序调用控制器、模块(如果控制器属于模块)、应用主体的 `afterAction()` 方法;
   * 默认情况下每个 `afterAction()` 方法会触发一个 `afterAction` 事件,在事件中你可以追加事件处理操作;
6. 应用主体获取操作结果并赋值给[响应](runtime-responses.md).
398 399


400
## 最佳实践 <span id="best-practices"></span>
401

funson86 committed
402 403
在设计良好的应用中,控制器很精练,包含的操作代码简短;
如果你的控制器很复杂,通常意味着需要重构,转移一些代码到其他类中。
404

funson86 committed
405
归纳起来,控制器
406

funson86 committed
407 408 409 410 411
* 可访问 [请求](runtime-requests.md) 数据;
* 可根据请求数据调用 [模型](structure-models.md) 的方法和其他服务组件;
* 可使用 [视图](structure-views.md) 构造响应;
* 不应处理应被[模型](structure-models.md)处理的请求数据;
* 应避免嵌入HTML或其他展示代码,这些代码最好在 [视图](structure-views.md)中处理.