Yii 的修行之路 - Console 控制檯命令

簡述

控制檯應用程序的結構很是相似於 Yii 的一個 Web 應用程序，主要用於終端服務器執行。

控制檯命令

控制檯應用程序的結構很是相似於 Yii 的一個 Web 應用程序。

它由一個或多個 yiiconsoleController 類組成，它們在控制檯環境下一般被稱爲「命令」。每一個控制器還能夠有一個或多個動做，就像 web 控制器。

兩個項目模板（基礎模版和高級模版）都有本身的控制檯應用程序。你能夠經過運行 yii 腳本，在位於倉庫的基本目錄中運行它。

當你不帶任何參數來運行它時，會給你一些可用的命令列表：

正如你在截圖中看到，Yii 中已經定義了一組默認狀況下可用的命令：

• yiiconsolecontrollersAssetController - 容許合併和壓縮你的 JavaScript 和 CSS 文件。

• yiiconsolecontrollersCacheController - 清除應用程序緩存。

• yiiconsolecontrollersFixtureController - 管理用於單元測試 fixture 的加載和卸載。

• yiiconsolecontrollersHelpController - 提供有關控制檯命令的幫助信息，這是默認的命令並會打印上面截圖所示的輸出。

• yiiconsolecontrollersMessageController - 從源文件提取翻譯信息。

• yiiconsolecontrollersMigrateController - 管理應用程序數據庫遷移。

用法
你能夠使用如下語法來執行控制檯控制器操做：

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 。在該文件裏你能夠給控制檯配置各類 應用組件 和屬性。

若是你的 web 應用程序和控制檯應用程序共享大量的配置參數和值，你能夠考慮把這些值放在一個單獨的文件中，該文件中包括（ web 和控制檯）應用程序配置。 你能夠在「高級」項目模板中看到一個例子。

提示：有時，你可能須要使用一個與在入口腳本中指定的應用程序配置不一樣的控制檯命令。例如，你可能想使用 yii migrate命令來升級你的測試數據庫，它被配置在每一個測試套件。

要動態地更改配置，只需指定一個自定義應用程序的配置文件，經過appconfig選項來執行命令：

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

控制檯的控制器和行爲

一個控制檯命令繼承自 yiiconsoleController 控制器類。 在控制器類中，定義一個或多個與控制器的子命令相對應的動做。在每個動做中，編寫你的代碼實現特定的子命令的適當的任務。

當你運行一個命令時，你須要指定一個控制器的路由。例如，路由 migrate/create 調用子命令對應的yiiconsolecontrollersMigrateController::actionCreate() 動做方法。

若是在執行過程當中提供的路由不包含路由 ID ，將執行默認操做（如 web 控制器）。

選項

經過覆蓋在 options() 中的方法，你能夠指定可用於控制檯命令（controller/actionID）選項。這個方法應該返回控制器類的公共屬性的列表。

當運行一個命令，你能夠指定使用語法 --OptionName=OptionValue 選項的值。 這將分配OptionValue 到控制器類的 OptionName 屬性。

參數

除了選項，命令還能夠接收參數。參數將傳遞給請求的子命令對應的操做方法。第一個參數對應第一個參數，第二個參數對應第二個參數，依次類推。

命令被調用時，若是沒有足夠的參數，若是有定義默認值的狀況下，則相應的參數將採起默認聲明的值；若是沒有設置默認值，而且在運行時沒有提供任何值，該命令將以一個錯誤退出。

你能夠使用 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.";