Yii源码阅读笔记（二十二）

  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  *
 17  * A module represents a sub-application which contains MVC elements by itself, such as
 18  * models, views, controllers, etc.
 19  * 模块代表一个由模型、视图、控制器等组成的子应用
 20  *
 21  * A module may consist of [[modules|sub-modules]].
 22  * 模块内也可以包含模块或子模块
 23  *
 24  * [[components|Components]] may be registered with the module so that they are globally
 25  * accessible within the module.
 26  * 组件可以注册到模块，以便在模块内全局访问
 27  *
 28  * @property array $aliases List of path aliases to be defined. The array keys are alias names (must start
 29  * with ‘@‘) and the array values are the corresponding paths or aliases. See [[setAliases()]] for an example.
 30  * This property is write-only.
 31  * @property array $aliases 别名数组  只读
 32  * @property string $basePath The root directory of the module.
 33  * @property string $basePath  模块的根路径
 34  * @property string $controllerPath The directory that contains the controller classes. This property is
 35  * read-only.
 36  * @property string $controllerPath 控制的路径数组 只读
 37  * @property string $layoutPath The root directory of layout files. Defaults to "[[viewPath]]/layouts".
 38  * @property string $layoutPath 模板路径数组 只读
 39  * @property array $modules The modules (indexed by their IDs).
 40  * @property array $modules 模块数组
 41  * @property string $uniqueId The unique ID of the module. This property is read-only.
 42  * @property string $uniqueId 模块的唯一ID 只读
 43  * @property string $viewPath The root directory of view files. Defaults to "[[basePath]]/views".
 44  * @property string $viewPath 模块下的视图文件路径
 45  *
 46  * @author Qiang Xue <qiang.xue@gmail.com>
 47  * @since 2.0
 48  */
 49 class Module extends ServiceLocator
 50 {
 51     /**
 52      * @event ActionEvent an event raised before executing a controller action.
 53      * @event ActionEvent Action事件，在执行控制的的action方法时触发
 54      * You may set [[ActionEvent::isValid]] to be false to cancel the action execution.
 55      */
 56     const EVENT_BEFORE_ACTION = ‘beforeAction‘;
 57     /**
 58      * @event ActionEvent an event raised after executing a controller action.
 59      * @event ActionEvent Action事件，在执行控制的的action方法后触发
 60      */
 61     const EVENT_AFTER_ACTION = ‘afterAction‘;
 62 
 63     /**
 64      * @var array custom module parameters (name => value).
 65      * @var array 自定义模块参数
 66      */
 67     public $params = [];
 68     /**
 69      * @var string an ID that uniquely identifies this module among other modules which have the same [[module|parent]].
 70      * @var string 模块的唯一ID，用于区分同一父模块下的模块
 71      */
 72     public $id;
 73     /**
 74      * @var Module the parent module of this module. Null if this module does not have a parent.
 75      * @var 当前模块的父模块
 76      */
 77     public $module;
 78     /**
 79      * @var string|boolean the layout that should be applied for views within this module. This refers to a view name
 80      * relative to [[layoutPath]]. If this is not set, it means the layout value of the [[module|parent module]]
 81      * will be taken. If this is false, layout will be disabled within this module.
 82      * @var string|boolean 布局文件
 83      */
 84     public $layout;
 85     /**
 86      * @var array mapping from controller ID to controller configurations.
 87      * @var array 控制器ID到控制器配置的映射
 88      * Each name-value pair specifies the configuration of a single controller.
 89      * A controller configuration can be either a string or an array.
 90      * If the former, the string should be the fully qualified class name of the controller.
 91      * If the latter, the array must contain a ‘class‘ element which specifies
 92      * the controller‘s fully qualified class name, and the rest of the name-value pairs
 93      * in the array are used to initialize the corresponding controller properties. For example,
 94      * 每一个键值对指定一个单独的控制器，控制器配置可以是一个字符串或者数组，如果是前者，该字符串是指定控制的的全路径（即带命名空间的）
 95      * 如果是后者，则数组中包含一个‘class’元素，该元素指定控制器的全路径，其余的参数用于初始化对应的属性，例子如下：
 96      *
 97      * ```php
 98      * [
 99      *   ‘account‘ => ‘app\controllers\UserController‘,//字符串形式，指定了accout控制器的路径
100      *   ‘article‘ => [
101      *      ‘class‘ => ‘app\controllers\PostController‘,//指定article控制器的路径
102      *      ‘pageTitle‘ => ‘something new‘,//提供了pageTitle参数
103      *   ],
104      * ]
105      * ```
106      */
107     public $controllerMap = [];
108     /**
109      * @var string the namespace that controller classes are in.
110      * @var string 控制器的命名空间
111      * This namespace will be used to load controller classes by prepending it to the controller
112      * class name.
113      * 该命名空间用于加在控制器类的前面加载控制器类
114      *
115      * If not set, it will use the `controllers` sub-namespace under the namespace of this module.
116      * For example, if the namespace of this module is "foo\bar", then the default
117      * controller namespace would be "foo\bar\controllers".
118      * 如果没有给定，默认为当前模块的命名空间加上 `controllers`构成的子命名空间
119      * 如当前模块的命名空间为"foo\bar"，那么控制器的默认命名空间为"foo\bar\controllers"
120      *
121      * See also the [guide section on autoloading](guide:concept-autoloading) to learn more about
122      * defining namespaces and how classes are loaded.
123      */
124     public $controllerNamespace;
125     /**
126      * @var string the default route of this module. Defaults to ‘default‘.
127      * @var string 当前模块的默认路由 默认为‘default‘
128      * The route may consist of child module ID, controller ID, and/or action ID.
129      * route 可能包含子模块ID，控制器ID，和/或 action ID，如果action ID未给定，则会调用[Controller::defaultAction]指定的action
130      * For example, `help`, `post/create`, `admin/post/create`.
131      * If action ID is not given, it will take the default value as specified in
132      * [[Controller::defaultAction]].
133      */
134     public $defaultRoute = ‘default‘;
135 
136     /**
137      * @var string the root directory of the module.
138      * @var string 当前模块的根路径
139      */
140     private $_basePath;
141     /**
142      * @var string the root directory that contains view files for this module
143      * @var string 当前模块下视图文件的路径数组
144      */
145     private $_viewPath;
146     /**
147      * @var string the root directory that contains layout view files for this module.
148      * @var string 当前模块下的布局文件路径数组
149      */
150     private $_layoutPath;
151     /**
152      * @var array child modules of this module
153      * @var array 当前模块的子模块数组
154      */
155     private $_modules = [];
156 
157 
158     /**
159      * Constructor.
160      * 构造函数
161      * @param string $id the ID of this module
162      * @param string $id 当前模块的ID
163      * @param Module $parent the parent module (if any)
164      * @param Module $parent 当前模块的父模块（如果有的话）
165      * @param array $config name-value pairs that will be used to initialize the object properties
166      * @param array $config 配置文件|数组
167      */
168     public function __construct($id, $parent = null, $config = [])
169     {
170         $this->id = $id;//给当前模块赋值唯一ID
171         $this->module = $parent;//给module属性（即当前模块的父模块）赋值
172         parent::__construct($config);//将配置文件赋值到Object的属性中，因为Object是所有类的基类，理论可以整个项目中访问
173     }
174 
175     /**
176      * Returns the currently requested instance of this module class.
177      * 从Yii::$app->loadedModules[‘yii\web\Application‘]数组中取得当前类的实例
178      * If the module class is not currently requested, null will be returned.
179      * This method is provided so that you access the module instance from anywhere within the module.
180      * 该方法可以在模块内的任何地方访问类的实例
181      * @return static|null the currently requested instance of this module class, or null if the module class is not requested.
182      */
183     public static function getInstance()
184     {
185         $class = get_called_class();
186         return isset(Yii::$app->loadedModules[$class]) ? Yii::$app->loadedModules[$class] : null;
187     }
188 
189     /**
190      * Sets the currently requested instance of this module class.
191      * 将当前类名和存储类的对象变量加入Yii::$app->loadedModules[‘yii\web\Application‘]数组中
192      * 这样直接通过Yii::$app->loadedModules[‘yii\web\Application‘]就可以直接调用这个类
193      * @param Module|null $instance the currently requested instance of this module class.
194      * If it is null, the instance of the calling class will be removed, if any.
195      */
196     public static function setInstance($instance)//module模块里会用到，为getInstance提供数据
197     {
198         if ($instance === null) {
199             unset(Yii::$app->loadedModules[get_called_class()]);//如果没有传入参数，说明是删除，直接unset
200         } else {
201             Yii::$app->loadedModules[get_class($instance)] = $instance;//否则将该类和类的实例存入loadedModules数组中
202         }
203     }
204 
205     /**
206      * Initializes the module.
207      * 初始化模块，取出控制器的命名空间，也可以理解为路径 注：第一次加载的时候才会执行
208      * This method is called after the module is created and initialized with property values
209      * given in configuration. The default implementation will initialize [[controllerNamespace]]
210      * if it is not set.
211      *
212      * If you override this method, please make sure you call the parent implementation.
213      */
214     public function init()
215     {
216         if ($this->controllerNamespace === null) {//判断controllerNamespace属性是否被赋值，没有赋值才执行
217             $class = get_class($this);//获取类名
218             if (($pos = strrpos($class, ‘\\‘)) !== false) {
219                 $this->controllerNamespace = substr($class, 0, $pos) . ‘\\controllers‘;//取得命名空间
220             }
221         }
222     }