yii2 source code study notes (19), yii2 source code study notes

yii2 source code study notes (19), yii2 source code study notes

view the remaining code

<span>  1</span>     <span>/*</span><span>*
</span><span>  2</span> <span>     * @return string|boolean the view file currently being rendered. False if no view file is being rendered.
</span><span>  3</span> <span>     * 当前正在渲染的视图文件
</span><span>  4</span>      <span>*/</span>
<span>  5</span>     <span>public</span><span> function getViewFile()
</span><span>  6</span> <span>    {
</span><span>  7</span>         <span>return</span> end($<span>this</span>-><span>_viewFiles);
</span><span>  8</span> <span>    }
</span><span>  9</span> 
<span> 10</span>     <span>/*</span><span>*
</span><span> 11</span> <span>     * This method is invoked right before [[renderFile()]] renders a view file.
</span><span> 12</span> <span>     * The default implementation will trigger the [[EVENT_BEFORE_RENDER]] event.
</span><span> 13</span> <span>     * 前置事件，执行[renderFile()]时被调用，默认触发[[EVENT_BEFORE_RENDER]]事件
</span><span> 14</span> <span>     * If you override this method, make sure you call the parent implementation first.
</span><span> 15</span> <span>     * @param string $viewFile the view file to be rendered. 要渲染的视图文件。
</span><span> 16</span> <span>     * @param array $params the parameter array passed to the [[render()]] method.
</span><span> 17</span> <span>     * 参数数组传递到[render()]方法。
</span><span> 18</span> <span>     * @return boolean whether to continue rendering the view file. 是否继续渲染视图文件。
</span><span> 19</span>      <span>*/</span>
<span> 20</span>     <span>public</span> function beforeRender($viewFile, $<span>params</span><span>)
</span><span> 21</span> <span>    {
</span><span> 22</span>         $<span>event</span> = <span>new</span> ViewEvent([<span>//</span><span>实例化ViewEvent</span>
<span> 23</span>             <span>'</span><span>viewFile</span><span>'</span> =><span> $viewFile,
</span><span> 24</span>             <span>'</span><span>params</span><span>'</span> => $<span>params</span><span>,
</span><span> 25</span> <span>        ]);
</span><span> 26</span>         $<span>this</span>->trigger(self::EVENT_BEFORE_RENDER, $<span>event</span>);<span>//</span><span>触发[EVENT_BEFORE_RENDER]事件</span>
<span> 27</span> 
<span> 28</span>         <span>return</span> $<span>event</span>->isValid;<span>//</span><span>判断是否继续渲染文件</span>
<span> 29</span> <span>    }
</span><span> 30</span> 
<span> 31</span>     <span>/*</span><span>*
</span><span> 32</span> <span>     * This method is invoked right after [[renderFile()]] renders a view file.
</span><span> 33</span> <span>     * The default implementation will trigger the [[EVENT_AFTER_RENDER]] event.
</span><span> 34</span> <span>     * 后置事件，在执行[renderFile()]方法后被调用，默认触发[[EVENT_AFTER_RENDER]]事件
</span><span> 35</span> <span>     * If you override this method, make sure you call the parent implementation first.
</span><span> 36</span> <span>     * @param string $viewFile the view file being rendered.要渲染的视图文件。
</span><span> 37</span> <span>     * @param array $params the parameter array passed to the [[render()]] method.
</span><span> 38</span> <span>     * 参数数组传递到[render()]方法。
</span><span> 39</span> <span>     * @param string $output the rendering result of the view file. Updates to this parameter
</span><span> 40</span> <span>     * will be passed back and returned by [[renderFile()]].
</span><span> 41</span> <span>     * 返回视图渲染的结果
</span><span> 42</span>      <span>*/</span>
<span> 43</span>     <span>public</span> function afterRender($viewFile, $<span>params</span>, &<span>$output)
</span><span> 44</span> <span>    {
</span><span> 45</span>         <span>if</span> ($<span>this</span>->hasEventHandlers(self::EVENT_AFTER_RENDER)) {<span>//</span><span>判断[EVENT_AFTER_RENDER]事件是否存在</span>
<span> 46</span>             $<span>event</span> = <span>new</span><span> ViewEvent([
</span><span> 47</span>                 <span>'</span><span>viewFile</span><span>'</span> =><span> $viewFile,
</span><span> 48</span>                 <span>'</span><span>params</span><span>'</span> => $<span>params</span><span>,
</span><span> 49</span>                 <span>'</span><span>output</span><span>'</span> =><span> $output,
</span><span> 50</span> <span>            ]);
</span><span> 51</span>             <span>//</span><span>触发[EVENT_AFTER_RENDER]事件</span>
<span> 52</span>             $<span>this</span>->trigger(self::EVENT_AFTER_RENDER, $<span>event</span><span>);
</span><span> 53</span>             $output = $<span>event</span>->output;<span>//</span><span>返回结果</span>
<span> 54</span> <span>        }
</span><span> 55</span> <span>    }
</span><span> 56</span> 
<span> 57</span>     <span>/*</span><span>*
</span><span> 58</span> <span>     * Renders a view file as a PHP script.
</span><span> 59</span> <span>     * 返回一个视图文件当作PHP脚本
</span><span> 60</span> <span>     * This method treats the view file as a PHP script and includes the file.
</span><span> 61</span> <span>     * It extracts the given parameters and makes them available in the view file.
</span><span> 62</span> <span>     * The method captures the output of the included view file and returns it as a string.
</span><span> 63</span> <span>     * 将传入的参数转换为变量，包含并执行view文件，返回执行结果
</span><span> 64</span> <span>     * This method should mainly be called by view renderer or [[renderFile()]].
</span><span> 65</span> <span>     *
</span><span> 66</span> <span>     * @param string $_file_ the view file. 视图文件
</span><span> 67</span> <span>     * @param array $_params_ the parameters (name-value pairs) that will be extracted and made available in the view file.
</span><span> 68</span> <span>     * @return string the rendering result 执行结果
</span><span> 69</span>      <span>*/</span>
<span> 70</span>     <span>public</span> function renderPhpFile($_file_, $_params_ =<span> [])
</span><span> 71</span> <span>    {
</span><span> 72</span>         ob_start(); <span>//</span><span>打开输出缓冲</span>
<span> 73</span>         ob_implicit_flush(<span>false</span>); <span>//</span><span>关闭缓冲区</span>
<span> 74</span>         extract($_params_, EXTR_OVERWRITE);<span>//</span><span> 将一个数组转换为变量使用</span>
<span> 75</span> <span>        require($_file_);
</span><span> 76</span>         
<span> 77</span>         <span>return</span> ob_get_clean();<span>//</span><span>得到缓冲区的内容并清除当前输出缓冲</span>
<span> 78</span> <span>    }
</span><span> 79</span> 
<span> 80</span>     <span>/*</span><span>*
</span><span> 81</span> <span>     * Renders dynamic content returned by the given PHP statements. 渲染动态内容
</span><span> 82</span> <span>     * This method is mainly used together with content caching (fragment caching and page caching)
</span><span> 83</span> <span>     * 用来聚合缓存的内容
</span><span> 84</span> <span>     * when some portions of the content (called *dynamic content*) should not be cached.
</span><span> 85</span> <span>     * The dynamic content must be returned by some PHP statements.
</span><span> 86</span> <span>     * 渲染某些被PHP语句返回的动态内容
</span><span> 87</span> <span>     * @param string $statements the PHP statements for generating the dynamic content.生成动态内容的PHP语句。
</span><span> 88</span> <span>     * @return string the placeholder of the dynamic content, or the dynamic content if there is no
</span><span> 89</span> <span>     * active content cache currently. 动态内容占位符 如果当前没有有效的内容缓存，调用evaluateDynamicContent输出
</span><span> 90</span>      <span>*/</span>
<span> 91</span>     <span>public</span><span> function renderDynamic($statements)
</span><span> 92</span> <span>    {
</span><span> 93</span>         <span>if</span> (!empty($<span>this</span>->cacheStack)) {<span>//</span><span>动态内容的列表不为空</span>
<span> 94</span>             $n = count($<span>this</span>->dynamicPlaceholders);<span>//</span><span>统计动态内容条数</span>
<span> 95</span>             $placeholder = <span>"</span><span><![CDATA[YII-DYNAMIC-$n]]></span><span>"</span>;<span>//</span><span>生成占位符</span>
<span> 96</span>             $<span>this</span>->addDynamicPlaceholder($placeholder, $statements);<span>//</span><span>添加动态内容占位符</span>
<span> 97</span> 
<span> 98</span>             <span>return</span><span> $placeholder;
</span><span> 99</span>         } <span>else</span> {<span>//</span><span>没有有效缓存 执行传入的PHP语句，返回执行结果</span>
<span>100</span>             <span>return</span> $<span>this</span>-><span>evaluateDynamicContent($statements);
</span><span>101</span> <span>        }
</span><span>102</span> <span>    }
</span><span>103</span> 
<span>104</span>     <span>/*</span><span>*
</span><span>105</span> <span>     * Adds a placeholder for dynamic content. 添加一个动态内容占位符
</span><span>106</span> <span>     * This method is internally used. 内部使用
</span><span>107</span> <span>     * @param string $placeholder the placeholder name 占位符名称
</span><span>108</span> <span>     * @param string $statements the PHP statements for generating the dynamic content
</span><span>109</span> <span>     * 生成动态内容的PHP语句
</span><span>110</span>      <span>*/</span>
<span>111</span>     <span>public</span><span> function addDynamicPlaceholder($placeholder, $statements)
</span><span>112</span> <span>    {
</span><span>113</span>         <span>foreach</span> ($<span>this</span>->cacheStack <span>as</span><span> $cache) {
</span><span>114</span>             $cache->dynamicPlaceholders[$placeholder] = $statements;<span>//</span><span>添加动态内容占位符</span>
<span>115</span> <span>        }
</span><span>116</span>         $<span>this</span>->dynamicPlaceholders[$placeholder] = $statements;<span>//</span><span>给当前视图添加动态内容占位符</span>
<span>117</span> <span>    }
</span><span>118</span> 
<span>119</span>     <span>/*</span><span>*
</span><span>120</span> <span>     * Evaluates the given PHP statements. 给定的PHP语句的值
</span><span>121</span> <span>     * This method is mainly used internally to implement dynamic content feature.内部使用实现动态内容功能
</span><span>122</span> <span>     * @param string $statements the PHP statements to be evaluated. PHP语句进行计算
</span><span>123</span> <span>     * @return mixed the return value of the PHP statements. PHP语句的值
</span><span>124</span>      <span>*/</span>
<span>125</span>     <span>public</span><span> function evaluateDynamicContent($statements)
</span><span>126</span> <span>    {
</span><span>127</span>         <span>return</span><span> eval($statements);
</span><span>128</span> <span>    }
</span><span>129</span> 
<span>130</span>     <span>/*</span><span>*
</span><span>131</span> <span>     * Begins recording a block.
</span><span>132</span> <span>     * This method is a shortcut to beginning [[Block]]
</span><span>133</span> <span>     * 数据块开始的标记，该方法是开始[Block]的快捷方式
</span><span>134</span> <span>     * 数据块可以在一个地方指定视图内容在另一个地方显示，通常和布局一起使用
</span><span>135</span> <span>     * @param string $id the block ID. 数据块标识
</span><span>136</span> <span>     * @param boolean $renderInPlace whether to render the block content in place. 是否渲染块内容。
</span><span>137</span> <span>     * Defaults to false, meaning the captured block will not be displayed.
</span><span>138</span> <span>     * @return Block the Block widget instance 数据块部件实例
</span><span>139</span>      <span>*/</span>
<span>140</span>     <span>public</span> function beginBlock($id, $renderInPlace = <span>false</span><span>)
</span><span>141</span> <span>    {
</span><span>142</span>         <span>return</span><span> Block::begin([
</span><span>143</span>             <span>'</span><span>id</span><span>'</span> => $id,<span>//</span><span>数据块唯一标识</span>
<span>144</span>             <span>'</span><span>renderInPlace</span><span>'</span> => $renderInPlace,<span>//</span><span>是否显示标识</span>
<span>145</span>             <span>'</span><span>view</span><span>'</span> => $<span>this</span><span>,
</span><span>146</span> <span>        ]);
</span><span>147</span> <span>    }
</span><span>148</span> 
<span>149</span>     <span>/*</span><span>*
</span><span>150</span> <span>     * Ends recording a block. 数据块结束标识
</span><span>151</span>      <span>*/</span>
<span>152</span>     <span>public</span><span> function endBlock()
</span><span>153</span> <span>    {
</span><span>154</span> <span>        Block::end();
</span><span>155</span> <span>    }
</span><span>156</span> 
<span>157</span>     <span>/*</span><span>*
</span><span>158</span> <span>     * Begins the rendering of content that is to be decorated by the specified view.
</span><span>159</span> <span>     * This method can be used to implement nested layout. For example, a layout can be embedded
</span><span>160</span> <span>     * in another layout file specified as '@app/views/layouts/base.php' like the following:
</span><span>161</span> <span>     * 开始指定的view渲染内容，用来实现嵌套布局，传入的第一个参数为布局文件的路径
</span><span>162</span> <span>     * ~~~
</span><span>163</span> <span>     * <?php $this->beginContent('@app/views/layouts/base.php'); ?>
</span><span>164</span> <span>     * ...layout content here...
</span><span>165</span> <span>     * <?php $this->endContent(); ?>
</span><span>166</span> <span>     * ~~~
</span><span>167</span> <span>     *
</span><span>168</span> <span>     * @param string $viewFile the view file that will be used to decorate the content enclosed by this widget.
</span><span>169</span> <span>     * This can be specified as either the view file path or path alias.布局文件的路径或路径别名。
</span><span>170</span> <span>     * @param array $params the variables (name => value) to be extracted and made available in the decorative view.
</span><span>171</span> <span>     * 可以在视图中运用的参数
</span><span>172</span> <span>     * @return ContentDecorator the ContentDecorator widget instance 部件实例
</span><span>173</span> <span>     * @see ContentDecorator
</span><span>174</span>      <span>*/</span>
<span>175</span>     <span>public</span> function beginContent($viewFile, $<span>params</span> =<span> [])
</span><span>176</span> <span>    {
</span><span>177</span>         <span>return</span><span> ContentDecorator::begin([
</span><span>178</span>             <span>'</span><span>viewFile</span><span>'</span> =><span> $viewFile,
</span><span>179</span>             <span>'</span><span>params</span><span>'</span> => $<span>params</span><span>,
</span><span>180</span>             <span>'</span><span>view</span><span>'</span> => $<span>this</span><span>,
</span><span>181</span> <span>        ]);
</span><span>182</span> <span>    }
</span><span>183</span> 
<span>184</span>     <span>/*</span><span>*
</span><span>185</span> <span>     * Ends the rendering of content.结束渲染内容
</span><span>186</span>      <span>*/</span>
<span>187</span>     <span>public</span><span> function endContent()
</span><span>188</span> <span>    {
</span><span>189</span> <span>        ContentDecorator::end();
</span><span>190</span> <span>    }
</span><span>191</span> 
<span>192</span>     <span>/*</span><span>*
</span><span>193</span> <span>     * Begins fragment caching. 开始片段缓存
</span><span>194</span> <span>     * This method will display cached content if it is available.
</span><span>195</span> <span>     * If not, it will start caching and would expect an [[endCache()]]
</span><span>196</span> <span>     * call to end the cache and save the content into cache.
</span><span>197</span> <span>     * 展示可用的缓存内容，否则将开始缓存内容直到出现[endCache()]方法
</span><span>198</span> <span>     * A typical usage of fragment caching is as follows,
</span><span>199</span> <span>     *
</span><span>200</span> <span>     * ~~~
</span><span>201</span> <span>     * if ($this->beginCache($id)) {
</span><span>202</span> <span>     *     // ...generate content here
</span><span>203</span> <span>     *     $this->endCache();
</span><span>204</span> <span>     * }
</span><span>205</span> <span>     * ~~~
</span><span>206</span> <span>     *
</span><span>207</span> <span>     * @param string $id a unique ID identifying the fragment to be cached.缓存片段的唯一标识
</span><span>208</span> <span>     * @param array $properties initial property values for [[FragmentCache]]初始属性[FragmentCache]
</span><span>209</span> <span>     * @return boolean whether you should generate the content for caching. 是否生成缓存的内容。
</span><span>210</span> <span>     * False if the cached version is available.
</span><span>211</span>      <span>*/</span>
<span>212</span>     <span>public</span> function beginCache($id, $properties =<span> [])
</span><span>213</span> <span>    {
</span><span>214</span>         $properties[<span>'</span><span>id</span><span>'</span>] = $id;    <span>//</span><span>片段标识</span>
<span>215</span>         $properties[<span>'</span><span>view</span><span>'</span>] = $<span>this</span>;    <span>//</span><span>调用初始化属性</span>
<span>216</span>         <span>/*</span><span> @var $cache FragmentCache </span><span>*/</span>
<span>217</span>         $cache =<span> FragmentCache::begin($properties); 
</span><span>218</span>         <span>if</span> ($cache->getCachedContent() !== <span>false</span><span>) {
</span><span>219</span>             $<span>this</span>->endCache();<span>//</span><span>从缓存中读取到了缓存的内容，则渲染内容并返回 false，不再进行缓存</span>
<span>220</span> 
<span>221</span>             <span>return</span> <span>false</span><span>;
</span><span>222</span>         } <span>else</span><span> {
</span><span>223</span>             <span>return</span> <span>true</span><span>;
</span><span>224</span> <span>        }
</span><span>225</span> <span>    }
</span><span>226</span> 
<span>227</span>     <span>/*</span><span>*
</span><span>228</span> <span>     * Ends fragment caching. 结束片段缓存
</span><span>229</span>      <span>*/</span>
<span>230</span>     <span>public</span><span> function endCache()
</span><span>231</span> <span>    {
</span><span>232</span> <span>        FragmentCache::end();
</span><span>233</span> <span>    }
</span><span>234</span> 
<span>235</span>     <span>/*</span><span>*
</span><span>236</span> <span>     * Marks the beginning of a page.页面开始标记
</span><span>237</span>      <span>*/</span>
<span>238</span>     <span>public</span><span> function beginPage()
</span><span>239</span> <span>    {
</span><span>240</span>         ob_start(); <span>//</span><span>打开输出缓冲</span>
<span>241</span>         ob_implicit_flush(<span>false</span>);<span>//</span><span>关闭缓冲区</span>
<span>242</span> 
<span>243</span>         $<span>this</span>-><span>trigger(self::EVENT_BEGIN_PAGE);
</span><span>244</span> <span>    }
</span><span>245</span> 
<span>246</span>     <span>/*</span><span>*
</span><span>247</span> <span>     * Marks the ending of a page. 页面结束标记
</span><span>248</span>      <span>*/</span>
<span>249</span>     <span>public</span><span> function endPage()
</span><span>250</span> <span>    {
</span><span>251</span>         $<span>this</span>-><span>trigger(self::EVENT_END_PAGE);
</span><span>252</span>         ob_end_flush();<span>//</span><span>关闭输出缓冲区</span>
<span>253</span>     }