# 控制臺命令 除了用于構建 Web 應用程序的豐富功能，Yii 中也有一個擁有豐富功能的控制臺，它們主要用于創建網站后臺處理的任務。 控制臺應用程序的結構非常類似于 Yii 的一個 Web 應用程序。它由一個或多個 yii\console\Controller 類組成，它們在控制臺環境下通常被稱為“命令”。每個控制器還可以有一個或多個動作，就像 web 控制器。 兩個項目模板（基礎模版和高級模版）都有自己的控制臺應用程序。你可以通過運行?`yii`?腳本，在位于倉庫的基本目錄中運行它。 當你不帶任何參數來運行它時，會給你一些可用的命令列表：  正如你在截圖中看到，Yii 中已經定義了一組默認情況下可用的命令： * yii\console\controllers\AssetController - 允許合并和壓縮你的 JavaScript 和 CSS 文件。在?[資源 - 使用 asset 命令](http://www.yiichina.com/doc/guide/2.0/structure-assets#using-the-asset-command)?一節可獲取更多信息。 * yii\console\controllers\CacheController - 清除應用程序緩存。 * yii\console\controllers\FixtureController - 管理用于單元測試 fixture 的加載和卸載。 這個命令的更多細節在?[Testing Section about Fixtures](http://www.yiichina.com/doc/guide/2.0/test-fixtures#managing-fixtures). * yii\console\controllers\HelpController - 提供有關控制臺命令的幫助信息，這是默認的命令并會打印上面截圖所示的輸出。 * yii\console\controllers\MessageController - 從源文件提取翻譯信息。 要了解更多關于這個命令的用法，請參閱?[I18N 章節](http://www.yiichina.com/doc/guide/2.0/tutorial-i18n#message-command). * yii\console\controllers\MigrateController - 管理應用程序數據庫遷移。 在?[數據庫遷移章節](http://www.yiichina.com/doc/guide/2.0/db-migrations)?可獲取更多信息。 ## 用法 你可以使用以下語法來執行控制臺控制器操作： ~~~ yii <route> [--option1=value1 --option2=value2 ... argument1 argument2 ...] ~~~ 以上，`<route>`?指的是控制器動作的路由。選項將填充類屬性，參數是動作方法的參數。 例如，將 yii\console\controllers\MigrateController::actionUp() 限制 5 個數據庫遷移并將 yii\console\controllers\MigrateController::$migrationTable 設置為?`migrations`?應該這樣調用： ~~~ yii migrate/up 5 --migrationTable=migrations ~~~ > **注意**: 當在控制臺使用?`*`?時, 不要忘記像?`"*"`?一樣用引號來引起來，為了防止在 shell 中執行命令時被當成當前目錄下的所有文件名。 ## 入口腳本 控制臺應用程序的入口腳本相當于用于 Web 應用程序的?`index.php`?入口文件。 控制臺入口腳本通常被稱為?`yii`，位于應用程序的根目錄。它包含了類似下面的代碼： ~~~ #!/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); ~~~ 該腳本將被創建為你應用程序中的一部分；你可以根據你的需求來修改它。如果你不需要記錄錯誤信息或者希望提高整體性能，`YII_DEBUG`?常數應定義為?`false`。 在基本的和高級的兩個應用程序模板中，控制臺應用程序的入口腳本在默認情況下會啟用調試模式，以提供給開發者更好的環境。 ## 配置 在上面的代碼中可以看到，控制臺應用程序使用它自己的配置文件，名為?`console.php`?。在該文件里你可以給控制臺配置各種?[應用組件](http://www.yiichina.com/doc/guide/2.0/structure-application-components)?和屬性。 如果你的 web 應用程序和控制臺應用程序共享大量的配置參數和值，你可以考慮把這些值放在一個單獨的文件中，該文件中包括（ web 和控制臺）應用程序配置。 你可以在“高級”項目模板中看到一個例子。 > 提示：有時，你可能需要使用一個與在入口腳本中指定的應用程序配置不同的控制臺命令。例如，你可能想使用?`yii migrate`命令來升級你的測試數據庫，它被配置在每個測試套件。要動態地更改配置，只需指定一個自定義應用程序的配置文件，通過`appconfig`選項來執行命令： > > ~~~ > yii <route> --appconfig=path/to/config.php ... > ~~~ ## 創建你自己的控制臺命令 ### 控制臺的控制器和行為 一個控制臺命令繼承自 yii\console\Controller 控制器類。 在控制器類中，定義一個或多個與控制器的子命令相對應的動作。在每一個動作中，編寫你的代碼實現特定的子命令的適當的任務。 當你運行一個命令時，你需要指定一個控制器的路由。例如，路由?`migrate/create`?調用子命令對應的yii\console\controllers\MigrateController::actionCreate() 動作方法。 如果在執行過程中提供的路由不包含路由 ID ，將執行默認操作（如 web 控制器）。 ### 選項 通過覆蓋在 yii\console\Controller::options() 中的方法，你可以指定可用于控制臺命令（controller/actionID）選項。這個方法應該返回控制器類的公共屬性的列表。 當運行一個命令，你可以指定使用語法?`--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. ### 參數 除了選項，命令還可以接收參數。參數將傳遞給請求的子命令對應的操作方法。第一個參數對應第一個參數，第二個參數對應第二個參數，依次類推。 命令被調用時，如果沒有足夠的參數，如果有定義默認值的情況下，則相應的參數將采取默認聲明的值；如果沒有設置默認值，并且在運行時沒有提供任何值，該命令將以一個錯誤退出。 你可以使用?`array`?類型提示來指示一個參數應該被視為一個數組。該數組通過拆分輸入字符串的逗號來生成。 下面的示例演示如何聲明參數： ~~~ class ExampleController extends \yii\console\Controller { // 命令 "yii example/create test" 會調用 "actionCreate('test')" public function actionCreate($name) { ... } // 命令 "yii example/index city" 會調用 "actionIndex('city', 'name')" // 命令 "yii example/index city id" 會調用 "actionIndex('city', 'id')" public function actionIndex($category, $order = 'name') { ... } // 命令 "yii example/add test" 會調用 "actionAdd(['test'])" // 命令 "yii example/add test1,test2" 會調用 "actionAdd(['test1', 'test2'])" public function actionAdd(array $name) { ... } } ~~~ ### 退出代碼 使用退出代碼是控制臺應用程序開發的最佳做法。通常，執行成功的命令會返回?`0`。如果命令返回一個非零數字，會認為出現錯誤。 該返回的數字作為出錯代碼，用以了解錯誤的詳細信息。例如?`1`?可能代表一個未知的錯誤，所有的代碼都將保留在特定的情況下：輸入錯誤，丟失的文件等等。 要讓控制臺命令返回一個退出代碼，只需在控制器操作方法中返回一個整數： ~~~ public function actionIndex() { if (/* some problem */) { echo "A problem occured!\n"; return 1; } // do something return 0; } ~~~ 你可以使用一些預定義的常數： * `Controller::EXIT_CODE_NORMAL`?值為?`0`; * `Controller::EXIT_CODE_ERROR`?值為?`1`. 為控制器定義有意義的常量，以防有更多的錯誤代碼類型，這會是一個很好的實踐。 ### 格式和顏色 Yii 支持格式化輸出，如果終端運行命令不支持的話則會自動退化為非格式化輸出。 要輸出格式的字符串很簡單。以下展示了如何輸出一些加粗的文字： ~~~ $this->stdout("Hello?\n", Console::BOLD); ~~~ 如果你需要建立字符串動態結合的多種樣式，最好使用?`ansiFormat`?： ~~~ $name = $this->ansiFormat('Alex', Console::FG_YELLOW); echo "Hello, my name is $name."; ~~~