Yii源码阅读笔记（十一）

  1 /**
  2      * Returns all ancestor modules of this controller.
  3      * 获取当前控制器所有的父模块
  4      * The first module in the array is the outermost one (i.e., the application instance),
  5      * while the last is the innermost one.
  6      * @return Module[] all ancestor modules that this controller is located within.
  7      */
  8     public function getModules()
  9     {
 10         $modules = [$this->module];
 11         $module = $this->module;
 12         while ($module->module !== null) {
 13             //由这里可知，返回的数组顺序为从父模块到子模块
 14             array_unshift($modules, $module->module);
 15             $module = $module->module;
 16         }
 17         return $modules;
 18     }
 19 
 20     /**
 21      * @return string the controller ID that is prefixed with the module ID (if any).
 22      *  返回控制器id
 23      */
 24     public function getUniqueId()
 25     {
 26        //如果当前所属模块为application，则就为该id,否则要前面要加上模块id
 27         return $this->module instanceof Application ? $this->id : $this->module->getUniqueId() . ‘/‘ . $this->id;
 28     }
 29 
 30     /**
 31      * Returns the route of the current request.
 32      * //获取默认请求的路由信息
 33      * @return string the route (module ID, controller ID and action ID) of the current request.
 34      */
 35     public function getRoute()
 36     {
 37         return $this->action !== null ? $this->action->getUniqueId() : $this->getUniqueId();
 38     }
 39 
 40     /**
 41      * Renders a view and applies layout if available.
 42      * 渲染视图文件和布局文件（如果有布局的话）
 43      * The view to be rendered can be specified in one of the following formats:
 44      *
 45      * - 别名路径 (e.g. "@app/views/site/index");
 46      * - 应用内的视图：直接指定模板文件路径，以双斜线“//”开始的路径 (e.g. "//site/index"):
 47      *   The actual view file will be looked for under the [[Application::viewPath|view path]] of the application.
 48      * - 模块内的视图：直接指定模板文件路径，以单个斜线“/”开始的路径 (e.g. "/site/index"): 
 49      *   The actual view file will be looked for under the [[Module::viewPath|view path]] of [[module]].
 50      * - relative path (e.g. "index"): the actual view file will be looked for under [[viewPath]].
 51      *
 52      * To determine which layout should be applied, the following two steps are conducted:
 53      * 确定应用布局文件类型的步骤：
 54      * 1. In the first step, it determines the layout name and the context module:
 55      * 首先确定布局文件名和背景模块
 56      * - If [[layout]] is specified as a string, use it as the layout name and [[module]] as the context module;
 57      * 如果布局文件是字符串，也就是设置布局文件，则直接调用
 58      * - If [[layout]] is null, search through all ancestor modules of this controller and find the first
 59      * 如果没有设置布局文件，则查找所有的父模块的布局文件。
 60      *   module whose [[Module::layout|layout]] is not null. The layout and the corresponding module
 61      *   are used as the layout name and the context module, respectively. If such a module is not found
 62      *   or the corresponding layout is not a string, it will return false, meaning no applicable layout.
 63      *
 64      * 2. In the second step, it determines the actual layout file according to the previously found layout name
 65      *    and context module. The layout name can be:
 66      *应用下的布局文件，以“/”开头，这个会从应用程序的布局文件目录下面查找布局文件
 67          * 3、其它情况，   这个会从当前模块的布局文件目录下查查找布局文件
 68      * - 别名路径(e.g. "@app/views/layouts/main");
 69      * - 绝对路径 (e.g. "/main"): 应用下的布局文件，以“/”开头，这个会从应用程序的布局文件目录下面查找布局文件
 70      * - 相对路径 (e.g. "main"): 这个会从当前模块的布局文件目录下查查找布局文件
 71      *   [[Module::layoutPath|layout path]] of the context module.
 72      *
 73      * If the layout name does not contain a file extension, it will use the default one `.php`.
 74      * 如果布局文件没有扩展名，则默认为.php
 75      * @param string $view the view name.
 76      * @param array $params the parameters (name-value pairs) that should be made available in the view.
 77      * These parameters will not be available in the layout.
 78      * @return string the rendering result.
 79      * @throws InvalidParamException if the view file or the layout file does not exist.
 80      */
 81     
 82     public function render($view, $params = [])
 83     {
 84         //由view对象渲染视图文件
 85         $content = $this->getView()->render($view, $params, $this);
 86         //调用renderContent方法渲染布局文件
 87         return $this->renderContent($content);
 88     }
 89 
 90     /**
 91      * Renders a static string by applying a layout.
 92      * 配合render方法渲染布局文件
 93      * @param string $content the static string being rendered
 94      * @return string the rendering result of the layout with the given static string as the `$content` variable.
 95      * If the layout is disabled, the string will be returned back.
 96      * @since 2.0.1
 97      */
 98     public function renderContent($content)
 99     {
100         //查找布局文件
101         $layoutFile = $this->findLayoutFile($this->getView());
102         if ($layoutFile !== false) {
103              //由view对象渲染布局文件，并把上面的视图结果作为content变量传递到布局中，所以布局中才会有$content变量来表示
104             return $this->getView()->renderFile($layoutFile, [‘content‘ => $content], $this);
105         } else {
106             return $content;
107         }
108     }
109 
110     /**
111      * Renders a view without applying layout.
112      * 这个只渲染视图文件，不会应用布局
113      * This method differs from [[render()]] in that it does not apply any layout.
114      * @param string $view the view name. Please refer to [[render()]] on how to specify a view name.
115      * @param array $params the parameters (name-value pairs) that should be made available in the view.
116      * @return string the rendering result.
117      * @throws InvalidParamException if the view file does not exist.
118      */
119     
120     public function renderPartial($view, $params = [])
121     {
122         return $this->getView()->render($view, $params, $this);
123     }
124 
125     /**
126      * Renders a view file.
127      * 这个就是用来渲染一个文件，$file为文件实路径或别名路径
128      * @param string $file the view file to be rendered. This can be either a file path or a path alias.
129      * @param array $params the parameters (name-value pairs) that should be made available in the view.
130      * @return string the rendering result.
131      * @throws InvalidParamException if the view file does not exist.
132      */
133     
134     public function renderFile($file, $params = [])
135     {
136         return $this->getView()->renderFile($file, $params, $this);
137     }
138 
139     /**
140      * Returns the view object that can be used to render views or view files.
141      * 获取view组件 应该是getter方法
142      * [[render()]], [[renderPartial()]] and [[renderFile()]] 方法调用这个对象实现视图的渲染
143      * If not set, it will default to the "view" application component.
144      * @return View|\yii\web\View the view object that can be used to render views or view files.
145      */
146     public function getView()
147     {
148         if ($this->_view === null) {
149             $this->_view = Yii::$app->getView();
150         }
151         return $this->_view;
152     }
153 
154     /**
155      * Sets the view object to be used by this controller.
156      * 设置view对象，这个应该是setter方法
157      * @param View|\yii\web\View $view the view object that can be used to render views or view files.
158      */
159     public function setView($view)
160     {
161         $this->_view = $view;
162     }
163 
164     /**
165      * Returns the directory containing view files for this controller.
166      * 获取这个控制器对应的view的文件路径
167      * 默认返回的是模块下的视图路径
168      * @return string the directory containing the view files for this controller.
169      */
170     public function getViewPath()
171     {
172         if ($this->_viewPath === null) {
173             $this->_viewPath = $this->module->getViewPath() . DIRECTORY_SEPARATOR . $this->id;
174         }
175         return $this->_viewPath;
176     }
177 
178     /**
179      * Sets the directory that contains the view files.
180      * 设置这个控制器对应的view文件的路径 setter方法
181      * @param string $path the root directory of view files.
182      * @throws InvalidParamException if the directory is invalid
183      * @since 2.0.7
184      */
185     public function setViewPath($path)
186     {
187         $this->_viewPath = Yii::getAlias($path);
188     }
189 
190     /**
191      * Finds the applicable layout file.
192      * 查找布局文件
193      * @param View $view the view object to render the layout file.
194      * @return string|boolean the layout file path, or false if layout is not needed.
195      * Please refer to [[render()]] on how to specify this parameter.
196      * @throws InvalidParamException if an invalid path alias is used to specify the layout.
197      */
198     public function findLayoutFile($view)
199     {
200         $module = $this->module;
201         if (is_string($this->layout)) {
202             //如果当前控制器设置了布局文件，则直接使用所设置的布局文件
203             $layout = $this->layout;
204         } elseif ($this->layout === null) {
205             //如果没有设置布局文件，则查找所有的父模块的布局文件。
206             while ($module !== null && $module->layout === null) {
207                 $module = $module->module;
208             }
209             if ($module !== null && is_string($module->layout)) {
210                 $layout = $module->layout;
211             }
212         }
213         //如果没有设置布局文件，返回false
214         if (!isset($layout)) {
215             return false;
216         }
217         /*
218          * 布局文件有三种路径写法
219          * 1、别名，以“@”开头，这种会在别名路径中查找布局文件
220          * 2、应用下的布局文件，以“/”开头，这个会从应用程序的布局文件目录下面查找布局文件
221          * 3、其它情况，   这个会从当前模块的布局文件目录下查查找布局文件
222          */
223         if (strncmp($layout, ‘@‘, 1) === 0) {
224             $file = Yii::getAlias($layout);
225         } elseif (strncmp($layout, ‘/‘, 1) === 0) {
226             $file = Yii::$app->getLayoutPath() . DIRECTORY_SEPARATOR . substr($layout, 1);
227         } else {
228             $file = $module->getLayoutPath() . DIRECTORY_SEPARATOR . $layout;
229         }
230         //如果布局文件有文件扩展名，返回
231         if (pathinfo($file, PATHINFO_EXTENSION) !== ‘‘) {
232             return $file;
233         }
234         //加上默认的文件扩展名。
235         $path = $file . ‘.‘ . $view->defaultExtension;
236         //如果文件不存在，并且，默认的文件扩展名也不是php，则加上.php作为扩展名。
237         if ($view->defaultExtension !== ‘php‘ && !is_file($path)) {
238             $path = $file . ‘.php‘;
239         }
240 
241         return $path;
242     }