Yii Framework 模組化開發完整指南：結構、Gii 生成、Layout、Assets 與配置

為什麼需要模組？

專案增長時，所有 Controller 集中在 controllers/、Model 在 models/ 會導致維護困難。模組將相關功能封裝為獨立單元 (含獨立 MVC、元件、視圖)，實現高內聚、低耦合，支援無限巢狀嵌套。

模組目錄結構

protected/
├── modules/
│   └── admin/                 # 模組 ID = admin
│       ├── AdminModule.php    # 模組類別 (繼承 CWebModule)
│       ├── components/        # 模組專用元件
│       ├── controllers/       # 控制器
│       │   └── DefaultController.php
│       ├── models/            # 模型
│       ├── views/             # 視圖
│       │   ├── default/       # 對應 DefaultController
│       │   │   └── index.php
│       │   └── layouts/       # 佈局
│       │       └── main.php
│       └── messages/          # 國際化訊息

使用 Gii 快速生成模組

1. 啟用 Gii：修改 protected/config/main.php

   'modules'=>array(
       'gii'=>array(
           'class'=>'system.gii.GiiModule',
           'password'=>'your_password',
           'ipFilters'=>array('127.0.0.1','::1'),
       ),
   ),

2. 訪問 https://your-app/index.php?r=gii
3. 選擇「Module Generator」→ Module ID 輸入 admin → Preview → Generate
4. 確保 protected/ 可寫入

註冊模組

<?php
// protected/config/main.php
return array(
    'modules'=>array(
        'gii'=>array(...),
        'admin', // 簡單註冊，使用預設配置
        // 或帶參數註冊
        // 'admin'=>array('web_url'=>'www.example.com'),
    ),
);

訪問模組

URL 格式：https://your-app/index.php?r=admin/default/index

• admin = 模組 ID
• default = Controller ID (預設)
• index = Action ID (預設)

模組專用 Layout

預設模組使用主應用 protected/views/layouts/main.php。若需獨立佈局：

<?php
// protected/modules/admin/controllers/DefaultController.php
class DefaultController extends Controller {
    public $layout = 'application.modules.admin.views.layouts.main';
    // ...
}

將主佈局複製到 protected/modules/admin/views/layouts/main.php 並修改。

模組 Assets 管理 (CSS/JS/圖片)

為避免檔案衝突、支援模組複用，使用 CAssetManager 發布私有資源到公開 /assets 目錄。

1. 放置資源

protected/modules/admin/assets/
├── css/screen.css
├── js/admin.js
└── images/logo.png

2. 模組類別掛載 Assets

<?php
// protected/modules/admin/AdminModule.php
class AdminModule extends CWebModule {
    private $_assetsUrl;

    public function getAssetsUrl(): string {
        if ($this->_assetsUrl === null) {
            $this->_assetsUrl = Yii::app()->getAssetManager()->publish(
                Yii::getPathOfAlias('application.modules.admin.assets')
            );
        }
        return $this->_assetsUrl;
    }

    public function setAssetsUrl(string $value): void {
        $this->_assetsUrl = $value;
    }
}

3. 視圖中引用

<!-- protected/modules/admin/views/layouts/main.php -->
<link rel="stylesheet" type="text/css" href="<?php echo $this->module->assetsUrl; ?>/css/screen.css" />
<script src="<?php echo $this->module->assetsUrl; ?>/js/admin.js"></script>

4. 複用優勢

整個 admin/ 目錄複製到新專案 protected/modules/ 下，註冊即用，資源路徑自動發布無衝突。

模組參數配置與存取

<?php
// main.php
'modules'=>array(
    'admin'=>array(
        'web_url'=>'www.example.com',
        'page_size'=>20,
    ),
),

Controller 中讀取

<?php
$webUrl = Yii::app()->controller->module->web_url;
$pageSize = Yii::app()->controller->module->page_size;
// 或
$module = Yii::app()->getModule('admin');
$webUrl = $module->web_url;

子模組 (巢狀模組)

模組可包含子模組，理論無限嵌套：

modules/
└── admin/
    └── modules/
        └── report/  # 訪問: r=admin/report/default/index

子模組類別繼承 CWebModule，父模組 AdminModule 需在 init() 中設定：

public function init() {
    $this->setModules(array(
        'report'=>array('class'=>'application.modules.admin.modules.report.ReportModule'),
    ));
    parent::init();
}

最佳實踐總結

• 單一職責：每個模組對應一個業務域 (後台、API、前台、報表)。
• 介面隔離：模組間通過 Service/元件介面溝通，避免直接引用對方 Model/Controller。
• 共用代碼下沉：通用 Model/Component/Widget 放在主應用 protected/components、protected/models。
• Assets 必發布：不要硬編碼資源路徑，務必使用 $this->module->assetsUrl。
• 配置外部化：模組參數在主配置注入，模組內部不硬編碼環境差異。