控制臺(tái)命令（Console Commands）

控制臺(tái)命令

除了用于構(gòu)建 Web 應(yīng)用程序的豐富功能，Yii 中也有一個(gè)擁有豐富功能的控制臺(tái)，它們主要用于創(chuàng)建網(wǎng)站后臺(tái)處理的任務(wù)。

控制臺(tái)應(yīng)用程序的結(jié)構(gòu)非常類似于 Yii 的一個(gè) Web 應(yīng)用程序。它由一個(gè)或多個(gè) yii\console\Controller 類組成，它們?cè)诳刂婆_(tái)環(huán)境下通常被稱為“命令”。每個(gè)控制器還可以有一個(gè)或多個(gè)動(dòng)作，就像 web 控制器。

兩個(gè)項(xiàng)目模板（基礎(chǔ)模版和高級(jí)模版）都有自己的控制臺(tái)應(yīng)用程序。你可以通過(guò)運(yùn)行?yii?腳本，在位于倉(cāng)庫(kù)的基本目錄中運(yùn)行它。 當(dāng)你不帶任何參數(shù)來(lái)運(yùn)行它時(shí)，會(huì)給你一些可用的命令列表：

正如你在截圖中看到，Yii 中已經(jīng)定義了一組默認(rèn)情況下可用的命令：

• yii\console\controllers\AssetController - 允許合并和壓縮你的 JavaScript 和 CSS 文件。在?資源 - 使用 asset 命令?一節(jié)可獲取更多信息。
• yii\console\controllers\CacheController - 清除應(yīng)用程序緩存。
• yii\console\controllers\FixtureController - 管理用于單元測(cè)試 fixture 的加載和卸載。 這個(gè)命令的更多細(xì)節(jié)在?Testing Section about Fixtures.
• yii\console\controllers\HelpController - 提供有關(guān)控制臺(tái)命令的幫助信息，這是默認(rèn)的命令并會(huì)打印上面截圖所示的輸出。
• yii\console\controllers\MessageController - 從源文件提取翻譯信息。 要了解更多關(guān)于這個(gè)命令的用法，請(qǐng)參閱?I18N 章節(jié).
• yii\console\controllers\MigrateController - 管理應(yīng)用程序數(shù)據(jù)庫(kù)遷移。 在?數(shù)據(jù)庫(kù)遷移章節(jié)?可獲取更多信息。

用法

你可以使用以下語(yǔ)法來(lái)執(zhí)行控制臺(tái)控制器操作：

yii <route> [--option1=value1 --option2=value2 ... argument1 argument2 ...]

以上，<route>?指的是控制器動(dòng)作的路由。選項(xiàng)將填充類屬性，參數(shù)是動(dòng)作方法的參數(shù)。

例如，將 yii\console\controllers\MigrateController::actionUp() 限制 5 個(gè)數(shù)據(jù)庫(kù)遷移并將 yii\console\controllers\MigrateController::$migrationTable 設(shè)置為?migrations?應(yīng)該這樣調(diào)用：

yii migrate/up 5 --migrationTable=migrations

注意: 當(dāng)在控制臺(tái)使用?*?時(shí), 不要忘記像?"*"?一樣用引號(hào)來(lái)引起來(lái)，為了防止在 shell 中執(zhí)行命令時(shí)被當(dāng)成當(dāng)前目錄下的所有文件名。

入口腳本

控制臺(tái)應(yīng)用程序的入口腳本相當(dāng)于用于 Web 應(yīng)用程序的?index.php?入口文件。 控制臺(tái)入口腳本通常被稱為?yii，位于應(yīng)用程序的根目錄。它包含了類似下面的代碼：

#!/usr/bin/env php
<?php
/**
 * Yii console bootstrap file.
 */

defined('YII_DEBUG') or define('YII_DEBUG', true);

require(__DIR__ . '/vendor/autoload.php');
require(__DIR__ . '/vendor/yiisoft/yii2/Yii.php');

$config = require(__DIR__ . '/config/console.php');

$application = new yii\console\Application($config);
$exitCode = $application->run();
exit($exitCode);

該腳本將被創(chuàng)建為你應(yīng)用程序中的一部分；你可以根據(jù)你的需求來(lái)修改它。如果你不需要記錄錯(cuò)誤信息或者希望提高整體性能，YII_DEBUG?常數(shù)應(yīng)定義為?false。 在基本的和高級(jí)的兩個(gè)應(yīng)用程序模板中，控制臺(tái)應(yīng)用程序的入口腳本在默認(rèn)情況下會(huì)啟用調(diào)試模式，以提供給開(kāi)發(fā)者更好的環(huán)境。

配置

在上面的代碼中可以看到，控制臺(tái)應(yīng)用程序使用它自己的配置文件，名為?console.php?。在該文件里你可以給控制臺(tái)配置各種?應(yīng)用組件?和屬性。

如果你的 web 應(yīng)用程序和控制臺(tái)應(yīng)用程序共享大量的配置參數(shù)和值，你可以考慮把這些值放在一個(gè)單獨(dú)的文件中，該文件中包括（ web 和控制臺(tái)）應(yīng)用程序配置。 你可以在“高級(jí)”項(xiàng)目模板中看到一個(gè)例子。

提示：有時(shí)，你可能需要使用一個(gè)與在入口腳本中指定的應(yīng)用程序配置不同的控制臺(tái)命令。例如，你可能想使用?yii migrate命令來(lái)升級(jí)你的測(cè)試數(shù)據(jù)庫(kù)，它被配置在每個(gè)測(cè)試套件。要?jiǎng)討B(tài)地更改配置，只需指定一個(gè)自定義應(yīng)用程序的配置文件，通過(guò)appconfig選項(xiàng)來(lái)執(zhí)行命令：

yii <route> --appconfig=path/to/config.php ...

創(chuàng)建你自己的控制臺(tái)命令

控制臺(tái)的控制器和行為

一個(gè)控制臺(tái)命令繼承自 yii\console\Controller 控制器類。 在控制器類中，定義一個(gè)或多個(gè)與控制器的子命令相對(duì)應(yīng)的動(dòng)作。在每一個(gè)動(dòng)作中，編寫(xiě)你的代碼實(shí)現(xiàn)特定的子命令的適當(dāng)?shù)娜蝿?wù)。

當(dāng)你運(yùn)行一個(gè)命令時(shí)，你需要指定一個(gè)控制器的路由。例如，路由?migrate/create?調(diào)用子命令對(duì)應(yīng)的yii\console\controllers\MigrateController::actionCreate() 動(dòng)作方法。 如果在執(zhí)行過(guò)程中提供的路由不包含路由 ID ，將執(zhí)行默認(rèn)操作（如 web 控制器）。

選項(xiàng)

通過(guò)覆蓋在 yii\console\Controller::options() 中的方法，你可以指定可用于控制臺(tái)命令（controller/actionID）選項(xiàng)。這個(gè)方法應(yīng)該返回控制器類的公共屬性的列表。 當(dāng)運(yùn)行一個(gè)命令，你可以指定使用語(yǔ)法?--OptionName=OptionValue?選項(xiàng)的值。 這將分配OptionValue?到控制器類的?OptionName?屬性。

If the default value of an option is of an array type and you set this option while running the command, the option value will be converted into an array by splitting the input string on any commas.

參數(shù)

除了選項(xiàng)，命令還可以接收參數(shù)。參數(shù)將傳遞給請(qǐng)求的子命令對(duì)應(yīng)的操作方法。第一個(gè)參數(shù)對(duì)應(yīng)第一個(gè)參數(shù)，第二個(gè)參數(shù)對(duì)應(yīng)第二個(gè)參數(shù)，依次類推。 命令被調(diào)用時(shí)，如果沒(méi)有足夠的參數(shù)，如果有定義默認(rèn)值的情況下，則相應(yīng)的參數(shù)將采取默認(rèn)聲明的值；如果沒(méi)有設(shè)置默認(rèn)值，并且在運(yùn)行時(shí)沒(méi)有提供任何值，該命令將以一個(gè)錯(cuò)誤退出。

你可以使用?array?類型提示來(lái)指示一個(gè)參數(shù)應(yīng)該被視為一個(gè)數(shù)組。該數(shù)組通過(guò)拆分輸入字符串的逗號(hào)來(lái)生成。

下面的示例演示如何聲明參數(shù)：

class ExampleController extends \yii\console\Controller
{
    // 命令 "yii example/create test" 會(huì)調(diào)用 "actionCreate('test')"
    public function actionCreate($name) { ... }

    // 命令 "yii example/index city" 會(huì)調(diào)用 "actionIndex('city', 'name')"
    // 命令 "yii example/index city id" 會(huì)調(diào)用 "actionIndex('city', 'id')"
    public function actionIndex($category, $order = 'name') { ... }

    // 命令 "yii example/add test" 會(huì)調(diào)用 "actionAdd(['test'])"
    // 命令 "yii example/add test1,test2" 會(huì)調(diào)用 "actionAdd(['test1', 'test2'])"
    public function actionAdd(array $name) { ... }
}

退出代碼

使用退出代碼是控制臺(tái)應(yīng)用程序開(kāi)發(fā)的最佳做法。通常，執(zhí)行成功的命令會(huì)返回?0。如果命令返回一個(gè)非零數(shù)字，會(huì)認(rèn)為出現(xiàn)錯(cuò)誤。 該返回的數(shù)字作為出錯(cuò)代碼，用以了解錯(cuò)誤的詳細(xì)信息。例如?1?可能代表一個(gè)未知的錯(cuò)誤，所有的代碼都將保留在特定的情況下：輸入錯(cuò)誤，丟失的文件等等。

要讓控制臺(tái)命令返回一個(gè)退出代碼，只需在控制器操作方法中返回一個(gè)整數(shù)：

public function actionIndex()
{
    if (/* some problem */) {
        echo "A problem occured!\n";
        return 1;
    }
    // do something
    return 0;
}

你可以使用一些預(yù)定義的常數(shù)：

• Controller::EXIT_CODE_NORMAL?值為?0;
• Controller::EXIT_CODE_ERROR?值為?1.

為控制器定義有意義的常量，以防有更多的錯(cuò)誤代碼類型，這會(huì)是一個(gè)很好的實(shí)踐。

格式和顏色

Yii 支持格式化輸出，如果終端運(yùn)行命令不支持的話則會(huì)自動(dòng)退化為非格式化輸出。

要輸出格式的字符串很簡(jiǎn)單。以下展示了如何輸出一些加粗的文字：

$this->stdout("Hello?\n", Console::BOLD);

如果你需要建立字符串動(dòng)態(tài)結(jié)合的多種樣式，最好使用?ansiFormat?：

$name = $this->ansiFormat('Alex', Console::FG_YELLOW);
echo "Hello, my name is $name.";