主控台應用程式 ¶

除了用於建構網站應用程式的豐富功能外，Yii 也完整支援主控台應用程式，這些應用程式主要用於建立網站需要執行的背景和維護任務。

主控台應用程式的結構與 Yii 網站應用程式非常相似。它由一個或多個 yii\console\Controller 類別組成，這些類別在主控台環境中通常被稱為命令。每個控制器也可以有一個或多個動作，就像網站控制器一樣。

這兩個專案範本都已經包含主控台應用程式。您可以透過呼叫位於儲存庫根目錄的 yii 腳本來執行它。當您在沒有任何其他參數的情況下執行它時，它會顯示可用命令的列表

如您在螢幕截圖中所見，Yii 已經定義了一組預設可用的命令

• AssetController - 允許您組合和壓縮您的 JavaScript 和 CSS 檔案。您可以在資源章節中了解更多關於此命令的資訊。
• CacheController - 允許您清除應用程式快取。
• FixtureController - 管理用於測試目的的 fixture 資料載入和卸載。此命令在關於 Fixture 的測試章節中有更詳細的描述。
• HelpController - 提供關於主控台命令的幫助資訊，這是預設命令，並印出您在上面輸出中看到的內容。
• MessageController - 從原始程式碼檔案中提取要翻譯的訊息。要了解更多關於此命令的資訊，請參閱I18N 章節。
• MigrateController - 管理應用程式遷移。資料庫遷移在資料庫遷移章節中有更詳細的描述。
• ServeController - 允許您執行 PHP 內建的網頁伺服器。

用法 ¶

您可以使用以下語法執行主控台控制器動作

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

選項可以在任何位置指定。

在上面，<route> 指的是控制器動作的路徑。選項將填充類別屬性，而參數是動作方法的參數。

例如，將 MigrateController::$migrationTable 設定為 migrations 且限制為 5 個遷移的 MigrateController::actionUp() 可以這樣呼叫

yii migrate/up 5 --migrationTable=migrations

注意：當在主控台中使用 * 時，別忘了將其用引號括起來，例如 "*"，以避免將其作為 shell glob 執行，shell glob 會被目前目錄的所有檔案名稱取代。

進入點腳本 ¶

主控台應用程式的進入點腳本相當於網站應用程式使用的 index.php 啟動引導檔案。主控台進入點腳本通常稱為 yii，並且位於您應用程式的根目錄中。它包含如下程式碼

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

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

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。在此檔案中，您應該特別為主控台應用程式設定各種 應用程式組件 和屬性。

如果您的網站應用程式和主控台應用程式共用許多設定參數和值，您可以考慮將共用部分移到一個單獨的檔案中，並將此檔案包含在兩個應用程式設定 (網站和主控台) 中。您可以在進階專案範本中看到此範例。

提示：有時，您可能希望使用與進入點腳本中指定的應用程式設定不同的應用程式設定來執行主控台命令。例如，您可能想要使用 yii migrate 命令來升級您的測試資料庫，這些資料庫在每個個別的測試套件中設定。若要動態變更設定，只需在執行命令時透過 appconfig 選項指定自訂應用程式設定檔即可

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

主控台命令自動完成 ¶

當使用 shell 時，命令參數的自動完成是一件有用的事情。自 2.0.11 版本起，./yii 命令開箱即用，為 Bash 和 ZSH 提供自動完成功能。

Bash 自動完成 ¶

確保已安裝 bash 自動完成功能。對於大多數安裝而言，預設情況下它是可用的。

將自動完成腳本放置在 /etc/bash_completion.d/ 中

 curl -L https://raw.githubusercontent.com/yiisoft/yii2/master/contrib/completion/bash/yii -o /etc/bash_completion.d/yii

對於臨時使用，您可以將檔案放在目前目錄中，並透過 source yii 將其包含在目前的 session 中。如果全域安裝，您可能需要重新啟動終端機或 source ~/.bashrc 以啟用它。

查看 Bash 手冊 以了解將自動完成腳本包含到您的環境中的其他方法。

ZSH 自動完成 ¶

將自動完成腳本放在用於自動完成的目錄中，例如使用 ~/.zsh/completion/

mkdir -p ~/.zsh/completion
curl -L https://raw.githubusercontent.com/yiisoft/yii2/master/contrib/completion/zsh/_yii -o ~/.zsh/completion/_yii

將目錄包含在 $fpath 中，例如透過將其新增到 ~/.zshrc

fpath=(~/.zsh/completion $fpath)

確保已載入 compinit，或透過將其新增到 ~/.zshrc 來執行此操作

autoload -Uz compinit && compinit -i

然後重新載入您的 shell

exec $SHELL -l

建立您自己的主控台命令 ¶

主控台控制器與動作 ¶

主控台命令定義為從 yii\console\Controller 擴展的控制器類別。在控制器類別中，您定義一個或多個對應於控制器子命令的動作。在每個動作中，您編寫程式碼來實作該特定子命令的適當任務。

執行命令時，您需要指定控制器動作的路徑。例如，路徑 migrate/create 會調用對應於 MigrateController::actionCreate() 動作方法的子命令。如果在執行期間提供的路徑不包含動作 ID，則將執行預設動作 (與網站控制器相同)。

選項 ¶

透過覆寫 yii\console\Controller::options() 方法，您可以指定可用於主控台命令 (controller/actionID) 的選項。該方法應傳回控制器類別的公用屬性列表。執行命令時，您可以使用 --optionName=optionValue 語法指定選項的值。這會將 optionValue 指派給控制器類別的 optionName 屬性。

如果選項的預設值是陣列類型，並且您在執行命令時設定了此選項，則選項值將透過在任何逗號上分割輸入字串來轉換為陣列。

選項別名 ¶

自 2.0.8 版本起，主控台命令提供 yii\console\Controller::optionAliases() 方法來為選項新增別名。

要定義別名，請在您的控制器中覆寫 yii\console\Controller::optionAliases()，例如

namespace app\commands;

use yii\console\Controller;

class HelloController extends Controller
{
    public $message;
    
    public function options($actionID)
    {
        return ['message'];
    }
    
    public function optionAliases()
    {
        return ['m' => 'message'];
    }
    
    public function actionIndex()
    {
        echo $this->message . "\n";
    }
}

現在，您可以使用以下語法來執行命令

yii hello -m=hello

參數 ¶

除了選項之外，命令還可以接收參數。參數將作為參數傳遞給對應於請求的子命令的動作方法。第一個參數對應於第一個參數，第二個參數對應於第二個參數，依此類推。如果在呼叫命令時未提供足夠的參數，則對應的參數將採用宣告的預設值 (如果已定義)。如果未設定預設值，且在執行階段未提供值，則命令將以錯誤退出。

您可以使用 array 類型提示來指示參數應被視為陣列。陣列將透過在逗號上分割輸入字串來產生。

以下範例示範如何宣告參數

class ExampleController extends \yii\console\Controller
{
    // The command "yii example/create test" will call "actionCreate('test')"
    public function actionCreate($name) { ... }

    // The command "yii example/index city" will call "actionIndex('city', 'name')"
    // The command "yii example/index city id" will call "actionIndex('city', 'id')"
    public function actionIndex($category, $order = 'name') { ... }

    // The command "yii example/add test" will call "actionAdd(['test'])"
    // The command "yii example/add test1,test2" will call "actionAdd(['test1', 'test2'])"
    public function actionAdd(array $name) { ... }
}

退出代碼 ¶

使用退出代碼是主控台應用程式開發的最佳實踐。傳統上，命令傳回 0 表示一切正常。如果命令傳回大於零的數字，則認為表示發生錯誤。傳回的數字將是錯誤代碼，可能可用於找出有關錯誤的詳細資訊。例如，1 通常可以代表未知錯誤，而所有更高的代碼將保留用於特定情況：輸入錯誤、檔案遺失等等。

要讓您的主控台命令傳回退出代碼，只需在控制器動作方法中傳回一個整數

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

您可以使用一些預定義的常數。這些常數在 yii\console\ExitCode 類別中定義

public function actionIndex()
{
    if (/* some problem */) {
        echo "A problem occurred!\n";
        return ExitCode::UNSPECIFIED_ERROR;
    }
    // do something
    return ExitCode::OK;
}

如果您有更具體的錯誤代碼類型，為您的控制器定義有意義的常數是一個好的實踐。

格式化與色彩 ¶

Yii 主控台支援格式化輸出，如果執行命令的終端機不支援格式化輸出，則會自動降級為非格式化輸出。

輸出格式化字串很簡單。以下是如何輸出一些粗體文字

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

如果您需要動態建構結合多種樣式的字串，最好使用 ansiFormat()

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

表格 ¶

自 2.0.13 版本起，有一個小工具允許您在主控台中格式化表格資料。它可以像這樣使用

echo Table::widget([
    'headers' => ['Project', 'Status', 'Participant'],
    'rows' => [
        ['Yii', 'OK', '@samdark'],
        ['Yii', 'OK', '@cebe'],
    ],
]);

詳細資訊請參閱 API 文件。