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 yiibase;
  9 
 10 use Yii;
 11 use yiidiServiceLocator;
 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 <qiang.xue@gmail.com>
 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' => 'appcontrollersUserController',
 88      *   'article' => [
 89      *      'class' => 'appcontrollersPostController',
 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 "fooar", then the default
103      * controller namespace would be "fooarcontrollers".
104      * 如果没有设置，默认为当前模块的命名空间加上 `controllers`构成的命名空间
105 119  * 如当前模块的命名空间为"fooar"，控制器的默认命名空间为"fooarcontrollers"
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     }