Yii 2: The Fast, Secure and Professional PHP Framework 命令行工具开发：自定义控制台命令
项目地址: https://gitcode.com/gh_mirrors/yi/yii2 Yii 2 框架不仅提供了构建 Web 应用程序的丰富功能，还包含了强大的控制台工具支持，用于创建后台处理任务。控制台应用程序的结构类似于 Web 应用程序，由一个或多个继承自 [[yii\console\Controller]] 的控制器类组成，这些控制器在控制台环境中通常被称为"命令"。
控制台命令基础
命令结构与入口脚本
控制台应用程序的入口脚本通常名为 yii，位于应用程序根目录，类似于 Web 应用的 index.php。其基本结构如下：
#!/usr/bin/env php
<?php
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 脚本不带任何参数时，会显示所有可用命令的帮助信息，包括 Yii 内置命令和自定义命令。
命令执行语法
执行控制台命令的基本语法如下：
yii <route> [--option1=value1 --option2=value2 ... argument1 argument2 ...]
其中 <route> 指控制器动作的路由，选项使用 --OptionName=OptionValue 格式，参数将传递给动作方法。例如执行数据库迁移命令：
yii migrate/up 5 --migrationTable=migrations
创建自定义控制台命令
基本控制器结构
自定义控制台命令需要创建继承自 [[yii\console\Controller]] 的控制器类，通常放置在 commands 目录下。以下是一个简单示例：
namespace app\commands;
use yii\console\Controller;
use yii\console\ExitCode;
class HelloController extends Controller
{
public function actionIndex()
{
echo "Hello, Yii Console!\n";
return ExitCode::OK;
}
}
选项与参数
定义选项
通过覆盖 [[yii\console\Controller::options()]] 方法，可以指定命令可用的选项。该方法返回控制器类的公共属性列表：
public $message;
public function options($actionID)
{
return ['message'];
}
运行命令时可以使用 --message=value 格式传递选项值。
选项别名
从 Yii 2.0.8 开始，可以通过 [[yii\console\Controller::optionAliases()]] 方法为选项定义别名：
public function optionAliases()
{
return ['m' => 'message'];
}
现在可以使用 -m 作为 --message 的别名：
./yii hello -m=hello
参数处理
动作方法可以接收参数，参数将按照位置对应传递：
// 命令 "yii example/create test" 会调用 actionCreate('test')
public function actionCreate($name) { ... }
// 带默认值的参数
public function actionIndex($category, $order = 'name') { ... }
// 数组类型参数，通过逗号分隔值
public function actionAdd(array $names) { ... }
格式化输出
Yii 控制台提供了多种格式化输出的方式，使输出更加易读。
文本样式
可以使用 [[yii\console\Controller::stdout()]] 方法和 [[yii\helpers\Console]] 类提供的常量来设置文本样式：
use yii\helpers\Console;
$this->stdout("This is bold text\n", Console::BOLD);
$this->stdout("This is red text\n", Console::FG_RED);
也可以使用 [[yii\console\Controller::ansiFormat()]] 方法格式化文本片段：
$name = $this->ansiFormat('Alex', Console::FG_YELLOW);
echo "Hello, my name is $name.";
表格输出
从 Yii 2.0.13 开始，可以使用 [[yii\console\widgets\Table]] 小部件格式化表格数据：
use yii\console\widgets\Table;
echo Table::widget([
'headers' => ['Project', 'Status', 'Participant'],
'rows' => [
['Yii', 'OK', '@samdark'],
['Yii', 'OK', '@cebe'],
],
]);
退出代码
控制台命令应返回退出代码，遵循 Unix 惯例：0 表示成功，非零值表示错误。Yii 提供了 [[yii\console\ExitCode]] 类定义常用退出代码：
public function actionIndex()
{
if (/* 出现错误 */) {
echo "A problem occurred!\n";
return ExitCode::UNSPECIFIED_ERROR;
}
// 执行成功
return ExitCode::OK;
}
高级功能
命令自动完成
Yii 从 2.0.11 版本开始为 Bash 和 ZSH 提供命令自动完成功能。
Bash 自动完成
将完成脚本安装到 /etc/bash_completion.d/ 目录：
curl -L https://raw.githubusercontent.com/yiisoft/yii2/master/contrib/completion/bash/yii -o /etc/bash_completion.d/yii
ZSH 自动完成
将 ZSH 完成脚本安装到自定义目录：
mkdir -p ~/.zsh/completion
curl -L https://raw.githubusercontent.com/yiisoft/yii2/master/contrib/completion/zsh/_yii -o ~/.zsh/completion/_yii
然后在 ~/.zshrc 中添加：
fpath=(~/.zsh/completion $fpath)
autoload -Uz compinit && compinit -i
动态配置应用
可以通过 --appconfig 选项指定自定义配置文件来执行命令：
yii migrate --appconfig=path/to/config.php
这在需要使用不同配置（如测试环境配置）执行命令时非常有用。
实际应用示例
数据库备份命令
以下是一个数据库备份命令的示例，演示了如何创建实用的控制台命令：
namespace app\commands;
use yii\console\Controller;
use yii\console\ExitCode;
use yii\helpers\Console;
class BackupController extends Controller
{
public $backupPath = '@app/backups';
public function options($actionID)
{
return ['backupPath'];
}
public function actionDb()
{
$this->stdout("Starting database backup...\n", Console::FG_CYAN);
$db = \Yii::$app->db;
$filename = $this->backupPath . '/' . date('Ymd_His') . '_db_backup.sql';
// 执行备份命令
$command = "mysqldump -u{$db->username} -p{$db->password} -h{$db->hostName} {$db->databaseName} > {$filename}";
exec($command, $output, $exitCode);
if ($exitCode === 0) {
$this->stdout("Backup completed successfully: {$filename}\n", Console::FG_GREEN);
return ExitCode::OK;
} else {
$this->stdout("Backup failed!\n", Console::FG_RED);
return ExitCode::UNSPECIFIED_ERROR;
}
}
}
运行该命令：
yii backup/db --backupPath=@app/custom_backups
总结
Yii 2 提供了强大而灵活的控制台命令支持，使开发者能够轻松创建各种后台任务。通过继承 [[yii\console\Controller]] 类，定义选项和参数，使用格式化输出，以及返回适当的退出代码，可以创建专业、易用的控制台命令。
官方文档提供了更多关于控制台命令开发的详细信息：docs/guide-zh-CN/tutorial-console.md。通过合理利用 Yii 的控制台功能，可以极大地提高开发效率和应用程序的可维护性。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
