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