控制臺命令（Console Commands）

控制臺命令

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

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

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

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

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

用法

你可以使用以下語法來執(zhí)行控制臺控制器操作：

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

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

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

yii migrate/up 5 --migrationTable=migrations

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

入口腳本

控制臺應(yīng)用程序的入口腳本相當(dāng)于用于 Web 應(yīng)用程序的?index.php?入口文件。 控制臺入口腳本通常被稱為?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ù)你的需求來修改它。如果你不需要記錄錯誤信息或者希望提高整體性能，YII_DEBUG?常數(shù)應(yīng)定義為?false。 在基本的和高級的兩個應(yīng)用程序模板中，控制臺應(yīng)用程序的入口腳本在默認(rèn)情況下會啟用調(diào)試模式，以提供給開發(fā)者更好的環(huán)境。

配置

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

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

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

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

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

控制臺的控制器和行為

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

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

選項

通過覆蓋在 yii\console\Controller::options() 中的方法，你可以指定可用于控制臺命令（controller/actionID）選項。這個方法應(yīng)該返回控制器類的公共屬性的列表。 當(dāng)運行一個命令，你可以指定使用語法?--OptionName=OptionValue?選項的值。 這將分配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ù)

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

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

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

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

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

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

退出代碼

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

要讓控制臺命令返回一個退出代碼，只需在控制器操作方法中返回一個整數(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.

為控制器定義有意義的常量，以防有更多的錯誤代碼類型，這會是一個很好的實踐。

格式和顏色

Yii 支持格式化輸出，如果終端運行命令不支持的話則會自動退化為非格式化輸出。

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

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

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

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