控制器

控制器是 MVC 模式中的一部分，是继承 yii\base\Controller 类的对象，负责处理请求和生成响应。具体来说，控制器从 应用主体 接管控制后会分析请求数据并传送到 模型，传送模型结果到 视图，最后生成输出响应信息。

动作

控制器由 动作 组成，它是执行终端用户请求的最基础的单元，一个控制器可有一个或多个动作。如下示例，post 控制器包含 view and create 两个动作：

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 加载模型，如果加载成功，会渲染名称为 view 的视图并显示，否则会抛出一个异常。

在动作 create（定义为 actionCreate() 方法）中, 代码类似，先将请求数据填入模型，然后保存模型，如果两者都成功，会跳转到 ID 为新创建的模型的 view 动作，否则显示提供用户输入的 create 视图。

路由

终端用户通过所谓的路由寻找到动作，路由是包含以下部分的字符串：

• 模块 ID: 仅存在于控制器属于非应用的 模块;
• 控制器 ID: 同应用（或同模块如果为模块下的控制器）下唯一标识控制器的字符串;
• 动作 ID: 同控制器下唯一标识动作的字符串。

路由使用如下格式:

ControllerID/ActionID

如果属于模块下的控制器，使用如下格式：

ModuleID/ControllerID/ActionID

如果用户的请求地址为 http://hostname/index.php?r=site/index, 会执行 site 控制器的 index 动作。更多关于处理路由的详情请参阅 路由 一节。

创建控制器

在 Web 应用中，控制器应继承 yii\web\Controller 或它的子类。同理在控制台应用中，控制器继承 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 可包含子目录前缀，例如 admin/article 代表 [[yii\base\Application::controllerNamespace]] 控制器命名空间下 admin子目录中 article 控制器。子目录前缀可为英文大小写字母、数字、下划线、正斜杠，其中正斜杠用来区分多级子目录(如 panels/admin)。

控制器类命名

控制器 ID 遵循以下规则衍生控制器类名：

1. 将用正斜杠区分的每个单词第一个字母转为大写。注意如果控制器 ID 包含正斜杠，只将最后的正斜杠后的部分第一个字母转为大写；
2. 去掉中横杠，将正斜杠替换为反斜杠;
3. 增加 Controller 后缀;
4. 在前面增加 [[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.

控制器类必须能被 自动加载，所以在上面的例子中，控制器 article 类应在 别名 为 @app/controllers/ArticleController.php 的文件中定义，控制器 admin/post-comment 应在 @app/controllers/admin/PostCommentController.php 文件中。

Info: 其中一个示例 admin/post-comment 表示你可以将控制器放在 [[yii\base\Application::controllerNamespace]] 控制器命名空间下的子目录中，在你不想用模块的情况下给控制器分类，这种方式很有用。

控制器映射

可通过在应用配置中配置 [[yii\base\Application::controllerMap]] 属性来强制上述的控制器 ID 和类名映射，通常用在使用第三方不能掌控类名的控制器上，如下所示：

[
    'controllerMap' => [
        // 用类名申明 "account" 控制器
        'account' => 'app\controllers\UserController',

        // 用配置数组申明 "article" 控制器
        'article' => [
            'class' => 'app\controllers\PostController',
            'enableCsrfValidation' => false,
        ],
    ],
]

默认控制器

每个应用有一个由 [[yii\base\Application::defaultRoute]] 属性指定的默认控制器，当请求没有指定路由，该属性值将作为路由使用。对于 [[yii\web\Application]] 网页应用，它的值为 'site'，对于 [[yii\console\Application]] 控制台应用，它的值为 help，所以 URL为 http://hostname/index.php 表示由 site 控制器来处理，等价于 http://hostname/index.php?r=site。

您可以在应用配置中修改默认控制器，如下所示：

[
    'defaultRoute' => 'main',
]

创建动作

创建动作，可简单地在控制器类中定义所谓的 动作方法 来完成，它必须是以 action 开头的 public 方法。它的返回值会作为响应数据发送给终端用户，如下代码定义了 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 应仅包含英文小写字母、数字、下划线和中横杠，其中的中横杠用来分隔单词。例如, view, update2, comment-post 都是真实的动作 ID，而 view?, Update 不是。

可通过两种方式创建动作 ID，内联动作和独立动作。

内联动作

内联动作，指的是根据我们以上描述的，在控制器类中定义的动作方法。它的名字是可以根据动作 ID 遵循如下规则衍生：

1. 将每个单词的第一个字母转为大写;
2. 去掉中横杠;
3. 增加 action 前缀.

例如 index 转成 actionIndex, hello-world 转成 actionHelloWorld。

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

内联动作，因为容易创建，是最常用的动作，但是，如果你计划在不同地方复用一个相同的动作，或者你想重新分配一个动作，需要考虑定义它为独立动作。

独立动作

独立动作，一般通过继承 yii\base\Action 或它的子类来定义。与内联动作不同，主要用于在多个控制器中复用，或重构为一些 扩展。例如，Yii 自带的yii\web\ViewAction 和 yii\web\ErrorAction 都属于独立动作。

要使用独立动作，需要通过控制器中覆盖 [[yii\base\Controller::actions()]] 方法，并在动作映射中申明，如下例所示：

public function actions()
{
    return [
        // 用类来申明"error" 动作
        'error' => 'yii\web\ErrorAction',

        // 用配置数组申明 "view" 动作
        'view' => [
            'class' => 'yii\web\ViewAction',
            'viewPrefix' => '',
        ],
    ];
}

如上所示，actions() 方法返回键为动作 ID、值为对应操作类名 或配置 configurations 的数组。与内联动作不同，独立动作 ID 可包含任意字符，只要在actions() 方法中申明。

为创建一个独立动作类，需要继承 yii\base\Action 或它的子类，并实现公有的名称为 run() 的方法, 该方法扮演的角色和动作方法类似，例如：

<?php
namespace app\components;

use yii\base\Action;

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

动作结果

内联动作的方法或独立动作的 run() 方法的返回值非常重要，它表示对应动作结果。

返回值可为 yii\web\Response 对象，作为响应发送给终端用户。

• 对于 [[yii\web\Application]] Web 应用，返回值可为任意数据，它赋值给[[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]] Web 应用，每个动作参数的值从 $_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: 会抛出 400 异常（[[yii\web\BadRequestHttpException]]），因为请求没有提供参数给必须赋值参数 $id；
• http://hostname/index.php?r=post/view&id[]=123: 会抛出 400 异常（[[yii\web\BadRequestHttpException]]），因为 $id 参数收到数组值 ['123'] 而不是字符串。

如果你想要一个动作参数来接受数组值，你应该使用 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 会自动转成数组。

上述例子主要描述 Web 应用的操作参数，对于控制台应用的传参更多详情，请参阅 控制台命令。

默认动作

每个控制器都有一个由 [[yii\base\Controller::defaultAction]] 属性指定的默认动作，当路由只提供了控制器 ID，会使用所请求的控制器的默认动作，且它的默认值为 index，如果想修改它，只需简单地在控制器类中覆盖这个属性即可，如下所示：

namespace app\controllers;

use yii\web\Controller;

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

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

控制器生命周期

处理一个请求时，应用主体会根据请求路由，解析创建一个控制器，控制器经过以下生命周期来完成请求：

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() 会跳过并且动作执行会被取消；
   • 默认情况下每个 beforeAction() 方法会触发一个 beforeAction 事件，在事件中你可以追加事件处理动作；
4. 控制器执行动作:
   • 请求数据解析和填入到动作参数；
5. 控制器按顺序调用控制器、模块（如果控制器属于模块）、应用主体的 afterAction() 方法；
   • 默认情况下每个 afterAction() 方法会触发一个 afterAction 事件，在事件中你可以追加事件处理动作；
6. 应用主体获取动作结果并赋值给响应对象

最佳实践

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

归纳起来，控制器

• 可访问请求组件的数据;
• 可根据请求数据调用模型的方法和其他服务组件;
• 可使用视图构造响应;
• 不应处理应被模型处理的请求数据;
• 应避免嵌入HTML或其他展示代码，这些代码最好在视图中处理.

💖喜欢本文档的，欢迎点赞、收藏、留言或转发，谢谢支持！
作者邮箱：zhuzixian520@126.com，github地址：github.com/zhuzixian520