Yii 框架添加新模塊完整流程：Gii 生成、配置註冊、初始化設置、視圖佈局、模型組件導入

Yii 模塊是獨立的 MVC 子應用，支持獨立控制器、模型、視圖、組件、配置。本文記錄從 Gii 生成到完整可用的標準化流程。

1. 使用 Gii 生成模塊骨架

1. 瀏覽器訪問 https://your-app/index.php?r=gii
2. 選擇 Module Generator
3. 輸入 Module ID：如 test
4. 點擊 Preview → Generate

生成目錄結構：

protected/modules/test/
├── TestModule.php              # 模塊主類 (繼承 CWebModule)
├── controllers/
│   └── DefaultController.php   # 默認控制器
├── views/
│   ├── default/
│   │   └── index.php           # 默認視圖
│   └── layouts/                # 模塊專用佈局
└── (models/, components/)      # 後續手動創建

2. 主配置註冊模塊

<?php
// protected/config/main.php
return [
    // ...
    'modules' => [
        'gii',      // 現有
        'admin',    // 現有
        'test',     // 新增：模塊 ID
    ],
];

3. 模塊初始化配置 (TestModule.php)

<?php
class TestModule extends CWebModule {
    public function init() {
        parent::init();
        
        // 設置模塊級默認值 (覆蓋應用級)
        Yii::app()->errorHandler->errorAction = 'test/default/error';
        Yii::app()->defaultController = 'test/default';
        Yii::app()->user->loginUrl = 'test/default/login';
        
        // 導入模塊專用模型和組件 (自動別名註冊)
        $this->setImport([
            'test.models.*',
            'test.components.*',
        ]);
    }
}

4. 驗證訪問

瀏覽器訪問：https://your-app/index.php?r=test 或 https://your-app/test/ (開啟 path 格式 URL 後)

將命中：TestModule -> DefaultController -> actionIndex() -> views/default/index.php

5. 模塊視圖與佈局規範

佈局嵌套示例

<?php
// 模塊佈局 views/layouts/column.php 繼承應用佈局 main.php
$this->beginContent('//layouts/main'); // 雙斜槓 = 應用根佈局
?>

    
側邊欄
    

          
    

endContent(); ?>

6. 控制器指定默認佈局與 Action

<?php
class DefaultController extends Controller {
    // 覆蓋父類屬性
    public $layout = '//layouts/main';     // 使用應用根佈局
    public $defaultAction = 'index';       // 默認 action
    
    public function actionIndex() {
        $this->render('index'); // 渲染 views/default/index.php
    }
}

7. 添加模塊專用模型與組件

1. 在 protected/modules/test/models/ 創建模型類 (如 TestForm.php)
2. 在 protected/modules/test/components/ 創建組件類 (如 TestHelper.php)
3. 已在 TestModule::init() 中 setImport，可直接使用：
   $model = new TestForm();
TestHelper::doSomething();

8. 模塊專用配置文件 (可選，大型模塊推薦)

// protected/modules/test/config/main.php
return [
    'components' => [
        'db' => [ ... ], // 模塊專用 DB (可選)
    ],
    'params' => [ ... ],
];

// TestModule.php 中加載
public function init() {
    // ...
    $config = require(__DIR__ . '/config/main.php');
    foreach ($config as $key => $value) {
        $this->$key = $value; // 或 Yii::app()->configure($config)
    }
}

完整檢查清單

• [ ] Gii 生成模塊骨架
• [ ] main.php 註冊模塊 ID
• [ ] TestModule::init() 設置默認控制器、錯誤頁、登錄跳轉、導入模型組件
• [ ] DefaultController 實現 actionIndex、指定 layout
• [ ] views/default/index.php 存在
• [ ] 瀏覽器訪問 /test 正常顯示
• [ ] 添加業務模型、組件、視圖、佈局
• [ ] (可選) 創建模塊專用配置文件

總結

Yii 模塊化機制清晰強大：**Gii 生成骨架 → 主配置註冊 → 模塊類初始化覆蓋默認值 → 遵循目錄約定開發**。關鍵點在於 `TestModule::init()` 中統一設置應用級組件行為 (errorHandler, defaultController, user.loginUrl) 並導入模塊專用類。遵循此流程，新模塊即插即用，與主應用解耦且共享核心資源。