yii2框架随笔31

今天来看vendor/yiisoft/yii2/base/Module. php

<?php

/**
 * @link http://www.yiiframework.com/
 * @copyright Copyright (c) 2008 Yii Software LLC
 * @license http://www.yiiframework.com/license/
 */

namespace yiibase;

use Yii;
use yiidiServiceLocator;

/**
 * Module is the base class for module and application classes.
 * Module是模块和应用类的基类
 *
 * A module represents a sub-application which contains MVC elements by itself, such as
 * models, views, controllers, etc.
 * 模块代表一个由模型、视图、控制器等组成的子应用
 *
 * A module may consist of [[modules|sub-modules]].
 * 模块内也可以包含模块或子模块
 *
 * [[components|Components]] may be registered with the module so that they are globally
 * accessible within the module.
 * 组件可以注册到模块，以便在模块内全局访问
 *
 * @property array $aliases List of path aliases to be defined. The array keys are alias names (must start
 * with '@') and the array values are the corresponding paths or aliases. See [[setAliases()]] for an example.
 * This property is write-only.
 * @property array $aliases 别名数组  只读
 * @property string $basePath The root directory of the module.
 * @property string $basePath  模块的根路径
 * @property string $controllerPath The directory that contains the controller classes. This property is
 * read-only.
 * @property string $controllerPath 控制的路径数组 只读
 * @property string $layoutPath The root directory of layout files. Defaults to "[[viewPath]]/layouts".
 * @property string $layoutPath 模板路径数组 只读
 * @property array $modules The modules (indexed by their IDs).
 * @property array $modules 模块数组
 * @property string $uniqueId The unique ID of the module. This property is read-only.
 * @property string $uniqueId 模块的唯一ID 只读
 * @property string $viewPath The root directory of view files. Defaults to "[[basePath]]/views".
 * @property string $viewPath 模块下的视图文件路径
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @since 2.0
 */
class Module extends ServiceLocator
{
    /**
     * @event ActionEvent an event raised before executing a controller action.
     * @event ActionEvent Action事件，在执行控制的的action方法时触发
     * You may set [[ActionEvent::isValid]] to be false to cancel the action execution.
     */
    const EVENT_BEFORE_ACTION = 'beforeAction';
    /**
     * @event ActionEvent an event raised after executing a controller action.
     * @event ActionEvent Action事件，在执行控制的的action方法后触发
     */
    const EVENT_AFTER_ACTION = 'afterAction';

    /**
     * @var array custom module parameters (name => value).
     * @var array 自定义模块参数
     */
    public $params = [];
    /**
     * @var string an ID that uniquely identifies this module among other modules which have the same [[module|parent]].
     * @var string 模块的唯一ID，用于区分同一父模块下的模块
     */
    public $id;
    /**
     * @var Module the parent module of this module. Null if this module does not have a parent.
     * @var 当前模块的父模块
     */
    public $module;
    /**
     * @var string|boolean the layout that should be applied for views within this module. This refers to a view name
     * relative to [[layoutPath]]. If this is not set, it means the layout value of the [[module|parent module]]
     * will be taken. If this is false, layout will be disabled within this module.
     * @var string|boolean 布局文件
     */
    public $layout;
    /**
     * @var array mapping from controller ID to controller configurations.
     * @var array 控制器ID到控制器配置的映射
     * Each name-value pair specifies the configuration of a single controller.
     * A controller configuration can be either a string or an array.
     * If the former, the string should be the fully qualified class name of the controller.
     * If the latter, the array must contain a 'class' element which specifies
     * the controller's fully qualified class name, and the rest of the name-value pairs
     * in the array are used to initialize the corresponding controller properties. For example,
     * 每一个键值对指定一个单独的控制器，控制器配置可以是一个字符串或者数组，如果是前者，该字符串是指定控制的的全路径（即带命名空间的）
     * 如果是后者，则数组中包含一个‘class’元素，该元素指定控制器的全路径，其余的参数用于初始化对应的属性，例子如下：
     *
     * ```php
     * [
     *   'account' => 'appcontrollersUserController',//字符串形式，指定了accout控制器的路径
     *   'article' => [
     *      'class' => 'appcontrollersPostController',//指定article控制器的路径
     *      'pageTitle' => 'something new',//提供了pageTitle参数
     *   ],
     * ]
     * ```
     */
    public $controllerMap = [];
    /**
     * @var string the namespace that controller classes are in.
     * @var string 控制器的命名空间
     * This namespace will be used to load controller classes by prepending it to the controller
     * class name.
     * 该命名空间用于加在控制器类的前面加载控制器类
     *
     * If not set, it will use the `controllers` sub-namespace under the namespace of this module.
     * For example, if the namespace of this module is "fooar", then the default
     * controller namespace would be "fooarcontrollers".
     * 如果没有给定，默认为当前模块的命名空间加上 `controllers`构成的子命名空间
     * 如当前模块的命名空间为"fooar"，那么控制器的默认命名空间为"fooarcontrollers"
     *
     * See also the [guide section on autoloading](guide:concept-autoloading) to learn more about
     * defining namespaces and how classes are loaded.
     */
    public $controllerNamespace;
    /**
     * @var string the default route of this module. Defaults to 'default'.
     * @var string 当前模块的默认路由 默认为'default'
     * The route may consist of child module ID, controller ID, and/or action ID.
     * route 可能包含子模块ID，控制器ID，和/或 action ID，如果action ID未给定，则会调用[Controller::defaultAction]指定的action
     * For example, `help`, `post/create`, `admin/post/create`.
     * If action ID is not given, it will take the default value as specified in
     * [[Controller::defaultAction]].
     */
    public $defaultRoute = 'default';

    /**
     * @var string the root directory of the module.
     * @var string 当前模块的根路径
     */
    private $_basePath;
    /**
     * @var string the root directory that contains view files for this module
     * @var string 当前模块下视图文件的路径数组
     */
    private $_viewPath;
    /**
     * @var string the root directory that contains layout view files for this module.
     * @var string 当前模块下的布局文件路径数组
     */
    private $_layoutPath;
    /**
     * @var array child modules of this module
     * @var array 当前模块的子模块数组
     */
    private $_modules = [];


    /**
     * Constructor.
     * 构造函数
     * @param string $id the ID of this module
     * @param string $id 当前模块的ID
     * @param Module $parent the parent module (if any)
     * @param Module $parent 当前模块的父模块（如果有的话）
     * @param array $config name-value pairs that will be used to initialize the object properties
     * @param array $config 配置文件|数组
     */
    public function __construct($id, $parent = null, $config = [])
    {
        $this->id = $id;//给当前模块赋值唯一ID
        $this->module = $parent;//给module属性（即当前模块的父模块）赋值
        parent::__construct($config);//将配置文件赋值到Object的属性中，因为Object是所有类的基类，理论可以整个项目中访问
    }

    /**
     * Returns the currently requested instance of this module class.
     * 从Yii::$app->loadedModules['yiiwebApplication']数组中取得当前类的实例
     * If the module class is not currently requested, null will be returned.
     * This method is provided so that you access the module instance from anywhere within the module.
     * 该方法可以在模块内的任何地方访问类的实例
     * @return static|null the currently requested instance of this module class, or null if the module class is not requested.
     */
    public static function getInstance()
    {
        $class = get_called_class();
        return isset(Yii::$app->loadedModules[$class]) ? Yii::$app->loadedModules[$class] : null;
    }

    /**
     * Sets the currently requested instance of this module class.
     * 将当前类名和存储类的对象变量加入Yii::$app->loadedModules['yiiwebApplication']数组中
     * 这样直接通过Yii::$app->loadedModules['yiiwebApplication']就可以直接调用这个类
     * @param Module|null $instance the currently requested instance of this module class.
     * If it is null, the instance of the calling class will be removed, if any.
     */
    public static function setInstance($instance)//module模块里会用到，为getInstance提供数据
    {
        if ($instance === null) {
            unset(Yii::$app->loadedModules[get_called_class()]);//如果没有传入参数，说明是删除，直接unset
        } else {
            Yii::$app->loadedModules[get_class($instance)] = $instance;//否则将该类和类的实例存入loadedModules数组中
        }
    }

    /**
     * Initializes the module.
     * 初始化模块，取出控制器的命名空间，也可以理解为路径 注：第一次加载的时候才会执行
     * This method is called after the module is created and initialized with property values
     * given in configuration. The default implementation will initialize [[controllerNamespace]]
     * if it is not set.
     *
     * If you override this method, please make sure you call the parent implementation.
     */
    public function init()
    {
        if ($this->controllerNamespace === null) {//判断controllerNamespace属性是否被赋值，没有赋值才执行
            $class = get_class($this);//获取类名
            if (($pos = strrpos($class, '\')) !== false) {
                $this->controllerNamespace = substr($class, 0, $pos) . '\controllers';//取得命名空间
            }
        }
    }

    /**
     * 新建一个控制器实例基于给定的路线.
    */
    public function createController($route)
    {
        if ($route === '') {
            $route = $this->defaultRoute;
        }

        // double slashes or leading/ending slashes may cause substr problem
        // 如果有双斜线或者结束的斜线，可能会引起问题
        $route = trim($route, '/');
        if (strpos($route, '//') !== false) {
            return false;
        }

        if (strpos($route, '/') !== false) {
            // 如果存在斜线，就根据斜线分割route，并限制最多分割成两个
            list ($id, $route) = explode('/', $route, 2);
        } else {
            // 不存在，就直接赋值给$id
            $id = $route;
            $route = '';
        }

        // module and controller map take precedence
        if (isset($this->controllerMap[$id])) {
            // 如果controllerMap中存在相应的$id，就使用Yii::createObject去创建该controller的实例
            $controller = Yii::createObject($this->controllerMap[$id], [$id, $this]);
            return [$controller, $route];
        }
        // 根据id获取module
        $module = $this->getModule($id);
        if ($module !== null) {
            // 获取到module，就递归调用相应module的createController去创建controller的实例
            return $module->createController($route);
        }

        // 如果取到了module，就需要继续去取controller的ID
        // 再次根据斜线分割
        if (($pos = strrpos($route, '/')) !== false) {
            // 如果有斜线，就将module的ID和后面截取出的内容一起拼成ID
            $id .= '/' . substr($route, 0, $pos);
            // 剩余的赋给route
            $route = substr($route, $pos + 1);
        }

        // 然后根据ID去创建controller的实例
        $controller = $this->createControllerByID($id);
        // 未创建成功，并且route不为空
        if ($controller === null && $route !== '') {
            // 将route拼接到ID中，再次去创建controller出的实例
            $controller = $this->createControllerByID($id . '/' . $route);
            $route = '';
        }

        return $controller === null ? false : [$controller, $route];
    }

    /**
     * 创建一个控制器基于给定控制器ID.
     *
     * The controller ID is relative to this module. The controller class
     * should be namespaced under [[controllerNamespace]].
     *
     * Note that this method does not check [[modules]] or [[controllerMap]].
     *
     * @param string $id the controller ID
     * @return Controller the newly created controller instance, or null if the controller ID is invalid.
     * @throws InvalidConfigException if the controller class and its file name do not match.
     * This exception is only thrown when in debug mode.
     */
    public function createControllerByID($id)
    {
        // $id是controller的ID，但它前面可能带有module的ID，而且可能是多层module ID
        // 取到最右边的斜线位置，可以分离出controller的名字
        $pos = strrpos($id, '/');
        if ($pos === false) {
            // 没有斜线，$id就是controller的名字
            $prefix = '';
            $className = $id;
        } else {
            // 有斜线，斜线前的是module的ID，斜线后是controller的名字
            $prefix = substr($id, 0, $pos + 1);
            $className = substr($id, $pos + 1);
        }

        if (!preg_match('%^[a-z][a-z0-9\-_]*$%', $className)) {
            // 如果controller的名字不符合命名的规范，就返回null
            // 以小写字母开头，可以包含数字/小写字母/右斜线/中划线/下划线
            return null;
        }
        if ($prefix !== '' && !preg_match('%^[a-z0-9_/]+$%i', $prefix)) {
            // 如果module的ID不符合module的命名规范，就返回null
            // 可以包含数字/小写字母/左斜线/下划线
            return null;
        }

        // 先将-替换为空格，再将每个单词的首字母大写，再将空格替换为空字符串，最后拼接上'Controller'，就拿到了类名（不带namespace）
        $className = str_replace(' ', '', ucwords(str_replace('-', ' ', $className))) . 'Controller';
        // 根据application和module中定义的controllerNamespace，拼出controller的类名，含namespace
        $className = ltrim($this->controllerNamespace . '\' . str_replace('/', '\', $prefix)  . $className, '\');
        if (strpos($className, '-') !== false || !class_exists($className)) {
            // 如果存在中划线或者类不存在，即返回null
            return null;
        }

        // is_subclass_of — 如果此对象是该类的子类，则返回 TRUE
        // 判断是不是'yiiaseController'的子类，是的话，就创建相应类的实例
        if (is_subclass_of($className, 'yiiaseController')) {
            return Yii::createObject($className, [$id, $this]);
        } elseif (YII_DEBUG) {
            throw new InvalidConfigException("Controller class must extend from \yii\base\Controller.");
        } else {
            return null;
        }
    }

    /**
     * This method is invoked right before an action within this module is executed.
     * 这个方法被调用之前执行一个动作在这个模块
     * If you override this method, your code should look like the following:
     *如果您重写此方法，您的代码应该看起来如下：
     * ```php
     * public function beforeAction($action)
     * {
     *     if (parent::beforeAction($action)) {
     *         // your custom code here
     *         return true;  // or false if needed
     *     } else {
     *         return false;
     *     }
     * }
     * ```
     *
     * @param Action $action the action to be executed.
     * @return boolean whether the action should continue to be executed.
     */
    public function beforeAction($action)
    {
        $event = new ActionEvent($action);
        //该方法将触发[[EVENT_BEFORE_ACTION]]事件
        $this->trigger(self::EVENT_BEFORE_ACTION, $event);
        return $event->isValid;
    }

    /**
     * This method is invoked right after an action within this module is executed.
     *调用该方法之后执行一个动作在这个模块。
     * The method will trigger the [[EVENT_AFTER_ACTION]] event. The return value of the method.
     * ```
     *
     * @param Action $action the action just executed.
     * @param mixed $result the action return result.
     * @return mixed the processed action result.
     */
    public function afterAction($action, $result)
    {   //初始化
        $event = new ActionEvent($action);
        //该事件触发后赋值给$result
        $event->result = $result;
        //该方法将触发[[EVENT_BEFORE_ACTION]]事件
        $this->trigger(self::EVENT_AFTER_ACTION, $event);
        return $event->result;
    }
}