yii2源码学习笔记（十八）

  1 <?php
  2 /**
  3  * @link http://www.yiiframework.com/
  4  * @copyright Copyright (c) 2008 Yii Software LLC
  5  * @license http://www.yiiframework.com/license/
  6  */
  7 
  8 namespace yii\base;
  9 
 10 use Yii;
 11 use yii\helpers\FileHelper;
 12 use yii\widgets\Block;
 13 use yii\widgets\ContentDecorator;
 14 use yii\widgets\FragmentCache;
 15 
 16 /**
 17  * View represents a view object in the MVC pattern.
 18  * MVC中的视图
 19  * View provides a set of methods (e.g. [[render()]]) for rendering purpose.
 20  * 视图提供了一套渲染页面的方法
 21  * @property string|boolean $viewFile The view file currently being rendered. False if no view file is being
 22  * rendered. This property is read-only.
 23  *
 24  * @author Qiang Xue <qiang.xue@gmail.com>
 25  * @since 2.0
 26  */
 27 class View extends Component
 28 {
 29     /**
 30      * @event Event an event that is triggered by [[beginPage()]].
 31      * 事件被[beginPage()]触发
 32      */
 33     const EVENT_BEGIN_PAGE = 'beginPage';
 34     /**
 35      * @event Event an event that is triggered by [[endPage()]].
 36      * 事件被[endPage()]触发
 37      */
 38     const EVENT_END_PAGE = 'endPage';
 39     /**
 40      * @event ViewEvent an event that is triggered by [[renderFile()]] right before it renders a view file.
 41      * 事件被[renderFile()]触发前呈现一个视图文件
 42      */
 43     const EVENT_BEFORE_RENDER = 'beforeRender';
 44     /**
 45      * @event ViewEvent an event that is triggered by [[renderFile()]] right after it renders a view file.
 46      * 事件被[renderFile()]触发后呈现一个视图文件
 47      */
 48     const EVENT_AFTER_RENDER = 'afterRender';
 49 
 50     /**
 51      * @var ViewContextInterface the context under which the [[renderFile()]] method is being invoked.
 52      * ViewContextInterface背景下 [renderFile()]方法被调用
 53      */
 54     public $context;
 55     /**
 56      * @var mixed custom parameters that are shared among view templates.
 57      * 视图模板中共享的自定义参数
 58      */
 59     public $params = [];
 60     /**
 61      * @var array a list of available renderers indexed by their corresponding supported file extensions.
 62      * Each renderer may be a view renderer object or the configuration for creating the renderer object.
 63      *  一个可用的渲染索引列表。每个渲染器是一个渲染器对象或创建渲染对象配置数组
 64      * For example, the following configuration enables both Smarty and Twig view renderers:
 65      *
 66      * ~~~
 67      * [
 68      *     'tpl' => ['class' => 'yii\smarty\ViewRenderer'],
 69      *     'twig' => ['class' => 'yii\twig\ViewRenderer'],
 70      * ]
 71      * ~~~
 72      *
 73      * If no renderer is available for the given view file, the view file will be treated as a normal PHP
 74      * and rendered via [[renderPhpFile()]].
 75      */
 76     public $renderers;
 77     /**
 78      * @var string the default view file extension. This will be appended to view file names if they don't have file extensions.
 79      * 默认视图文件扩展名，文件没有扩展名的情况下自动加载
 80      */
 81     public $defaultExtension = 'php';
 82     /**
 83      * @var Theme|array|string the theme object or the configuration for creating the theme object.
 84      * If not set, it means theming is not enabled.主题对象或创建主题对象的配置 未设置则不启用
 85      */
 86     public $theme;
 87     /**
 88      * @var array a list of named output blocks. The keys are the block names and the values
 89      * are the corresponding block content. You can call [[beginBlock()]] and [[endBlock()]]
 90      * to capture small fragments of a view. They can be later accessed somewhere else
 91      * through this property.
 92      * 一个输出块列表。键是块名称值为内容。可以调用 [beginblock()]和[endblock()]捕获视图的小片段
 93      * 可以在其他地方通过这个属性访问。
 94      */
 95     public $blocks;
 96     /**
 97      * @var array a list of currently active fragment cache widgets. This property
 98      * is used internally to implement the content caching feature. Do not modify it directly.
 99      * 当前操作片段的缓存部件列表。用于内部实现内容缓存功能。不要直接修改
100      * @internal
101      */
102     public $cacheStack = [];
103     /**
104      * @var array a list of placeholders for embedding dynamic contents. This property
105      * is used internally to implement the content caching feature. Do not modify it directly.
106      * 嵌入动态内容占位符列表。 用于内部实现内容缓存功能。不要直接修改
107      * @internal
108      */
109     public $dynamicPlaceholders = [];
110 
111     /**
112      * @var array the view files currently being rendered. There may be multiple view files being
113      * rendered at a moment because one view may be rendered within another.
114      * 正在渲染的视图文件。可能有多个视图文件被渲染，因为一个视图可以在另一个视图中呈现
115      */
116     private $_viewFiles = [];
117 
118 
119     /**
120      * Initializes the view component.初始化视图组件
121      */
122     public function init()
123     {
124         parent::init(); //调用父类的方法
125         if (is_array($this->theme)) {
126             if (!isset($this->theme['class'])) {
127                 $this->theme['class'] = 'yii\base\Theme';//是数组，没有设置类名，则类名'yii\base\Theme'
128             }
129             $this->theme = Yii::createObject($this->theme);//设置了类名，调用配置创建对象
130         } elseif (is_string($this->theme)) {//以字符串参数的形式创建对象
131             $this->theme = Yii::createObject($this->theme);
132         }
133     }
134 
135     /**
136      * Renders a view.
137      * 渲染一个视图
138      * The view to be rendered can be specified in one of the following formats:
139      *
140      * - path alias (e.g. "@app/views/site/index");
141      * 路径别名
142      * - absolute path within application (e.g. "//site/index"): the view name starts with double slashes.
143      *   The actual view file will be looked for under the [[Application::viewPath|view path]] of the application.
144      *  绝对路径，会在[Application::viewPath|view path]下查找文件
145      * - absolute path within current module (e.g. "/site/index"): the view name starts with a single slash.
146      *   The actual view file will be looked for under the [[Module::viewPath|view path]] of the [[Controller::module|current module]].
147      * 模块下的绝对路径，会在[Module::viewPath|view path]下查找文件
148      * - relative view (e.g. "index"): the view name does not start with `@` or `/`. The corresponding view file will be
149      *   looked for under the [[ViewContextInterface::getViewPath()|view path]] of the view `$context`.
150      * 相对路径，会在[ViewContextInterface::getViewPath()|view path]下查找文件  
151      * If `$context` is not given, it will be looked for under the directory containing the view currently
152      *   being rendered (i.e., this happens when rendering a view within another view).
153      *
154      * @param string $view the view name.   视图名称
155      * @param array $params the parameters (name-value pairs) that will be extracted and made available in the view file.
156      * 视图中应用参数
157      * @param object $context the context to be assigned to the view and can later be accessed via [[context]]
158      * in the view. If the context implements [[ViewContextInterface]], it may also be used to locate
159      * the view file corresponding to a relative view name. 对应情景
160      * @return string the rendering result
161      * @throws InvalidParamException if the view cannot be resolved or the view file does not exist.
162      * @see renderFile()
163      */
164     public function render($view, $params = [], $context = null)
165     {
166         $viewFile = $this->findViewFile($view, $context);//查找视图文件路径
167         return $this->renderFile($viewFile, $params, $context);//渲染视图文件
168     }
169 
170     /**
171      * Finds the view file based on the given view name.通过视图文件名查找视图文件
172      * @param string $view the view name or the path alias of the view file. Please refer to [[render()]]
173      * on how to specify this parameter. 视图名称或路径视图文件的别名
174      * @param object $context the context to be assigned to the view and can later be accessed via [[context]]
175      * in the view. If the context implements [[ViewContextInterface]], it may also be used to locate
176      * the view file corresponding to a relative view name. 对应情景
177      * @return string the view file path. Note that the file may not exist. 文件路径
178      * @throws InvalidCallException if a relative view name is given while there is no active context to
179      * determine the corresponding view file.
180      */
181     protected function findViewFile($view, $context = null)
182     {
183         if (strncmp($view, '@', 1) === 0) {
184             // e.g. "@app/views/main"  判断是否是别名路径，是则获取真实路径
185             $file = Yii::getAlias($view);
186         } elseif (strncmp($view, '//', 2) === 0) {
187             // e.g. "//layouts/main" 以//开始，查找文件路径，拼接视图文件路径
188             $file = Yii::$app->getViewPath() . DIRECTORY_SEPARATOR . ltrim($view, '/');
189         } elseif (strncmp($view, '/', 1) === 0) {
190             // e.g. "/site/index"
191             if (Yii::$app->controller !== null) { 
192                 //以/开始，且控制器存在，查找控制器对应的文件目录，拼接路径
193                 $file = Yii::$app->controller->module->getViewPath() . DIRECTORY_SEPARATOR . ltrim($view, '/');
194             } else {
195                 throw new InvalidCallException("Unable to locate view file for view '$view': no active controller.");
196             }
197         } elseif ($context instanceof ViewContextInterface) {
198             //对应情景存在 查找文件路径，拼接视图文件路径
199             $file = $context->getViewPath() . DIRECTORY_SEPARATOR . $view;
200         } elseif (($currentViewFile = $this->getViewFile()) !== false) {
201             //当前渲染文件存在，拼接路径
202             $file = dirname($currentViewFile) . DIRECTORY_SEPARATOR . $view;
203         } else {
204             throw new InvalidCallException("Unable to resolve view file for view '$view': no active view context.");
205         }
206 
207         if (pathinfo($file, PATHINFO_EXTENSION) !== '') {
208             return $file;//视图文件的扩展名不为空，返回扩展名
209         }
210         $path = $file . '.' . $this->defaultExtension; //给视图文件添加扩展名
211         if ($this->defaultExtension !== 'php' && !is_file($path)) {
212             $path = $file . '.php';
213         }
214 
215         return $path;//返回路径
216     }
217 
218     /**
219      * Renders a view file.
220      * 渲染一个视图文件。
221      * If [[theme]] is enabled (not null), it will try to render the themed version of the view file as long
222      * as it is available.
223      * 如果[theme]可用，将渲染视图文件的主题版本直到[theme]不可用
224      * The method will call [[FileHelper::localize()]] to localize the view file.
225      * 调用[FileHelper::localize()]方法本地化视图文件
226      * If [[renderers|renderer]] is enabled (not null), the method will use it to render the view file.
227      * Otherwise, it will simply include the view file as a normal PHP file, capture its output and
228      * return it as a string.
229      * 如果[[renderers|renderer]]启用，该方法将用它来渲染视图文件。否则，将视图文件作为一个正常的PHP文件包含进来，获取其输出并返回一个字符串。
230      * @param string $viewFile the view file. This can be either an absolute file path or an alias of it.
231      * 视图文件。可以是绝对路径或它的别名。
232      * @param array $params the parameters (name-value pairs) that will be extracted and made available in the view file.
233      * 视图文件执行的参数
234      * @param object $context the context that the view should use for rendering the view. If null,
235      * existing [[context]] will be used.
236      * 用于渲染视图的上下文
237      * @return string the rendering result 
238      * @throws InvalidParamException if the view file does not exist
239      */
240     public function renderFile($viewFile, $params = [], $context = null)
241     {
242         $viewFile = Yii::getAlias($viewFile);//处理输入的视图文件名
243 
244         if ($this->theme !== null) {
245             $viewFile = $this->theme->applyTo($viewFile);//如果theme非空，应用到视图文件
246         }
247         if (is_file($viewFile)) {
248             $viewFile = FileHelper::localize($viewFile);//本地化视图文件
249         } else {
250             throw new InvalidParamException("The view file does not exist: $viewFile");
251         }
252 
253         $oldContext = $this->context;
254         if ($context !== null) {
255             $this->context = $context;
256         }
257         $output = '';
258         $this->_viewFiles[] = $viewFile;//记录当前渲染文件
259 
260         if ($this->beforeRender($viewFile, $params)) {//如果前置事件执行成功
261             Yii::trace("Rendering view file: $viewFile", __METHOD__);//记录trace信息
262             $ext = pathinfo($viewFile, PATHINFO_EXTENSION);//视图文件扩展名
263             if (isset($this->renderers[$ext])) {//视图文件的扩展名是否支持
264                 if (is_array($this->renderers[$ext]) || is_string($this->renderers[$ext])) {
265                     $this->renderers[$ext] = Yii::createObject($this->renderers[$ext]);
266                 }
267                 /* @var $renderer ViewRenderer */
268                 $renderer = $this->renderers[$ext];//赋值view渲染器对象
269                 $output = $renderer->render($this, $viewFile, $params);//渲染视图文件
270             } else {//视图文件不是支持的类型，以普通php文件处理
271                 $output = $this->renderPhpFile($viewFile, $params);
272             }
273             $this->afterRender($viewFile, $params, $output);
274         }
275 
276         array_pop($this->_viewFiles);
277         $this->context = $oldContext;
278 
279         return $output;
280     }