yii2/docs/guide-zh-CN/structure-modules.md

模块

模块是独立的软件单元，由模型, 视图, 控制器和其他支持组件组成， 终端用户可以访问在应用主体中已安装的模块的控制器， 模块被当成小应用主体来看待，和应用主体不同的是， 模块不能单独部署，必须属于某个应用主体。

创建模块

模块被组织成一个称为yii\base\Module::basePath的目录， 在该目录中有子目录如controllers, models, views 分别为对应控制器，模型，视图和其他代码，和应用非常类似。 如下例子显示一个模型的目录结构：

forum/
    Module.php                   模块类文件
    controllers/                 包含控制器类文件
        DefaultController.php    default 控制器类文件
    models/                      包含模型类文件
    views/                       包含控制器视图文件和布局文件
        layouts/                 包含布局文件
        default/                 包含DefaultController控制器视图文件
            index.php            index视图文件

模块类

每个模块都有一个继承yii\base\Module的模块类， 该类文件直接放在模块的yii\base\Module::basePath目录下， 并且能被 自动加载。当一个模块被访问， 和 应用主体实例 类似会创建该模块类唯一实例，模块实例用来帮模块内代码共享数据和组件。

以下示例一个模块类大致定义：

namespace app\modules\forum;

class Module extends \yii\base\Module
{
    public function init()
    {
        parent::init();

        $this->params['foo'] = 'bar';
        // ...  其他初始化代码 ...
    }
}

如果 init() 方法包含很多初始化模块属性代码， 可将他们保存在配置 并在 init() 中使用以下代码加载：

public function init()
{
    parent::init();
    // 从config.php加载配置来初始化模块
    \Yii::configure($this, require __DIR__ . '/config.php');
}

config.php配置文件可能包含以下内容，类似 应用主体配置.

<?php
return [
    'components' => [
        // list of component configurations
    ],
    'params' => [
        // list of parameters
    ],
];

模块中的控制器

创建模块的控制器时，惯例是将控制器类放在模块类命名空间的 controllers 子命名空间中， 也意味着要将控制器类文件放在模块 yii\base\Module::basePath 目录中的 controllers 子目录中。 例如，上小节中要在 forum 模块中创建 post 控制器， 应像如下申明控制器类：

namespace app\modules\forum\controllers;

use yii\web\Controller;

class PostController extends Controller
{
    // ...
}

可配置yii\base\Module::controllerNamespace属性来自定义控制器类的命名空间， 如果一些控制器不再该命名空间下，可配置yii\base\Module::controllerMap属性让它们能被访问， 这类似于 应用主体配置 所做的。

模块中的视图

视图应放在模块的yii\base\Module::basePath对应目录下的 views 目录， 对于模块中控制器对应的视图文件应放在 views/ControllerID 目录下， 其中ControllerID对应 控制器 ID. For example, if 例如，假定控制器类为PostController， 目录对应模块yii\base\Module::basePath目录下的 views/post 目录。

模块可指定 布局，它用在模块的控制器视图渲染。 布局文件默认放在 views/layouts 目录下， 可配置yii\base\Module::layout属性指定布局名， 如果没有配置 layout 属性名，默认会使用应用的布局。

模块中的控制台命令

您的模块也可以声明命令，这将通过 控制台 模式可用。

当 Yii 在控制台模式下执行并将其指向命令的命名空间时。想要在命令行中查看你的命令， 你需要更改 yii\base\Module::controllerNamespace 属性。

一种实现方法是在模块的 init() 方法中测试Yii应用程序的实例类型：

public function init()
{
    parent::init();
    if (Yii::$app instanceof \yii\console\Application) {
        $this->controllerNamespace = 'app\modules\forum\commands';
    }
}

然后您的命令将从命令行使用以下路由：

yii <module_id>/<command>/<sub_command>

使用模块

要在应用中使用模块，只需要将模块加入到应用主体配置的yii\base\Application::modules属性的列表中， 如下代码的应用主体配置 使用 forum 模块:

[
    'modules' => [
        'forum' => [
            'class' => 'app\modules\forum\Module',
            // ... 模块其他配置 ...
        ],
    ],
]

yii\base\Application::modules 属性使用模块配置数组， 每个数组键为模块 ID，它标识该应用中唯一的模块， 数组的值为用来创建模块的 配置。

路由

和访问应用的控制器类似，路由 也用在模块中控制器的寻址， 模块中控制器的路由必须以模块ID开始，接下来为控制器ID和操作ID。 例如，假定应用使用一个名为 forum 模块， 路由forum/post/index 代表模块中 post 控制器的 index 操作， 如果路由只包含模块ID，默认为 default 的 yii\base\Module::defaultRoute 属性来决定使用哪个控制器/操作， 也就是说路由 forum 可能代表 forum 模块的 default 控制器。

The URL manager rules for the modules should be added before yii\web\UrlManager::parseRequest() is fired. That means doing it in module's init() won't work because module will be initialized when routes were already processed. Thus, the rules should be added at bootstrap stage. It is a also a good practice to wrap module's URL rules with \yii\web\GroupUrlRule.

In case a module is used to version API, its URL rules should be added directly in urlManager section of the application config.

访问模块

在模块中，可能经常需要获取模块类的实例来访问模块ID，模块参数，模块组件等， 可以使用如下语句来获取：

$module = MyModuleClass::getInstance();

其中 MyModuleClass 对应你想要的模块类， getInstance() 方法返回当前请求的模块类实例， 如果模块没有被请求，该方法会返回空，注意不需要手动创建一个模块类， 因为手动创建的和Yii处理请求时自动创建的不同。

Info: 当开发模块时，你不能假定模块使用固定的ID， 因为在应用或其他没模块中，模块可能会对应到任意的ID， 为了获取模块ID，应使用上述代码获取模块实例， 然后通过$module->id获取模块ID。

也可以使用如下方式访问模块实例:

// 获取ID为 "forum" 的模块
$module = \Yii::$app->getModule('forum');

// 获取处理当前请求控制器所属的模块
$module = \Yii::$app->controller->module;

第一种方式仅在你知道模块ID的情况下有效， 第二种方式在你知道处理请求的控制器下使用。

一旦获取到模块实例，可访问注册到模块的参数和组件，例如：

$maxPostCount = $module->params['maxPostCount'];

引导启动模块

有些模块在每个请求下都有运行， yii\debug\Module 模块就是这种， 为此将这种模块加入到应用主体的 yii\base\Application::bootstrap 属性中。

例如，如下示例的应用主体配置会确保debug模块每次都被加载：

[
    'bootstrap' => [
        'debug',
    ],

    'modules' => [
        'debug' => 'yii\debug\Module',
    ],
]

模块嵌套

模块可无限级嵌套，也就是说，模块可以包含另一个包含模块的模块，我们称前者为父模块，后者为子模块， 子模块必须在父模块的yii\base\Module::modules属性中申明， 例如：

namespace app\modules\forum;

class Module extends \yii\base\Module
{
    public function init()
    {
        parent::init();

        $this->modules = [
            'admin' => [
                // 此处应考虑使用一个更短的命名空间
                'class' => 'app\modules\forum\modules\admin\Module',
            ],
        ];
    }
}

在嵌套模块中的控制器，它的路由应包含它所有祖先模块的ID， 例如forum/admin/dashboard/index 代表 在模块forum中子模块admin中dashboard控制器的index操作。

Info: yii\base\Module::getModule() 方法只返回子模块的直属的 父模块。 yii\base\Application::loadedModules 保存了已加所有载模块的属性, 包括两者的子模块和 嵌套模块，并用他们的类名进行索引。

Accessing components from within modules

Since version 2.0.13 modules support tree traversal. This allows module developers to reference (application) components via the service locator that is their module. This means that it is preferable to use $module->get('db') over Yii::$app->get('db'). The user of a module is able to specify a specific component to be used for the module in case a different component (configuration) is required.

For example consider partial this application configuration:

'components' => [
    'db' => [
        'tablePrefix' => 'main_',
        'class' => Connection::class,
        'enableQueryCache' => false
    ],
],
'modules' => [
    'mymodule' => [
        'components' => [
            'db' => [
                'tablePrefix' => 'module_',
                'class' => Connection::class
            ],
        ],
    ],
],

The application database tables will be prefixed with main_, while all module tables will be prefixed with module_. Note that configuration above is not merged; the modules' component for example will have the query cache enabled since that is the default value.

最佳实践

模块在大型项目中常备使用，这些项目的特性可分组， 每个组包含一些强相关的特性， 每个特性组可以做成一个模块由特定的开发人员和开发组来开发和维护。

在特性组上，使用模块也是重用代码的好方式， 一些常用特性，如用户管理，评论管理，可以开发成模块， 这样在相关项目中非常容易被重用。