Yii Controller 控制器全景解析：路由、操作、參數綁定、生命周期與最佳實踐

控制器在 MVC 中的定位

繼承 yii\base\Controller（Web 應用用 yii\web\Controller，Console 用 yii\console\Controller），負責：接收請求 → 解析路由 → 實例化操作 → 執行前置過濾 → 綁定參數執行操作 → 執行後置過濾 → 返回響應。

路由解析規則

請求 ?r=module/controller/action 或 PATH_INFO /module/controller/action：

• 模組 ID（可選）：應用下唯一標識模組
• 控制器 ID：小寫、中劃線分隔單詞，如 post-comment → PostCommentController
• 操作 ID：小寫、中劃線，如 hello-world → actionHelloWorld()

命名空間映射：yii\base\Application::controllerNamespace (預設 app\controllers) + 子目錄對應模組/子命名空間。

操作類型：內聯 vs 獨立

獨立操作示例

message;
  }
}

// Controller 註冊
public function actions() {
  return [
    'hello' => [
      'class' => 'app\components\HelloWorldAction',
      'message' => 'Welcome!',
    ],
    'error' => 'yii\web\ErrorAction', // 內建錯誤頁
    'view' => [
      'class' => 'yii\web\ViewAction',
      'viewPrefix' => '',
    ],
  ];
}

操作參數自動綁定（核心便利特性）

public function actionView($id, $slug = null, array $tags = []) {
  // GET /post/view?id=123&slug=hello&tags[]=php&tags[]=yii
  // $id=123, $slug='hello', $tags=['php','yii']
  // 缺少必填參數 → 自動拋出 BadRequestHttpException (400)
  // 類型聲明 array 自動將標量轉為單元素陣列
}

支援：標量、陣列（array 型別聲明）、預設值、必填檢查。Console 應用對應命令行參數綁定。

控制器生命周期

1. __construct() → init()
2. 建立操作對象（內聯/獨立/預設）
3. 依序調用：Application::beforeAction() → Module::beforeAction() → Controller::beforeAction()
4. 任一返回 false → 取消執行，跳過後續 beforeAction 並直接進入 afterAction
5. 執行操作 run() / actionXyz()（含參數綁定）
6. 依序調用：Controller::afterAction() → Module::afterAction() → Application::afterAction()
7. 觸發 beforeAction/afterAction 事件（可掛載監聽器）
8. 應用收集結果封裝響應

結果返回類型

• 字串/陣列/物件 → 賦值給 Response::data，最終序列化輸出
• Response 物件 → 直接作為響應（如 redirect() 返回 RedirectResponse）
• Console 應用返回整數 → Response::exitStatus

最佳實踐清單

1. 薄控制器：業務邏輯下沉 Service/Repository/Model，Controller 僅做請求協調
2. 表單驗證用 Model：Model::load() + validate()，而非 Controller 手寫驗證
3. 視圖渲染：return $this->render('view', ['model' => $model])，避免在 Controller 拼 HTML
4. 錯誤處理：拋出 NotFoundHttpException、ForbiddenHttpException 等內建異常，由 ErrorHandler 統一渲染
5. 行為注入：跨控制器共享邏輯（如權限檢查、日誌、速率限制）用 behaviors() 掛載
6. 預設操作：public $defaultAction = 'index'; 讓 ?r=controller 直接進入列表頁

常見錯誤

Yii Controller 以「約定優於配置」實現路由映射、參數綁定、生命周期管理，配合獨立操作與行為機制，支撐從簡單 CRUD 到複雜多模組應用的全谱系開發需求。