yii2源碼學習筆記(十四），yii2源碼學習筆記

Module類是模塊和應用類的基類。　　yiisoft\yii2\base\Module.php

<span>  1</span> <?<span>php
</span><span>  2</span> <span>/*</span><span>*
</span><span>  3</span> <span> * @link </span><span>http://www.yiiframework.com/</span>
<span>  4</span> <span> * @copyright Copyright (c) 2008 Yii Software LLC
</span><span>  5</span> <span> * @license </span><span>http://www.yiiframework.com/license/</span>
<span>  6</span>  <span>*/</span>
<span>  7</span> 
<span>  8</span> <span>namespace</span> yii\<span>base</span><span>;
</span><span>  9</span> 
<span> 10</span> <span>use Yii;
</span><span> 11</span> <span>use yii\di\ServiceLocator;
</span><span> 12</span> 
<span> 13</span> <span>/*</span><span>*
</span><span> 14</span> <span> * Module is the base class for module and application classes.
</span><span> 15</span> <span> *  Module是模塊和應用類的基類
</span><span> 16</span> <span> * A module represents a sub-application which contains MVC elements by itself, such as
</span><span> 17</span> <span> * models, views, controllers, etc.
</span><span> 18</span> <span> * 模塊是一個由模型、視圖、控制器等組成的子應用
</span><span> 19</span> <span> * A module may consist of [[modules|sub-modules]].
</span><span> 20</span> <span> * 模塊內也可以包含模塊或子模塊
</span><span> 21</span> <span> * [[components|Components]] may be registered with the module so that they are globally
</span><span> 22</span> <span> * accessible within the module.
</span><span> 23</span> <span> * 組件可以注冊到模塊，以便在模塊內全局訪問
</span><span> 24</span> <span> * @property array $aliases List of path aliases to be defined. The array keys are alias names (must start
</span><span> 25</span> <span> * with '@') and the array values are the corresponding paths or aliases. See [[setAliases()]] for an example.
</span><span> 26</span> <span> * This property is write-only. 要定義的別名路徑數組    只寫
</span><span> 27</span> <span> * @property string $basePath The root directory of the module. 模塊的根路徑
</span><span> 28</span> <span> * @property string $controllerPath The directory that contains the controller classes. This property is
</span><span> 29</span> <span> * read-only.   控制器類的路徑 只讀
</span><span> 30</span> <span> * @property string $layoutPath The root directory of layout files. Defaults to "[[viewPath]]/layouts".
</span><span> 31</span> <span> * 模板路徑數組 只讀
</span><span> 32</span> <span> * @property array $modules The modules (indexed by their IDs). 模塊數組
</span><span> 33</span> <span> * @property string $uniqueId The unique ID of the module. This property is read-only.模塊的唯一標識 只讀
</span><span> 34</span> <span> * @property string $viewPath The root directory of view files. Defaults to "[[basePath]]/views".
</span><span> 35</span> <span> * 模塊下視圖文件路徑
</span><span> 36</span> <span> * @author Qiang Xue <qiang.xue@gmail.com>
</span><span> 37</span> <span> * @since 2.0
</span><span> 38</span>  <span>*/</span>
<span> 39</span> <span>class</span><span> Module extends ServiceLocator
</span><span> 40</span> <span>{
</span><span> 41</span>     <span>/*</span><span>*
</span><span> 42</span> <span>     * @event ActionEvent an event raised before executing a controller action. 在執(zhí)行控制的的action方法前觸發(fā)
</span><span> 43</span> <span>     * You may set [[ActionEvent::isValid]] to be false to cancel the action execution.
</span><span> 44</span> <span>     * 可以設置[[ActionEvent::isValid]]為false取消行動的執(zhí)行。
</span><span> 45</span>      <span>*/</span>
<span> 46</span>     <span>const</span> EVENT_BEFORE_ACTION = <span>'</span><span>beforeAction</span><span>'</span><span>;
</span><span> 47</span>     <span>/*</span><span>*
</span><span> 48</span> <span>     * @event ActionEvent an event raised after executing a controller action.
</span><span> 49</span> <span>     * 在執(zhí)行控制的的action方法后觸發(fā)
</span><span> 50</span> <span>     * 
</span><span> 51</span>      <span>*/</span>
<span> 52</span>     <span>const</span> EVENT_AFTER_ACTION = <span>'</span><span>afterAction</span><span>'</span><span>;
</span><span> 53</span> 
<span> 54</span>     <span>/*</span><span>*
</span><span> 55</span> <span>     * @var array custom module parameters (name => value). 自定義模塊參數
</span><span> 56</span>      <span>*/</span>
<span> 57</span>     <span>public</span> $<span>params</span> =<span> [];
</span><span> 58</span>     <span>/*</span><span>*
</span><span> 59</span> <span>     * @var string an ID that uniquely identifies this module among other modules which have the same [[module|parent]].
</span><span> 60</span> <span>     * 模塊的唯一標識，用于區(qū)分同一父模塊下的模塊
</span><span> 61</span>      <span>*/</span>
<span> 62</span>     <span>public</span><span> $id;
</span><span> 63</span>     <span>/*</span><span>*
</span><span> 64</span> <span>     * @var Module the parent module of this module. Null if this module does not have a parent.
</span><span> 65</span> <span>     *  當前模塊的父模塊
</span><span> 66</span>      <span>*/</span>
<span> 67</span>     <span>public</span><span> $module;
</span><span> 68</span>     <span>/*</span><span>*
</span><span> 69</span> <span>     * @var string|boolean the layout that should be applied for views within this module. This refers to a view name
</span><span> 70</span> <span>     * relative to [[layoutPath]]. If this is not set, it means the layout value of the [[module|parent module]]
</span><span> 71</span> <span>     * will be taken. If this is false, layout will be disabled within this module.
</span><span> 72</span> <span>     * 布局文件 如果沒有設置，調用 [[module|parent module]]的值。如果是false，在模塊中布局將被禁用。
</span><span> 73</span>      <span>*/</span>
<span> 74</span>     <span>public</span><span> $layout;
</span><span> 75</span>     <span>/*</span><span>*
</span><span> 76</span> <span>     * @var array mapping from controller ID to controller configurations. 控制器ID到控制器配置的映射
</span><span> 77</span> <span>     * Each name-value pair specifies the configuration of a single controller.
</span><span> 78</span> <span>     * A controller configuration can be either a string or an array.
</span><span> 79</span> <span>     * If the former, the string should be the fully qualified class name of the controller.
</span><span> 80</span> <span>     * If the latter, the array must contain a 'class' element which specifies
</span><span> 81</span> <span>     * the controller's fully qualified class name, and the rest of the name-value pairs
</span><span> 82</span> <span>     * in the array are used to initialize the corresponding controller properties. For example,
</span><span> 83</span> <span>     * 每個鍵值對指定單獨的控制器，控制器配置可以是字符串或者數組，如果是前者，該字符串是指定控制的的全路徑
</span><span> 84</span> <span> 95  * 如果是后者，則包含一個&lsquo;class&rsquo;元素指定控制器的全路徑，其余的參數用于初始化對應的屬性
</span><span> 85</span> <span>     * ~~~
</span><span> 86</span> <span>     * [
</span><span> 87</span> <span>     *   'account' => 'app\controllers\UserController',
</span><span> 88</span> <span>     *   'article' => [
</span><span> 89</span> <span>     *      'class' => 'app\controllers\PostController',
</span><span> 90</span> <span>     *      'pageTitle' => 'something new',
</span><span> 91</span> <span>     *   ],
</span><span> 92</span> <span>     * ]
</span><span> 93</span> <span>     * ~~~
</span><span> 94</span>      <span>*/</span>
<span> 95</span>     <span>public</span> $controllerMap =<span> [];
</span><span> 96</span>     <span>/*</span><span>*
</span><span> 97</span> <span>     * @var string the namespace that controller classes are in.    控制器的命名空間
</span><span> 98</span> <span>     * This namespace will be used to load controller classes by prepending it to the controller
</span><span> 99</span> <span>     * class name.
</span><span>100</span> <span>     * 命名空間 在控制器類的前面加載控制器類
</span><span>101</span> <span>     * If not set, it will use the `controllers` sub-namespace under the namespace of this module.
</span><span>102</span> <span>     * For example, if the namespace of this module is "foo\bar", then the default
</span><span>103</span> <span>     * controller namespace would be "foo\bar\controllers".
</span><span>104</span> <span>     * 如果沒有設置，默認為當前模塊的命名空間加上 `controllers`構成的命名空間
</span><span>105</span> <span>119  * 如當前模塊的命名空間為"foo\bar"，控制器的默認命名空間為"foo\bar\controllers"
</span><span>106</span> <span>     * See also the [guide section on autoloading](guide:concept-autoloading) to learn more about
</span><span>107</span> <span>     * defining namespaces and how classes are loaded.
</span><span>108</span>      <span>*/</span>
<span>109</span>     <span>public</span><span> $controllerNamespace;
</span><span>110</span>     <span>/*</span><span>*
</span><span>111</span> <span>     * @var string the default route of this module. Defaults to 'default'. 當前前模塊的默認路由
</span><span>112</span> <span>     * The route may consist of child module ID, controller ID, and/or action ID.
</span><span>113</span> <span>     * For example, `help`, `post/create`, `admin/post/create`.
</span><span>114</span> <span>     * If action ID is not given, it will take the default value as specified in
</span><span>115</span> <span>     * [[Controller::defaultAction]].
</span><span>116</span> <span>     * route 可能包含子模塊ID，控制器ID，操作ID，如果action ID未給定，會調用[Controller::defaultAction]指定的action
</span><span>117</span>      <span>*/</span>
<span>118</span>     <span>public</span> $defaultRoute = <span>'</span><span>default</span><span>'</span><span>;
</span><span>119</span> 
<span>120</span>     <span>/*</span><span>*
</span><span>121</span> <span>     * @var string the root directory of the module.    當前模塊的根路徑
</span><span>122</span>      <span>*/</span>
<span>123</span>     <span>private</span><span> $_basePath;
</span><span>124</span>     <span>/*</span><span>*
</span><span>125</span> <span>     * @var string the root directory that contains view files for this module 當前模塊下視圖文件的路徑
</span><span>126</span>      <span>*/</span>
<span>127</span>     <span>private</span><span> $_viewPath;
</span><span>128</span>     <span>/*</span><span>*
</span><span>129</span> <span>     * @var string the root directory that contains layout view files for this module.
</span><span>130</span> <span>     * 當前模塊下的布局文件路徑
</span><span>131</span>      <span>*/</span>
<span>132</span>     <span>private</span><span> $_layoutPath;
</span><span>133</span>     <span>/*</span><span>*
</span><span>134</span> <span>     * @var array child modules of this module  當前模塊的子模塊數組
</span><span>135</span>      <span>*/</span>
<span>136</span>     <span>private</span> $_modules =<span> [];
</span><span>137</span> 
<span>138</span> 
<span>139</span>     <span>/*</span><span>*
</span><span>140</span> <span>     * Constructor. 構造函數
</span><span>141</span> <span>     * @param string $id the ID of this module 當前模塊的標識
</span><span>142</span> <span>     * @param Module $parent the parent module (if any) 當前模塊的父模塊
</span><span>143</span> <span>     * @param array $config name-value pairs that will be used to initialize the object properties
</span><span>144</span> <span>     * 配置文件 用于初始化對象屬性
</span><span>145</span>      <span>*/</span>
<span>146</span>     <span>public</span> function __construct($id, $parent = <span>null</span>, $config =<span> [])
</span><span>147</span> <span>    {
</span><span>148</span>         $<span>this</span>->id = $id; <span>//</span><span>給當前模塊唯一標識</span>
<span>149</span>         $<span>this</span>->module = $parent;    <span>//</span><span>當前模塊的父模塊</span>
<span>150</span>         parent::__construct($config);   <span>//</span><span>調用父類的配置</span>
<span>151</span> <span>    }
</span><span>152</span> 
<span>153</span>     <span>/*</span><span>*
</span><span>154</span> <span>     * Returns the currently requested instance of this module class.   取得當前類的實例
</span><span>155</span> <span>     * If the module class is not currently requested, null will be returned.
</span><span>156</span> <span>     * 沒有當前請求的模塊類，將返回null。
</span><span>157</span> <span>     * This method is provided so that you access the module instance from anywhere within the module.
</span><span>158</span> <span>     * 可以在模塊內的任何地方訪問類的實例
</span><span>159</span> <span>     * @return static|null the currently requested instance of this module class, or null if the module class is not requested.
</span><span>160</span>      <span>*/</span>
<span>161</span>     <span>public</span> <span>static</span><span> function getInstance()
</span><span>162</span> <span>    {
</span><span>163</span>         $<span>class</span> =<span> get_called_class();
</span><span>164</span>         <span>return</span> isset(Yii::$app->loadedModules[$<span>class</span>]) ? Yii::$app->loadedModules[$<span>class</span>] : <span>null</span><span>;
</span><span>165</span> <span>    }
</span><span>166</span> 
<span>167</span>     <span>/*</span><span>*
</span><span>168</span> <span>     * Sets the currently requested instance of this module class.  設置模塊類的當前請求實例。
</span><span>169</span> <span>     * @param Module|null $instance the currently requested instance of this module class.
</span><span>170</span> <span>     * If it is null, the instance of the calling class will be removed, if any.
</span><span>171</span> <span>     * 當前模塊類的實例。如果為null，調用類的實例將被刪除
</span><span>172</span>      <span>*/</span>
<span>173</span>     <span>public</span> <span>static</span><span> function setInstance($instance)
</span><span>174</span> <span>    {
</span><span>175</span>         <span>if</span> ($instance === <span>null</span>) {<span>//</span><span>如果沒有傳入參數，直接unset</span>
<span>176</span>             unset(Yii::$app-><span>loadedModules[get_called_class()]);
</span><span>177</span>         } <span>else</span> {<span>//</span><span>將該類和類的實例存入loadedModules數組中</span>
<span>178</span>             Yii::$app->loadedModules[get_class($instance)] =<span> $instance;
</span><span>179</span> <span>        }
</span><span>180</span> <span>    }
</span><span>181</span> 
<span>182</span>     <span>/*</span><span>*
</span><span>183</span> <span>     * Initializes the module.
</span><span>184</span> <span>     * 初始化模塊
</span><span>185</span> <span>     * This method is called after the module is created and initialized with property values
</span><span>186</span> <span>     * given in configuration. The default implementation will initialize [[controllerNamespace]]
</span><span>187</span> <span>     * if it is not set.
</span><span>188</span> <span>     * 該模塊創(chuàng)建和初始化給出的配置  如果沒有設置，默認初始化[[controllerNamespace]]
</span><span>189</span> <span>     * If you override this method, please make sure you call the parent implementation.
</span><span>190</span> <span>     * 重寫確保父類調用
</span><span>191</span>      <span>*/</span>
<span>192</span>     <span>public</span><span> function init()
</span><span>193</span> <span>    {
</span><span>194</span>         <span>if</span> ($<span>this</span>->controllerNamespace === <span>null</span>) {<span>//</span><span>判斷是否為空</span>
<span>195</span>             $<span>class</span> = get_class($<span>this</span>); <span>//</span><span>獲取類名</span>
<span>196</span>             <span>if</span> (($pos = strrpos($<span>class</span>, <span>'</span><span>\\</span><span>'</span>)) !== <span>false</span><span>) {
</span><span>197</span>                 $<span>this</span>->controllerNamespace = substr($<span>class</span>, <span>0</span>, $pos) . <span>'</span><span>\\controllers</span><span>'</span>; <span>//</span><span>取得命名空間</span>
<span>198</span> <span>            }
</span><span>199</span> <span>        }
</span><span>200</span> <span>    }
</span><span>201</span> 
<span>202</span>     <span>/*</span><span>*
</span><span>203</span> <span>     * Returns an ID that uniquely identifies this module among all modules within the current application.
</span><span>204</span> <span>     * Note that if the module is an application, an empty string will be returned.
</span><span>205</span> <span>     * 當前應用程序中模塊的唯一標識，如果該模塊是應用程序返回空字符串
</span><span>206</span> <span>     * @return string the unique ID of the module.模塊的唯一標識
</span><span>207</span>      <span>*/</span>
<span>208</span>     <span>public</span><span> function getUniqueId()
</span><span>209</span>     {     <span>//</span><span>如果當前模塊有父模塊，則返回拼接的標識作為唯一ID，否則只返回當前模塊ID</span>
<span>210</span>         <span>return</span> $<span>this</span>->module ? ltrim($<span>this</span>->module->getUniqueId() . <span>'</span><span>/</span><span>'</span> . $<span>this</span>->id, <span>'</span><span>/</span><span>'</span>) : $<span>this</span>-><span>id;
</span><span>211</span> <span>    }
</span><span>212</span> 
<span>213</span>     <span>/*</span><span>*
</span><span>214</span> <span>     * Returns the root directory of the module.    返回當前模塊的根路徑
</span><span>215</span> <span>     * It defaults to the directory containing the module class file.   默認為包含模塊類文件的路徑。
</span><span>216</span> <span>     * @return string the root directory of the module. 當前模塊的根路徑
</span><span>217</span>      <span>*/</span>
<span>218</span>     <span>public</span><span> function getBasePath()
</span><span>219</span> <span>    {
</span><span>220</span>         <span>if</span> ($<span>this</span>->_basePath === <span>null</span><span>) {
</span><span>221</span>             $<span>class</span> = <span>new</span> \ReflectionClass($<span>this</span>);   <span>//</span><span>生成當前類的反射對象</span>
<span>222</span>             $<span>this</span>->_basePath = dirname($<span>class</span>->getFileName());<span>//</span><span>取得類定義的路徑</span>
<span>223</span> <span>        }
</span><span>224</span> 
<span>225</span>         <span>return</span> $<span>this</span>-><span>_basePath;
</span><span>226</span> <span>    }
</span><span>227</span> 
<span>228</span>     <span>/*</span><span>*
</span><span>229</span> <span>     * Sets the root directory of the module.   設置當前模塊的根路徑
</span><span>230</span> <span>     * This method can only be invoked at the beginning of the constructor. 只在構造函數開始時調用。
</span><span>231</span> <span>     * @param string $path the root directory of the module. This can be either a directory name or a path alias.
</span><span>232</span> <span>     * 模塊的根目錄?？梢允且粋€目錄名或路徑別名
</span><span>233</span> <span>     * @throws InvalidParamException if the directory does not exist. 如果路徑不存在。拋出異常
</span><span>234</span>      <span>*/</span>
<span>235</span>     <span>public</span><span> function setBasePath($path)
</span><span>236</span> <span>    {
</span><span>237</span>         $path = Yii::getAlias($path);<span>//</span><span>將路徑別名轉換為實際路徑。</span>
<span>238</span>         $p = realpath($path);   <span>//</span><span>返回絕對路徑名</span>
<span>239</span>         <span>if</span> ($p !== <span>false</span> &&<span> is_dir($p)) {
</span><span>240</span>             $<span>this</span>->_basePath = $p;<span>//</span><span>是目錄名且不為false，返回目錄名，否則拋出異常</span>
<span>241</span>         } <span>else</span><span> {
</span><span>242</span>             <span>throw</span> <span>new</span> InvalidParamException(<span>"</span><span>The directory does not exist: $path</span><span>"</span><span>);
</span><span>243</span> <span>        }
</span><span>244</span>     }

?