# 模块
模块是独立的软件单元，由[模型](http://www.yiichina.com/doc/guide/2.0/structure-models), [视图](http://www.yiichina.com/doc/guide/2.0/structure-views), [控制器](http://www.yiichina.com/doc/guide/2.0/structure-controllers)和其他支持组件组成， 终端用户可以访问在[应用主体](http://www.yiichina.com/doc/guide/2.0/structure-applications)中已安装的模块的控制器， 模块被当成小应用主体来看待，和[应用主体](http://www.yiichina.com/doc/guide/2.0/structure-applications)不同的是， 模块不能单独部署，必须属于某个应用主体。
## 创建模块
模块被组织成一个称为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目录下， 并且能被 [自动加载](http://www.yiichina.com/doc/guide/2.0/concept-autoloading)。当一个模块被访问，和 [应用主体实例](http://www.yiichina.com/doc/guide/2.0/structure-applications) 类似会创建该模块类唯一实例，模块实例用来帮模块内代码共享数据和组件。
以下示例一个模块类大致定义：
~~~
namespace app\modules\forum;
class Module extends \yii\base\Module
{
public function init()
{
parent::init();
$this->params['foo'] = 'bar';
// ... 其他初始化代码 ...
}
}
~~~
如果 `init()` 方法包含很多初始化模块属性代码， 可将他们保存在[配置](http://www.yiichina.com/doc/guide/2.0/concept-configurations) 并在`init()`中使用以下代码加载：
~~~
public function init()
{
parent::init();
// 从config.php加载配置来初始化模块
\Yii::configure($this, require(__DIR__ . '/config.php'));
}
~~~
`config.php`配置文件可能包含以下内容，类似[应用主体配置](http://www.yiichina.com/doc/guide/2.0/structure-applications#application-configurations).
~~~
<?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属性让它们能被访问， 这类似于 [应用主体配置](http://www.yiichina.com/doc/guide/2.0/structure-applications#controller-map) 所做的。
### 模块中的视图
视图应放在模块的yii\base\Module::basePath对应目录下的 `views` 目录， 对于模块中控制器对应的视图文件应放在`views/ControllerID` 目录下， 其中`ControllerID`对应 [控制器 ID](http://www.yiichina.com/doc/guide/2.0/structure-controllers#routes). For example, if 例如，假定控制器类为`PostController`，目录对应模块yii\base\Module::basePath目录下的 `views/post` 目录。
模块可指定 [布局](http://www.yiichina.com/doc/guide/2.0/structure-views#layouts)，它用在模块的控制器视图渲染。 布局文件默认放在 `views/layouts` 目录下，可配置yii\base\Module::layout属性指定布局名， 如果没有配置 `layout` 属性名，默认会使用应用的布局。
## 使用模块
要在应用中使用模块，只需要将模块加入到应用主体配置的yii\base\Application::modules属性的列表中， 如下代码的[应用主体配置](http://www.yiichina.com/doc/guide/2.0/structure-applications#application-configurations) 使用 `forum` 模块:
~~~
[
'modules' => [
'forum' => [
'class' => 'app\modules\forum\Module',
// ... 模块其他配置 ...
],
],
]
~~~
yii\base\Application::modules 属性使用模块配置数组，每个数组键为*模块 ID*， 它标识该应用中唯一的模块，数组的值为用来创建模块的 [配置](http://www.yiichina.com/doc/guide/2.0/concept-configurations)。
### 路由
和访问应用的控制器类似，[路由](http://www.yiichina.com/doc/guide/2.0/structure-controllers#routes) 也用在模块中控制器的寻址， 模块中控制器的路由必须以模块ID开始，接下来为控制器ID和操作ID。 例如，假定应用使用一个名为 `forum` 模块，路由`forum/post/index` 代表模块中 `post` 控制器的 `index` 操作， 如果路由只包含模块ID，默认为 `default` 的yii\base\Module::defaultRoute 属性来决定使用哪个控制器/操作， 也就是说路由 `forum` 可能代表 `forum`模块的 `default` 控制器。
### 访问模块
在模块中，可能经常需要获取[模块类](http://www.yiichina.com/doc/guide/2.0/structure-modules#module-classes)的实例来访问模块ID，模块参数，模块组件等， 可以使用如下语句来获取：
~~~
$module = MyModuleClass::getInstance();
~~~
其中 `MyModuleClass` 对应你想要的模块类，`getInstance()` 方法返回当前请求的模块类实例， 如果模块没有被请求，该方法会返回空，注意不需要手动创建一个模块类，因为手动创建的和Yii处理请求时自动创建的不同。
> 补充: 当开发模块时，你不能假定模块使用固定的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`操作。
## 最佳实践
模块在大型项目中常备使用，这些项目的特性可分组，每个组包含一些强相关的特性， 每个特性组可以做成一个模块由特定的开发人员和开发组来开发和维护。
在特性组上，使用模块也是重用代码的好方式，一些常用特性，如用户管理，评论管理，可以开发成模块， 这样在相关项目中非常容易被重用。
- 介绍（Introduction）
- 关于 Yii（About Yii）
- 从 Yii 1.1 升级（Upgrading from Version 1.1）
- 入门（Getting Started）
- 安装 Yii（Installing Yii）
- 运行应用（Running Applications）
- 第一次问候（Saying Hello）
- 使用 Forms（Working with Forms）
- 玩转 Databases（Working with Databases）
- 用 Gii 生成代码（Generating Code with Gii）
- 更上一层楼（Looking Ahead）
- 应用结构（Application Structure）
- 结构概述（Overview）
- 入口脚本（Entry Scripts）
- 应用（Applications）
- 应用组件（Application Components）
- 控制器（Controllers）
- 模型（Models）
- 视图（Views）
- 模块（Modules）
- 过滤器（Filters）
- 小部件（Widgets）
- 前端资源（Assets）
- 扩展（Extensions）
- 请求处理（Handling Requests）
- 运行概述（Overview）
- 引导（Bootstrapping）
- 路由引导与创建 URL（Routing and URL Creation）
- 请求（Requests）
- 响应（Responses）
- Sessions and Cookies
- 错误处理（Handling Errors）
- 日志（Logging）
- 关键概念（Key Concepts）
- 组件（Components）
- 属性（Properties）
- 事件（Events）
- 行为（Behaviors）
- 配置（Configurations）
- 别名（Aliases）
- 类自动加载（Class Autoloading）
- 服务定位器（Service Locator）
- 依赖注入容器（Dependency Injection Container）
- 配合数据库工作（Working with Databases）
- 数据库访问（Data Access Objects）: 数据库连接、基本查询、事务和模式操作
- 查询生成器（Query Builder）: 使用简单抽象层查询数据库
- 活动记录（Active Record）: 活动记录对象关系映射（ORM），检索和操作记录、定义关联关系
- 数据库迁移（Migrations）: 在团体开发中对你的数据库使用版本控制
- Sphinx
- Redis
- MongoDB
- ElasticSearch
- 接收用户数据（Getting Data from Users）
- 创建表单（Creating Forms）
- 输入验证（Validating Input）
- 文件上传（Uploading Files）
- 收集列表输入（Collecting Tabular Input）
- 多模型同时输入（Getting Data for Multiple Models）
- 显示数据（Displaying Data）
- 格式化输出数据（Data Formatting）
- 分页（Pagination）
- 排序（Sorting）
- 数据提供器（Data Providers）
- 数据小部件（Data Widgets）
- 操作客户端脚本（Working with Client Scripts）
- 主题（Theming）
- 安全（Security）
- 认证（Authentication）
- 授权（Authorization）
- 处理密码（Working with Passwords）
- 客户端认证（Auth Clients）
- 安全领域的最佳实践（Best Practices）
- 缓存（Caching）
- 概述（Overview）
- 数据缓存（Data Caching）
- 片段缓存（Fragment Caching）
- 分页缓存（Page Caching）
- HTTP 缓存（HTTP Caching）
- RESTful Web 服务
- 快速入门（Quick Start）
- 资源（Resources）
- 控制器（Controllers）
- 路由（Routing）
- 格式化响应（Response Formatting）
- 授权验证（Authentication）
- 速率限制（Rate Limiting）
- 版本化（Versioning）
- 错误处理（Error Handling）
- 开发工具（Development Tools）
- 调试工具栏和调试器（Debug Toolbar and Debugger）
- 使用 Gii 生成代码（Generating Code using Gii）
- TBD 生成 API 文档（Generating API Documentation）
- 测试（Testing）
- 概述（Overview）
- 搭建测试环境（Testing environment setup）
- 单元测试（Unit Tests）
- 功能测试（Functional Tests）
- 验收测试（Acceptance Tests）
- 测试夹具（Fixtures）
- 高级专题（Special Topics）
- 高级应用模版（Advanced Project Template）
- 从头构建自定义模版（Building Application from Scratch）
- 控制台命令（Console Commands）
- 核心验证器（Core Validators）
- 国际化（Internationalization）
- 收发邮件（Mailing）
- 性能优化（Performance Tuning）
- 共享主机环境（Shared Hosting Environment）
- 模板引擎（Template Engines）
- 集成第三方代码（Working with Third-Party Code）
- 小部件（Widgets）
- Bootstrap 小部件（Bootstrap Widgets）
- jQuery UI 小部件（jQuery UI Widgets）
- 助手类（Helpers）
- 助手一览（Overview）
- Array 助手（ArrayHelper）
- Html 助手（Html）
- Url 助手（Url）