Yii框架官方指南系列50—專題：控制台應用

控制台應用主要用於實現在線Web應用所需的離線操作,例如代碼生成, 搜索索引編譯, 郵件發送等等. Yii框架以面向對象的方式提供了一個編寫控制台應用的框架. 它允許控制台應用存取線上網路應用程式所使用的資源(例如資料庫連線資訊) .

1. 概覽

Yii可以以命令列的方式運行每一個控制台任務，控制台命令是一個繼承自CConsoleCommand的類別。

當我們使用 yiic webapp 工具建立一個初始化的Yii應用骨架的時候, 我們可以在protected資料夾下看到如下兩個檔案:

• yiic: 這是一個運行在Linux/Unix上的可執行腳本;

• yiic.bat: 這是一個運行在Windows上的可執行批次腳本.

在控制台視窗中, 我們可以輸入如下命令:

cd protected
yiic help

這將會顯示一系列的控制台命令。預設情況下，這些有效的命令包括由Yii框架提供的（系統命令）和開發者自己為獨立應用程式編寫的（使用者命令）。

如果想要查看如何使用一個命令, 可以使用：

yiic help <command-name></command-name>

要執行一個命令, 可以使用如下的命令格式：

yiic <command-name> [parameters...]</command-name>

2. 創建命令

命令命令以類文件的控制台命令形如CConsoleApplication::command的路徑下. 預設情況下, 指向資料夾protected/commands.

一個控制台命令類別必須繼承自CConsoleCommand. 這個類別名稱必須是XyzCommand的格式, 其中 Xyz 名稱. 例如, 一個sitemap 指令必須使用類別名稱 SitemapCommand。控制台命令名稱是大小寫敏感的.

Tip: 透過設定CConsoleApplication::command匹配, 可以取得以不同形式命名、儲存在不同資料夾下的命令類別.

為了創建一個新的指令,需要經常重寫CConsoleCommand::run() 或發展一個或多個指令動作。

當執行一個控制台指令時，CConsoleCommand::run()方法將會被控制台套用呼叫。所有控制台參數也會以下列方法片段的形式傳入此方法：

public function run($args) { ... }

其中 $args 代表命令列給定的額外參數。

在控制台命令中, 我們可以使用 Yii::app()來訪問控制台應用實例, 不僅如此我們還可以訪問資源如數據庫連接(e.g. Yii::app()->db). 可以看到這種用法和在網路應用中的使用非常類似。

Info: 從版本1.1.1開始, 我們也可以建立被同一台機子上所有的Yii應用共享的全域指令：定義一個命名為YII_CONSOLE_COMMANDS的環境變數指向一個已存在的資料夾，然後將一個命名為YII_CONSOLE_COMMANDS的環境變數指向一個已存在的資料夾，然後將一個已存在的資料夾我們的全域命令類別放到這個資料夾下即可。

3. 控制台命令動作（action）

Note: 這個控制台命令動作特性從版本1.1.5後有效。

一個控制台命令經常需要處理不同的命令列參數, 有些是必須的，有些是可選的. 控制台命令還需要提供一些子命令來處理不同的子任務。這些工作可以簡化使用控制台命令動作。

一個控制台命令動作是一個控制台命令類別中的方法. 這個方法名稱必須是actionXyz的格式, 其中Xyz 代表首字母大寫的動作名稱. 例如, 一個actionIndex方法定義了一個命名為index的動作.

想要執行特定的動作, 我們可以使用如下的命令行格式:

yiic <command-name> <action-name> --option1=value1 --option2=value2 ...</action-name></command-name>

額外的option-value 對將為以命名參數的方式傳入動作方法中. 一個xyz 操作的值將會以$xyz參數的形式傳入到動作方法中。例如, 如果我們定義瞭如下的命令類:

class SitemapCommand extends CConsoleCommand
{
    public function actionIndex($type, $limit=5) { ... }
    public function actionInit() { ... }
}

然後，下面的控制台命令在調用actionIndex('News', 5)的時候都會有結果:

yiic sitemap index --type=News --limit=5

// $limit takes default value
yiic sitemap index --type=News

// $limit takes default value
// because 'index' is a default action, we can omit the action name
yiic sitemap --type=News

// the order of options does not matter
yiic sitemap index --limit=5 --type=News

沒有指定值(e.g. --type instead of --type=News), 對應的動作參數值將會假定為true。

Note: 不支援選購的參數格式 --type News, -t News.

一個參數值可以是陣列（必須要有陣列型態提示）:

在命令列參數中想要使用數組值, 只需簡單重複同一個選項:

public function actionIndex(array $types) { ... }

上面的命令最終將會調用actionIndex(array('News', 'Article')).

從版本1.1. 6開始, Yii 也支援使用匿名動作參數和全域選項.

匿名参数表示这些命令行参数不是以选项的形式呈现. 例如, 在命令 yiic sitemap index --limit=5 News中, 我们有一个值为News的匿名参数和命名参数 limit，其值为5。

为了使用匿名参数, 一个命令动作必须声明参数为 $args的形式. 例如,

public function actionIndex($limit=10, $args=array()) {...}

$args数组将会装入所有的匿名参数值.

全局选项代表那些命令行选项可以被一个命令中所有动作共享的选项. 例如, 在一个命令中提供了多个选项, 我们可能想要每一个动作识别一个名为verbose的动作. 当然我们可以在每一个动作方法中声明 $verbose 参数, 一个更好的方式是将其声明为这个命令类的公有成员变量, 将 verbose 转换为全局参数:

class SitemapCommand extends CConsoleCommand
{
    public $verbose=false;
    public function actionIndex($type) {...}
}

上面的代码允许我们执行一个带 verbose 选项的命令:

yiic sitemap index --verbose=1 --type=News

4. 退出代码

Note: 在控制台命令中退出代码的特性从版本 1.1.11起有效.

通过cronjob或者使用一个持续集成的服务器自动运行控制台命令的时候, 要么命令运行运行成功，要么命令运行失败. 这可以通过检查进程返回的退出代码来查看。

这些退出码是从0-254的整型值(this is the range in php world), 其中 0 表示退出成功其他的所有非0值表示出现了错误.

在一个动作方法或者控制台命令的 run() 方法中你可以在退出时返回整型值退出码 ，例如:

if (/* error */) {
    return 1; // exit with error code 1
}
// ... do something ...
return 0; // exit successfully

如果没有返回值, 应用将会退出返回 0.

5. 自定义控制台应用

默认情况下, 如果一个应用是使用yiic webapp工具创建的, 命令行应用的配置将会放在 protected/config/console.php文件中. 和一个Web应用配置文件一样, 这个文件是一个返回控制台应用实例的初始化配置值的数组的PHP脚本。所以CConsoleApplication的任何公有属性都可以在该文件中配置.

因为控制台命令经常被创建来服务于Web应用, 所以需要访问资源（如数据库连接）。我们可以在控制台配置文件中以如下方式来实现 ：

return array(
    ......
    'components'=>array(
        'db'=>array(
            ......
        ),
    ),
);

正如我们所看到的那样, 配置的格式和我们在Web应用中的配置类似.这是因为CConsoleApplication和 CWebApplication 的基类相同。

 以上就是Yii框架官方指南系列50——专题：控制台应用的内容，更多相关内容请关注PHP中文网（www.php.cn）！