五 15 四月 2016

控制器

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

操作

“操作”是执行终端用户请求的最基础的单元，一个控制器中可以包含一个或多个操作。

如下示例展示了一个名为post的控制器，其中包含两个操作：view和create。

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

在view操作（定义为actionView()方法）中，代码首先会根据请求的模型ID加载模型，如果加载成功，会使用一个名为view的视图进行展示，否则会抛出一个异常。

在create操作（定义为actionCreate()方法）中，代码也是一样的。首先它会尝试将请求数据填充到模型中并且保存。如果两个操作都成功了的话会重定向到操作view，并且把新创建的模型的ID作为参数传递过去，否则就重定向到create视图。

路由

终端用户通过所谓的路由来定位操作，路由就是包含了如下部分的一个字符串：

• 模型ID：只有当控制器属于非应用模块时才会存在
• 控制器ID：同一个应用（如果是模块下的控制器那就是同一个模块）下可以唯一标识控制器的字符串
• 操作ID：同一个控制器下唯一标识操作的字符串

路由使用如下格式：

ControllerID/ActionID

如果是模块下的控制器，则使用如下格式：

ModuleID/ControllerID/ActionID

如果用户的请求地址是http://hostname/index.php?r=site/index，会执行site控制器下的index操作，详情请参考路由和URL生成器一节。

创建控制器

在yii\web\Application网页应用中，控制器应该继承yii\web\Controller或它的子类，同理，在yii\console\Application控制台应用中，控制器继承yii\console\Controller或它的子类。如下代码定义了一个site控制器：

<?php
namespace app\controllers;

use yii\web\Controller;

class SiteController extends Controller
{
}
?>

控制器ID

通常情况下，控制器用来处理有关的资源类型，因此，控制器ID通常为与资源有关的名词，例如使用article作为处理文章的控制器ID。

控制器ID应该只包含小写字母、数字、下划线、中横线和斜杠，例如aarticle和post-comment是合法的控制器ID，而article?、PostComment、admin\post则不是。

控制器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；

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

注意：在最后一个示例中，admin/post2-comment表示你可以将控制器放在yii\base\Application::controllerNamespace控制器命名空间的子目录下，当你不想用模块的时候，可以采用这种方式给控制器分类。

控制器Map

我们可以通过配置控制器Map来突破上述的控制器ID和类名的对应限制，通常情况下，当我们使用了第三方类库并且我们无法控制他们的类命名时，这种方式就很有用了。

你可以在应用程序配置文件中配置控制器Map：

<?php
[
    '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'，所以URLhttp://hostname/index.php将会交由site控制器来处理。

我们可以修改配置文件中的值来修改默认的控制器：

<?php
[
    'defaultRoute' => 'main',
]
?>

创建操作

创建操作可以像在控制器类中定义所谓的操作方法一样简单，一个操作方法必须是以action为开头而命名的公有方法。操作方法的返回值会作为响应数据发送给终端用户，如下代码定义了两个操作index和hello-world：

<?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';
    }
}
?>

操作ID

操作通常用来执行资源的特定操作，因此，操作ID通常是动词，如view、update等。

操作ID应该仅包含英文小写字母、数字、下划线和横杠，操作ID中的横杠用来分隔单词，例如view、update2、comment-post是合法的操作ID，而view?、Update则不是。

我们可以通过两种方式来创建操作：内联操作和独立操作，内联操作在控制器类中被定义为方法，而独立操作则是继承yii\base\Action或者其子类的类。内联操作容易创建，在无需重用的情况可以优先使用；独立操作相反，主要用于多个控制器重用，或者重构为扩展。

内联操作

内联操作方法的名字根据操作ID遵循如下规则衍生：

• 将每个单词的第一个字母转为大写；
• 去掉横杠；
• 增加action前缀

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

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

独立操作

要使用独立操作，需要通过控制器中覆盖yii\base\Controller::actions()方法在action map中声明，如下是示例代码：

<?php
public function actions()
{
    return [
        // 用类来声明“error”操作
        'error' => 'yii\web\ErrorAction',

        // 用配置数组声明“view”操作
        'view' => [
            'class' => 'yii\web\ViewAction',
            'viewPrefix' => '',
        ],
    ];
}
?>

actions()方法返回一个数组，其中key是操作的ID，对应的值是相应的操作类名，跟内联操作不同的是，独立操作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()方法的返回值非常重要，它表示对应操作的结果。返回值可以是响应对象，作为响应信息发送给终端用户。

• 对于yii\web\Application网页应用，返回值可以为任何数据，它赋值给yii\web\Response::data， 最终转换为字符串来展示响应内容
• 对于yii\console\Console控制台应用，返回值可以是整数，表示命令行下执行的yii\console\Response::exitStatus退出状态

在上面的例子中，操作结果都是字符串，作为响应数据发送给终端用户，下面的这个例子显示一个操作通过返回响应对象（yii\web\Controller::redirect()方法返回一个响应对象）可以将用户引导跳转至新的URL。

<?php
public function actionForward()
{
    // 用户浏览器重定向到 http://example.com
    return $this->redirect('http://example.com');
}

操作参数

内联操作和独立操作的run()方法都可以带参数，称为操作参数。参数值从请求中获取，对于yii\web\Application网页应用，每个操作参数的值从$_GET中获得，参数名作为键；对于yii\console\Application控制台应用，操作参数对应命令行参数。

如下例，操作view（内联操作）声明了两个参数$id和$version。

<?php
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参数收到的值不是字符串而是数组

如果想让操作参数接收数组，需要指定$id为array，如下所示：

<?php
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'会自动转成数组。

上述例子主要描述网页应用的操作参数，对于控制台应用，详情参考控制台命令。

默认操作

每个控制器都有一个由yii\base\Controller::defaultAction属性指定的默认操作，当路由只包含控制器ID，这表示请求了指定控制器的默认操作。

默认操作默认为index，如果想要修改默认操作，只需简单的在控制器类中覆盖这个属性即可，如下所示：

<?php
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或其他展示代码，这些代码最好在视图中处理。

Category: PHP Develop

Comments