控制器

控制器 是 CController 或其子類別的實體。它在當用戶請求時由應用程式建立。 當一個控制器運行時，它執行所請求的動作，動作通常會載入所必要的模型並呈現相應的視圖。 動作 最簡單的形式，就是一個名字以 action 開頭的控制器類別行為。

控制器通常有一個預設的動作。當用戶的請求未指定要執行的動作時，預設動作將被執行。 預設情況下，預設的動作名為 index。它可以通過設置 CController::defaultAction 修改。

如下是一個 Site 控制器，擁有一個 index 動作 (預設動作) 和一個 contact 動作。

class SiteController extends CController
{
    public function actionIndex()
    {
        // ...
    }
 
    public function actionContact()
    {
        // ...
    }
}

路由

控制器和動作以 ID 識別。控制器 ID 是一種 'path/to/xyz' 的格式，對應相應的控制器類別檔案 protected/controllers/path/to/XyzController.php, 其中的標誌 xyz 應被替換為實際的名字 (例如 post 對應 protected/controllers/PostController.php). 動作 ID 是除去 action 前綴的動作方法名。例如，如果一個控制器類別含有一個名為 actionEdit 的方法，則相應的動作 ID 為 edit。

注意: 在 1.0.3 版本之前，控制器 ID 的格式為 path.to.xyz ，而不是 path/to/xyz。

用戶以路由的形式請求特定的控制器和動作。路由是由控制器 ID 和動作 ID 連接起來的，兩者以斜線分割。 例如，路由 post/edit 代表 PostController 及其 edit 動作。預設情況下，URL http://hostname/index.php?r=post/edit 即請求此控制器和動作。

注意: 預設情況下，路由是大小寫敏感的，從版本 1.0.1 開始，可以通過設置應用程式配置中的 CUrlManager::caseSensitive 為 false 使路由對大小寫不敏感。當在大小寫不敏感模式中時， 要確保你遵循了相應的規則約定，即：包含控制器類別檔案的目錄名小寫，且 控制器映射 和 動作映射 中使用的鍵為小寫。

從 1.0.3 版本開始，應用程式可以含有 模組（Module）. 模組中，控制器動作的路由格式為 moduleID/controllerID/actionID 。 更多詳情，請閱讀 模組相關章節.

控制器實體化

控制器實體在 CWebApplication 處理送來的請求時建立。指定了控制器 ID ， 應用程式將使用如下規則確定控制器的類別以及類別檔案的位置。

在使用了 模組 (1.0.3 版後可用) 後，上述過程則稍有不同。 具體來說，應用程式將檢查此 ID 是否代表一個模組中的控制器。如果是的話，模組實體將被首先建立，然後建立模組中的控制器實體。

動作

如前文所述，動作可以被定義為一個以 action 單字作為前綴命名的方法。而更高級的方式是定義一個動作類別並讓控制器在收到請求時將其實體化。 這使得動作可以被復用，提高了可復用度。

要定義一個新動作類別，可用如下程式碼：

class UpdateAction extends CAction
{
    public function run()
    {
        // place the action logic here
    }
}

為了讓控制器注意到這個動作，我們要用如下方式覆蓋控制器類別的actions() 方法：

class PostController extends CController
{
    public function actions()
    {
        return array(
            'edit'=>'application.controllers.post.UpdateAction',
        );
    }
}

如上所示，我們使用了路徑別名 application.controllers.post.UpdateAction 指定動作類別檔案為 protected/controllers/post/UpdateAction.php.

通過編寫基於類別的動作，我們可以將應用程式組織為模組的風格。例如， 如下目錄結構可用於組織控制器相關程式碼：

protected/
    controllers/
        PostController.php
        UserController.php
        post/
            CreateAction.php
            ReadAction.php
            UpdateAction.php
        user/
            CreateAction.php
            ListAction.php
            ProfileAction.php
            UpdateAction.php

動作參數綁定

從版本 1.1.4 開始，Yii 提供了對自動動作參數綁定的支援。 就是說，控制器動作可以定義命名的參數，參數的值將由 Yii 自動從 $_GET 提取。

為了詳細說明此功能，假設我們需要為 PostController 寫一個 create 動作。此動作需要兩個參數：

從 $_GET 中提取參數時，我們可以不再使用下面這種無聊的程式碼了：

class PostController extends CController
{
    public function actionCreate()
    {
        if(isset($_GET['category']))
            $category=(int)$_GET['category'];
        else
            throw new CHttpException(404,'invalid request');
 
        if(isset($_GET['language']))
            $language=$_GET['language'];
        else
            $language='en';
 
        // ... fun code starts here ...
    }
}

現在使用動作參數功能，我們可以更輕鬆的完成任務：

class PostController extends CController
{
    public function actionCreate($category, $language='en')
    {
        $category=(int)$category;
 
        // ... fun code starts here ...
    }
}

注意我們在動作方法 actionCreate 中增加了兩個參數。 這些參數的名字必須和我們想要從 $_GET 中提取的名字一致。 當用戶沒有在請求中指定 $language 參數時，這個參數會使用預設值 en 。 由於 $category 沒有預設值，如果用戶沒有在 $_GET 中提供 category 參數， 將會自動拋出一個 CHttpException (錯誤程式碼 400) 異常。

從 1.1.5 之後的版本, Yii 也支援對動作參數的陣列型別的偵測。這是藉由 PHP 的型別提示來完成，語法如下：

class PostController extends CController
{
    public function actionCreate(array $categories)
    {
        // Yii will make sure $categories be an array
    }
}

使用關鍵字 array 在參數 $categories 之前。所以，如果 $_GET['categories'] 是一個字串，他就會被轉換成一個含有此字串的陣列。

注意: 如果參數的宣告沒有 array 的型別提示，這代表該參數一定是個 純量 (scalar) (例如，不是一個陣列). 在這種情況下，透過 $_GET 傳遞一個陣列參數 會引發 HTTP 例外。

過濾器

過濾器是一段程式碼，可被配置在控制器動作執行之前或之後執行。例如，存取控制過濾器將被執行以確保在執行請求的動作之前，用戶已通過身份驗證；性能過濾器可用於測量控制器執行所用的時間。

一個動作可以有多個過濾器。過濾器執行順序為它們出現在過濾器列表中的順序。過濾器可以阻止動作及後面其他過濾器的執行

過濾器可以定義為一個控制器類別的方法。方法名必須以 filter 開頭。例如，現有的 filterAccessControl 方法定義了一個名為 accessControl 的過濾器。 過濾器方法必須為如下結構：

public function filterAccessControl($filterChain)
{
    // 調用 $filterChain->run() 以繼續後續過濾器與動作的執行。
}

其中的 $filterChain (過濾器鏈)是一個 CFilterChain 的實體，代表與所請求動作相關的過濾器列表。在過濾器方法中， 我們可以調用 $filterChain->run() 以繼續執行後續過濾器和動作。

過濾器也可以是一個 CFilter 或其子類別的實體。如下程式碼定義了一個新的過濾器類別：

class PerformanceFilter extends CFilter
{
    protected function preFilter($filterChain)
    {
        // 動作被執行之前應用程式的邏輯
        return true; // 如果動作不應被執行，此處返回 false
    }
 
    protected function postFilter($filterChain)
    {
        // 動作執行之後應用程式的邏輯
    }
}

要對動作應用程式過濾器，我們需要覆蓋 CController::filters() 方法。此方法應返回一個過濾器配置數組。例如：

class PostController extends CController
{
    ......
    public function filters()
    {
        return array(
            'postOnly + edit, create',
            array(
                'application.filters.PerformanceFilter - edit, create',
                'unit'=>'second',
            ),
        );
    }
}

上述程式碼指定了兩個過濾器： postOnly 和 PerformanceFilter。 postOnly 過濾器是基於方法的（相應的過濾器方法已在 CController 中定義）； 而 performanceFilter 過濾器是基於物件的。路徑別名 application.filters.PerformanceFilter 指定過濾器類別檔案是 protected/filters/PerformanceFilter。我們使用一個數組配置 PerformanceFilter ，這樣它就可被用於初始化過濾器對象的屬性值。此處 PerformanceFilter 的 unit 屬性值將被初始為 second。

使用加減號，我們可指定哪些動作應該或不應該應用程式過濾器。上述程式碼中， postOnly 應只被應用程式於 edit 和 create 動作，而 PerformanceFilter 應被應用程式於 除了 edit 和 create 之外的動作。 如果過濾器配置中沒有使用加減號，則此過濾器將被應用於所有動作。

$Id$