Controller控制器类

原文地址: http://www.cnblogs.com/dragon16/p/5557644.html

Controller控制器类，是所有控制器的基类，用于调用模型和布局。

<?php/** * @link http://www.yiiframework.com/ * @copyright Copyright (c) 2008 Yii Software LLC * @license http://www.yiiframework.com/license/ */namespace yii\base;use Yii;/** * Controller is the base class for classes containing controller logic. *  控制器，是所用控制器类的基类 * @property Module[] $modules All ancestor modules that this controller is located within. This property is * read-only.只读属性  当前控制器的所有模块 * @property string $route The route (module ID, controller ID and action ID) of the current request. This * property is read-only.当前请求的路径  只读属性 可以获取到请求的路径 * @property string $uniqueId The controller ID that is prefixed with the module ID (if any). This property is * read-only.为前缀的controller ID  唯一标识 * @property View|\yii\web\View $view The view object that can be used to render views or view files. * 视图用来传递视图或视图文件. * @property string $viewPath The directory containing the view files for this controller. This property is * read-only. 包含当前控制器的视图目录 * * @author Qiang Xue <[e-mail]> * @since 2.0 */class Controller extends Component implements ViewContextInterface{    /**     * @event ActionEvent an event raised right before executing a controller action.     * ActionEvent事件提出正确的执行器动作之前执行。     * You may set [[ActionEvent::isValid]] to be false to cancel the action execution.     * 如果对事件的isValid属性设置为false，将取消action的执行     */    const EVENT_BEFORE_ACTION = 'beforeAction';    /**     * @event ActionEvent an event raised right after executing a controller action.     * 在执行controller操作后触发的事件     */    const EVENT_AFTER_ACTION = 'afterAction';    /**     * @var string the ID of this controller.     * 控制器id     */    public $id;    /**     * @var Module $module the module that this controller belongs to.     * 所属模块     */    public $module;    /**     * @var string the ID of the action that is used when the action ID is not specified     * in the request. Defaults to 'index'.控制器中默认动作，默认为index     */    public $defaultAction = 'index';    /**     * @var string|boolean the name of the layout to be applied to this controller's views.     * 布局的名称 应用到该控制器的视图。     * This property mainly affects the behavior of [[render()]].此属性主要影响[[render()]]行为     * Defaults to null, meaning the actual layout value should inherit that from [[module]]'s layout value.     * If false, no layout will be applied.      * 如果设置为false，则不使用布局文件     */    public $layout;    /**     * @var Action the action that is currently being executed. This property will be set     * by [[run()]] when it is called by [[Application]] to run an action.     * 当前执行的操作，可在事件中根据这个action来执行不同的操作     */    public $action;    /**     * @var View the view object that can be used to render views or view files.     * 视图对象，用来定义输出的视图文件     */    private $_view;    /**     * @param string $id the ID of this controller.控制器的ID     * @param Module $module the module that this controller belongs to.控制器的模块     * @param array $config name-value pairs that will be used to initialize the object properties.     * 初始化对像时的配置文件     */    public function __construct($id, $module, $config = [])    {        //初始化控制器id，模块，根据配置文件初始化控制器对象        $this->id = $id;        $this->module = $module;        parent::__construct($config);    }    /**     * Declares external actions for the controller.定义action声明控制器的外部操作     * This method is meant to be overwritten to declare external actions for the controller.     * It should return an array, with array keys being action IDs, and array values the corresponding     * action class names or action configuration arrays. For example,     * 这个方法指定独立的action，返回格式为数组，name为action的id,value为action类的实现，     * ~~~     * return [     *     'action1' => 'app\components\Action1',     *     'action2' => [     *         'class' => 'app\components\Action2',     *         'property1' => 'value1',     *         'property2' => 'value2',     *     ],     * ];     * ~~~     *     * [[\Yii::createObject()]] will be used later to create the requested action     * using the configuration provided here.     * 使用此处提供的配置来创建请求的操作。     */    public function actions()    {        return [];    }    /**     * Runs an action within this controller with the specified action ID and parameters.     * 控制器中运行指定的操作标识和参数。     * If the action ID is empty, the method will use [[defaultAction]].     * 如果没有定义ID，会调用默认操作     * @param string $id the ID of the action to be executed. 要执行的动作标识。     * @param array $params the parameters (name-value pairs) to be passed to the action.     * 传递给操作的参数。     * @return mixed the result of the action.  操作结果     * @throws InvalidRouteException if the requested action ID cannot be resolved into an action successfully.     * @see createAction()     */    public function runAction($id, $params = [])    {        $action = $this->createAction($id);//创建操作        if ($action === null) {//创建失败，抛出异常            throw new InvalidRouteException('Unable to resolve the request: ' . $this->getUniqueId() . '/' . $id);        }        Yii::trace("Route to run: " . $action->getUniqueId(), __METHOD__);        if (Yii::$app->requestedAction === null) {            // 记录当前的操作为requestedAction            Yii::$app->requestedAction = $action;        }        $oldAction = $this->action;//将操作中的信息保存        $this->action = $action;//写入属性        //保存当前控制器的所有父模块        $modules = [];        $runAction = true;        // call beforeAction on modules 从外到里一层层执行module的beforeAction        foreach ($this->getModules() as $module) {            if ($module->beforeAction($action)) {                 // 将执行成功的module放入到$modules中，顺序会颠倒                array_unshift($modules, $module);            } else {                 // 执行失败，就标记一下                $runAction = false;                break;            }        }        $result = null;        if ($runAction && $this->beforeAction($action)) {            // run the action 执行成功就执行action            $result = $action->runWithParams($params);            // 执行controller本身的afterAction            $result = $this->afterAction($action, $result);            // call afterAction on modules 从里到外一层层执行所有            foreach ($modules as $module) {                /* @var $module Module */                $result = $module->afterAction($action, $result);            }        }        $this->action = $oldAction;        return $result;    }

/**     * Runs a request specified in terms of a route.在路径中指定的请求。     * The route can be either an ID of an action within this controller or a complete route consisting     * of module IDs, controller ID and action ID. If the route starts with a slash '/', the parsing of     * the route will start from the application; otherwise, it will start from the parent module of this controller.     * 该路径可以是控制器内的一个动作的标识，或由模块标识、控制器标识和动作标识组成的一个完整路径。     * 如果该路径从一个“/”开始，该路径的解析将从应用程序开始；否则，它将从该控制器的父模块开始。     * @param string $route the route to be handled, e.g., 'view', 'comment/view', '/admin/comment/view'.     * @param array $params the parameters to be passed to the action.     * @return mixed the result of the action.     * @see runAction()     */    public function run($route, $params = [])    {        $pos = strpos($route, '/');        if ($pos === false) {//判断是否以“/”开始 是则解析从应用程序开始；否则，它将从该控制器的父模块开始。            return $this->runAction($route, $params);        } elseif ($pos > 0) {            return $this->module->runAction($route, $params);        } else {            return Yii::$app->runAction(ltrim($route, '/'), $params);        }    }    /**     * Binds the parameters to the action.将参数绑定到动作标识。     * This method is invoked by [[Action]] when it begins to run with the given parameters.     * 运行给定的参数时，该方法被调用。     * @param Action $action the action to be bound with parameters.参数约束的操作。     * @param array $params the parameters to be bound to the action.要约束的参数。     * @return array the valid parameters that the action can run with.可以运行的有效参数。     */    public function bindActionParams($action, $params)    {        return [];    }    /**     * Creates an action based on the given action ID. 根据给定的操作标识创建一个action。     * The method first checks if the action ID has been declared in [[actions()]]. If so,     * it will use the configuration declared there to create the action object.     * If not, it will look for a controller method whose name is in the format of `actionXyz`     * where `Xyz` stands for the action ID. If found, an [[InlineAction]] representing that     * method will be created and returned.     * 该方法首先检查动作标识是否在 [[actions()]]设置，如果是将使用配置声明来创建操作对象。     * 如果不是，它会寻找控制器方法`Xyz` 的 `actionXyz`作为动作标识，调用[[InlineAction]]方法创建对象     * @param string $id the action ID.      * @return Action the newly created action instance. Null if the ID doesn't resolve into any action.     */    public function createAction($id)    {        if ($id === '') {             // 如果action的id为空，就是用默认的action            $id = $this->defaultAction;        }        $actionMap = $this->actions();// 获取actions方法中的定义的actionMap        if (isset($actionMap[$id])) {             // 如果操作标识在actionMap中，就去创建这个action            return Yii::createObject($actionMap[$id], [$id, $this]);        } elseif (preg_match('/^[a-z0-9\\-_]+$/', $id) && strpos($id, '--') === false && trim($id, '-') === $id) {             // 如果id符合命名规范，而且两边不存在-            // 用于拼接controller类名类似的方法拼接action方法的名称            $methodName = 'action' . str_replace(' ', '', ucwords(implode(' ', explode('-', $id))));            if (method_exists($this, $methodName)) {                // 如果方法存在，就实例化                $method = new \ReflectionMethod($this, $methodName);                if ($method->isPublic() && $method->getName() === $methodName) {                    // 如果方法是public的，就new一个InlineAction返回                    return new InlineAction($id, $this, $methodName);                }            }        }        return null;    }    /**     * This method is invoked right before an action is executed.     * 在执行操作之前调用此方法。     * The method will trigger the [[EVENT_BEFORE_ACTION]] event. The return value of the method     * will determine whether the action should continue to run.     * 方法将触发 [[EVENT_BEFORE_ACTION]] 事件，返回值确定该操作是否执行     * If you override this method, your code should look like the following:     *     * ```php     * public function beforeAction($action)     * {     *     if (parent::beforeAction($action)) {     *         // your custom code here     *         return true;  // or false if needed     *     } else {     *         return false;     *     }     * }     * ```     *     * @param Action $action the action to be executed. 执行的操作     * @return boolean whether the action should continue to run.确定操作是否应该继续运行。     */    public function beforeAction($action)    {        $event = new ActionEvent($action);        $this->trigger(self::EVENT_BEFORE_ACTION, $event);        return $event->isValid;    }    /**     * This method is invoked right after an action is executed.     * 在执行操作之后调用此方法。     * The method will trigger the [[EVENT_AFTER_ACTION]] event. The return value of the method     * will be used as the action return value.     *     * If you override this method, your code should look like the following:     *     * ```php     * public function afterAction($action, $result)     * {     *     $result = parent::afterAction($action, $result);     *     // your custom code here     *     return $result;     * }     * ```     *     * @param Action $action the action just executed. 刚刚执行的操作。     * @param mixed $result the action return result. 操作返回值     * @return mixed the processed action result. 处理结果。     */    public function afterAction($action, $result)    {        $event = new ActionEvent($action);        $event->result = $result;        $this->trigger(self::EVENT_AFTER_ACTION, $event);        return $event->result;    }    /**     * Returns all ancestor modules of this controller. 获取当前控制器所有的父模块     * The first module in the array is the outermost one (i.e., the application instance),     * while the last is the innermost one.     * 数组中的第一个模块是最外层的一个，最后一个模块是最内层的。     * @return Module[] all ancestor modules that this controller is located within.当前控制器所有的父模块     */    public function getModules()    {        // 当前controller的module组成的数组        $modules = [$this->module];        $module = $this->module;        while ($module->module !== null) {             // 将外面的module插入到modules数组的开头            array_unshift($modules, $module->module);            $module = $module->module;        }        return $modules;    }    /**     * @return string the controller ID that is prefixed with the module ID (if any).     * 返回控制器id     */    public function getUniqueId()    {        //如果当前所属模块为application，则就为当前id,否则要面要加上模块id        return $this->module instanceof Application ? $this->id : $this->module->getUniqueId() . '/' . $this->id;    }    /**     * Returns the route of the current request.    获取默认请求的路由信息     * @return string the route (module ID, controller ID and action ID) of the current request.      * 当前请求的路由（模块标识、控制器标识和操作标识）     */    public function getRoute()    {        return $this->action !== null ? $this->action->getUniqueId() : $this->getUniqueId();    }    /**     * Renders a view and applies layout if available.     * 如果有布局渲染视图文件和布局文件     * The view to be rendered can be specified in one of the following formats:     *     * - path alias (e.g. "@app/views/site/index");     * - absolute path within application (e.g. "//site/index"): the view name starts with double slashes.     *   The actual view file will be looked for under the [[Application::viewPath|view path]] of the application.     * - absolute path within module (e.g. "/site/index"): the view name starts with a single slash.     *   The actual view file will be looked for under the [[Module::viewPath|view path]] of [[module]].     * - relative path (e.g. "index"): the actual view file will be looked for under [[viewPath]].     *     * To determine which layout should be applied, the following two steps are conducted:     * 确定应用布局文件类型的步骤：     * 1. In the first step, it determines the layout name and the context module:     * 首先确定布局文件名和背景模块     * - If [[layout]] is specified as a string, use it as the layout name and [[module]] as the context module;     * - If [[layout]] is null, search through all ancestor modules of this controller and find the first     *   module whose [[Module::layout|layout]] is not null. The layout and the corresponding module     *   are used as the layout name and the context module, respectively. If such a module is not found     *   or the corresponding layout is not a string, it will return false, meaning no applicable layout.     *   如果布局文件是字符串，也就是设置布局文件，则直接调用。 如果没有设置布局文件，则查找所有的父模块的布局文件。     * 2. In the second step, it determines the actual layout file according to the previously found layout name     *    and context module. The layout name can be:     *    应用下的布局文件，以“/”开头，这个会从应用程序的布局文件目录下面查找布局文件     * - a path alias (e.g. "@app/views/layouts/main");     * - an absolute path (e.g. "/main"): the layout name starts with a slash. The actual layout file will be     *   looked for under the [[Application::layoutPath|layout path]] of the application;     * - a relative path (e.g. "main"): the actual layout file will be looked for under the     *   [[Module::layoutPath|layout path]] of the context module.     *     * If the layout name does not contain a file extension, it will use the default one `.php`.     * 如果布局文件没有扩展名，则默认为.php     * @param string $view the view name.     * @param array $params the parameters (name-value pairs) that should be made available in the view.     * These parameters will not be available in the layout.     * @return string the rendering result.     * @throws InvalidParamException if the view file or the layout file does not exist.     */    public function render($view, $params = [])    {        //由view对象渲染视图文件        $content = $this->getView()->render($view, $params, $this);        return $this->renderContent($content);//渲染布局文件    }    /**     * Renders a static string by applying a layout.    配合render方法渲染布局文件     * @param string $content the static string being rendered  被渲染的静态字符串     * @return string the rendering result of the layout with the given static string as the `$content` variable.     * If the layout is disabled, the string will be returned back.     * 以给定的静态字符串作为“$content”变量布局的渲染结果。如果布局被禁用，将返回该字符串。     * @since 2.0.1     */    public function renderContent($content)    {        $layoutFile = $this->findLayoutFile($this->getView()); //查找布局文件        if ($layoutFile !== false) {//由view对象渲染布局文件，并把上视图结果作为content变量传递到布局中，            return $this->getView()->renderFile($layoutFile, ['content' => $content], $this);        } else {            return $content;        }    }    /**     * Renders a view without applying layout.渲染视图文件不应用布局     * This method differs from [[render()]] in that it does not apply any layout.     * 这种方法不同于[[render()]]，它不使用任何布局。     * @param string $view the view name. Please refer to [[render()]] on how to specify a view name.     * 视图名称。根据[[render()]]指定一个视图名称。     * @param array $params the parameters (name-value pairs) that should be made available in the view.     * 在视图中提供的参数(name-value pairs)     * @return string the rendering result.渲染结果。     * @throws InvalidParamException if the view file does not exist.如果视图文件不存在，抛出异常     */    public function renderPartial($view, $params = [])    {        return $this->getView()->render($view, $params, $this);    }    /**     * Renders a view file. 渲染一个文件     * @param string $file the view file to be rendered. This can be either a file path or a path alias.     * 要呈现的视图文件。可以是一个文件路径或路径别名。     * @param array $params the parameters (name-value pairs) that should be made available in the view.     * 在视图中提供的参数(name-value pairs)     * @return string the rendering result.渲染结果     * @throws InvalidParamException if the view file does not exist.如果视图文件不存在，抛出异常     */    public function renderFile($file, $params = [])    {        return $this->getView()->renderFile($file, $params, $this);    }    /**     * Returns the view object that can be used to render views or view files.     * 返回渲染视图或视图文件的view对象。     * The [[render()]], [[renderPartial()]] and [[renderFile()]] methods will use     * this view object to implement the actual view rendering.     * [[render()]], [[renderPartial()]] and [[renderFile()]] 方法将使用视图对象实现视图显示。     * If not set, it will default to the "view" application component.如果未设置，则默认为“view”应用程序组件。     * @return View|\yii\web\View the view object that can be used to render views or view files.     * 渲染视图或视图文件的view对象。     */    public function getView()    {        if ($this->_view === null) {            $this->_view = Yii::$app->getView();        }        return $this->_view;    }    /**     * Sets the view object to be used by this controller.     * @param View|\yii\web\View $view the view object that can be used to render views or view files.     */    public function setView($view)    {        $this->_view = $view;    }    /**     * Returns the directory containing view files for this controller.返回该控制器包含视图文件的目录。     * The default implementation returns the directory named as controller [[id]] under the [[module]]'s     * [[viewPath]] directory.默认返回目录命名为控制器[[id]] 下的 [[module]]的[[viewPath]]目录。     * @return string the directory containing the view files for this controller.     * 包含此控制器的视图文件的目录。     */    public function getViewPath()    {        return $this->module->getViewPath() . DIRECTORY_SEPARATOR . $this->id;    }    /**     * Finds the applicable layout file.查找适用的布局文件。     * @param View $view the view object to render the layout file.呈现布局文件视图对象。     * @return string|boolean the layout file path, or false if layout is not needed.     * Please refer to [[render()]] on how to specify this parameter.     * 布局文件路径，或者不需要布局。参阅[[render()]]如何指定此参数。     * @throws InvalidParamException if an invalid path alias is used to specify the layout.     * 如果使用了无效的路径别名指定布局。抛出异常     */    public function findLayoutFile($view)    {        $module = $this->module;        if (is_string($this->layout)) {             //如果当前控制器设置了布局文件，则直接使用所设置的布局文件            $layout = $this->layout;        } elseif ($this->layout === null) {             //如果没有设置布局文件，查找所有的父模块的布局文件。            while ($module !== null && $module->layout === null) {                $module = $module->module;            }            if ($module !== null && is_string($module->layout)) {                $layout = $module->layout;            }        }        if (!isset($layout)) {            return false;//如果没有设置布局文件，返回false        }        if (strncmp($layout, '@', 1) === 0) {            $file = Yii::getAlias($layout);//以“@”开头，会在别名路径中查找布局文件        } elseif (strncmp($layout, '/', 1) === 0) {//以“/”开头，会从应用程序的布局文件目录下面查找布局文件            $file = Yii::$app->getLayoutPath() . DIRECTORY_SEPARATOR . substr($layout, 1);        } else {//从当前模块的布局文件目录下查找布局文件            $file = $module->getLayoutPath() . DIRECTORY_SEPARATOR . $layout;        }        if (pathinfo($file, PATHINFO_EXTENSION) !== '') {            return $file;//如果布局文件有文件扩展名，返回文件        }        $path = $file . '.' . $view->defaultExtension;//拼接默认的文件扩展名。        if ($view->defaultExtension !== 'php' && !is_file($path)) {            $path = $file . '.php';//如果文件不存在，并且，默认的文件扩展名也不是php，则加上.php作为扩展名。        }        return $path;    }