控制台应用程序 ¶

除了为构建 Web 应用程序提供的丰富功能外，Yii 还全面支持控制台应用程序，主要用于创建网站需要执行的后台和维护任务。

控制台应用程序的结构与 Yii Web 应用程序非常相似。它包含一个或多个 yii\console\Controller 类，在控制台环境中通常被称为命令。每个控制器也可以具有一个或多个操作，就像 Web 控制器一样。

两个项目模板都已包含控制台应用程序。您可以通过调用yii脚本运行它，该脚本位于存储库的基目录中。当您在没有任何其他参数的情况下运行它时，它会提供可用命令的列表

正如您在屏幕截图中看到的，Yii 已经定义了一组默认可用的命令

• AssetController - 允许您组合和压缩 JavaScript 和 CSS 文件。您可以在资产部分中了解更多关于此命令的信息。
• CacheController - 允许您刷新应用程序缓存。
• FixtureController - 管理夹具数据加载和卸载，用于测试目的。此命令在关于夹具的测试部分中进行了更详细的描述。
• HelpController - 提供有关控制台命令的帮助信息，这是默认命令，会打印您在上面输出中看到的內容。
• MessageController - 从源文件提取要翻译的消息。要了解有关此命令的更多信息，请参阅I18N 部分。
• MigrateController - 管理应用程序迁移。数据库迁移在数据库迁移部分中进行了更详细的描述。
• ServeController - 允许您运行 PHP 内置 Web 服务器。

使用 ¶

您可以使用以下语法执行控制台控制器操作

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

选项可以在任何位置指定。

在上面，<route> 指的是控制器操作的路由。选项将填充类属性，而参数是操作方法的参数。

例如，MigrateController::actionUp()，其中 MigrateController::$migrationTable 设置为 migrations，并且迁移限制为 5 个，可以这样调用：

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);
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。在此文件中，您应该为控制台应用程序配置各种 应用程序组件 和属性。

如果您的 Web 应用程序和控制台应用程序共享许多配置参数和值，您可能需要考虑将公共部分移至一个单独的文件中，并将此文件包含在两个应用程序配置（Web 和控制台）中。您可以在高级项目模板中看到此示例。

提示：有时，您可能希望使用与入口脚本中指定的配置不同的应用程序配置运行控制台命令。例如，您可能希望使用 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 将其包含在当前会话中。如果全局安装，您可能需要重新启动终端或 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，则将执行默认操作（与 Web 控制器一样）。

选项 ¶

通过覆盖 yii\console\Controller::options() 方法，您可以指定可用于控制台命令（控制器/操作 ID）的选项。该方法应返回控制器类公共属性的列表。运行命令时，可以使用语法 --optionName=optionValue 指定选项的值。这将为控制器类的 optionName 属性分配 optionValue。

如果选项的默认值为数组类型，并且您在运行命令时设置了此选项，则选项值将通过在任何逗号上分割输入字符串来转换为数组。

选项别名 ¶

从版本 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 文档。