Yii源码阅读笔记（十一）

controller类的render部分，用于渲染视图和布局文件：

 /**
      * 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()
     {
         $modules = [$this->module];
         $module = $this->module;
         while ($module->module !== null) {
             //由这里可知，返回的数组顺序为从父模块到子模块
             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:
      *
      * - 别名路径 (e.g. "@app/views/site/index");
      * - 应用内的视图：直接指定模板文件路径，以双斜线“//”开始的路径 (e.g. "//site/index"):
      *   The actual view file will be looked for under the [[Application::viewPath|view path]] of the application.
      * - 模块内的视图：直接指定模板文件路径，以单个斜线“/”开始的路径 (e.g. "/site/index"):
      *   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:
      *应用下的布局文件，以“/”开头，这个会从应用程序的布局文件目录下面查找布局文件
          * 3、其它情况，   这个会从当前模块的布局文件目录下查查找布局文件
      * - 别名路径(e.g. "@app/views/layouts/main");
      * - 绝对路径 (e.g. "/main"): 应用下的布局文件，以“/”开头，这个会从应用程序的布局文件目录下面查找布局文件
      * - 相对路径 (e.g. "main"): 这个会从当前模块的布局文件目录下查查找布局文件
      *   [[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);
         //调用renderContent方法渲染布局文件
         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.
      * @since 2.0.1
      */
     public function renderContent($content)
     {
         //查找布局文件
         $layoutFile = $this->findLayoutFile($this->getView());
         if ($layoutFile !== false) {
              //由view对象渲染布局文件，并把上面的视图结果作为content变量传递到布局中，所以布局中才会有$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.
      * @param string $view the view name. Please refer to [[render()]] on how to specify a view name.
      * @param array $params the parameters (name-value pairs) that should be made available in the view.
      * @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.
      * 这个就是用来渲染一个文件，$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.
      * @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组件 应该是getter方法
      * [[render()]], [[renderPartial()]] and [[renderFile()]] 方法调用这个对象实现视图的渲染
      * If not set, it will default to the "view" application component.
      * @return View|\yii\web\View the view object that can be used to render views or view files.
      */
     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.
      * 设置view对象，这个应该是setter方法
      * @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.
      * 获取这个控制器对应的view的文件路径
      * 默认返回的是模块下的视图路径
      * @return string the directory containing the view files for this controller.
      */
     public function getViewPath()
     {
         if ($this->_viewPath === null) {
             $this->_viewPath = $this->module->getViewPath() . DIRECTORY_SEPARATOR . $this->id;
         }
         return $this->_viewPath;
     }

     /**
      * Sets the directory that contains the view files.
      * 设置这个控制器对应的view文件的路径 setter方法
      * @param string $path the root directory of view files.
      * @throws InvalidParamException if the directory is invalid
      * @since 2.0.7
      */
     public function setViewPath($path)
     {
         $this->_viewPath = Yii::getAlias($path);
     }

     /**
      * 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.
      * @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;
             }
         }
         //如果没有设置布局文件，返回false
         if (!isset($layout)) {
             return false;
         }
         /*
          * 布局文件有三种路径写法
          * 1、别名，以“@”开头，这种会在别名路径中查找布局文件
          * 2、应用下的布局文件，以“/”开头，这个会从应用程序的布局文件目录下面查找布局文件
          * 3、其它情况，   这个会从当前模块的布局文件目录下查查找布局文件
          */
         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;
         //如果文件不存在，并且，默认的文件扩展名也不是php，则加上.php作为扩展名。
         if ($view->defaultExtension !== 'php' && !is_file($path)) {
             $path = $file . '.php';
         }

         return $path;
     }