Yii框架官方指南系列50——专题：控制台应用

清华大佬耗费三个月吐血整理的几百G的资源，免费分享！....>>>

控制台应用主要用于实现在线Web应用所需要的离线操作,例如代码生成, 搜索索引编译, 邮件发送等等. Yii框架以面向对象的方式提供了一个编写控制台应用的框架. 它允许控制台应用访问在线Web应用所使用的资源 (例如数据库连接信息) .

1. 概览

Yii可以以命令行的方式运行每一个控制台任务，控制台命令是一个继承自CConsoleCommand的类。

当我们使用 yiic webapp 工具创建一个初始化的Yii应用骨架的时候, 我们可以在protected文件夹下看到如下两个文件:

• yiic: 这是一个运行在Linux/Unix上的可执行脚本;
• yiic.bat: 这是一个运行在Windows上的可执行批处理脚本.

在控制台窗口中, 我们可以输入如下命令:

cd protected
yiic help

这将会显示一系列的控制台命令。默认情况下，这些有效的命令包括由Yii框架提供的（系统命令）和开发者自己为独立应用编写的（用户命令）。

如果想要查看如何使用一个命令, 可以使用：

yiic help <command-name>

要执行一个命令, 可以使用如下的命令格式：

yiic <command-name> [parameters...]

2. 创建命令

控制台命令以类文件的形式保存形如CConsoleApplication::command的路径下. 默认情况下, 指向文件夹protected/commands.

一个控制台命令类必须继承自CConsoleCommand. 这个类名必须是XyzCommand的格式, 其中 Xyz 代表首字母大写的命令名称. 例如, 一个sitemap 命令必须使用类名 SitemapCommand。控制台命令名是大小写敏感的.

Tip: 通过配置 CConsoleApplication::command匹配, 可以获取以不同形式命名、存储在不同文件夹下的命令类.

为了创建一个新的命令,需要经常重写 CConsoleCommand::run() 或者开发一个或者多个命令动作。

当执行一个控制台命令时，CConsoleCommand::run()方法将会被控制台应用调用。所有控制台参数也会以如下方法片段的形式传入这个方法：

public function run($args) { ... }

其中 $args 代表命令行给定的额外参数。

在控制台命令中, 我们可以使用 Yii::app()来访问控制台应用实例, 不仅如此我们还可以访问资源如数据库连接 (e.g. Yii::app()->db). 可以看到这种用法和在Web应用中的使用非常类似。

Info: 从版本1.1.1开始, 我们还可以创建被同一台机子上所有的Yii应用共享的全局命令：定义一个命名为 YII_CONSOLE_COMMANDS的环境变量指向一个已存在的文件夹，然后将我们的全局命令类放到这个文件夹下即可。

3. 控制台命令动作（action）

Note: 这个控制台命令动作特性从版本1.1.5后有效。

一个控制台命令经常需要处理不同的命令行参数, 有些是必须的，有些是可选的. 控制台命令还需要提供一些子命令来处理不同的子任务。这些工作可以简化使用控制台命令动作。

一个控制台命令动作是一个控制台命令类中的方法. 这个方法名必须是actionXyz的格式, 其中Xyz 代表首字母大写的动作名. 例如, 一个actionIndex方法定义了一个命名为index的动作.

想要执行特定的动作, 我们可以使用如下的命令行格式:

yiic <command-name> <action-name> --option1=value1 --option2=value2 ...

额外的 option-value 对将为以命名参数的方式传入动作方法中. 一个xyz 操作的值将会以$xyz参数的形式传入到动作方法中。例如, 如果我们定义了如下的命令类:

class SitemapCommand extends CConsoleCommand
{
    public function actionIndex($type, $limit=5) { ... }
    public function actionInit() { ... }
}

然后，下面的控制台命令在调用actionIndex('News', 5)的时候都会有结果:

yiic sitemap index --type=News --limit=5

// $limit takes default value
yiic sitemap index --type=News

// $limit takes default value
// because 'index' is a default action, we can omit the action name
yiic sitemap --type=News

// the order of options does not matter
yiic sitemap index --limit=5 --type=News

如果一个操作没有指定值(e.g. --type instead of --type=News), 相应的动作参数值将会假定为true。

Note: 不支持可选的参数格式 --type News, -t News.

一个参数值可以是数组（必须要有数组类型提示）:

public function actionIndex(array $types) { ... }

在命令行参数中想要使用数组值, 只需简单重复同一个选项:

yiic sitemap index --types=News --types=Article

上面的命令最终将会调用actionIndex(array('News', 'Article')).

从版本 1.1.6开始, Yii 还支持使用匿名动作参数和全局选项.

匿名参数表示这些命令行参数不是以选项的形式呈现. 例如, 在命令 yiic sitemap index --limit=5 News中, 我们有一个值为News的匿名参数和命名参数 limit，其值为5。

为了使用匿名参数, 一个命令动作必须声明参数为 $args的形式. 例如,

public function actionIndex($limit=10, $args=array()) {...}

$args数组将会装入所有的匿名参数值.

全局选项代表那些命令行选项可以被一个命令中所有动作共享的选项. 例如, 在一个命令中提供了多个选项, 我们可能想要每一个动作识别一个名为verbose的动作. 当然我们可以在每一个动作方法中声明 $verbose 参数, 一个更好的方式是将其声明为这个命令类的公有成员变量, 将 verbose 转换为全局参数:

class SitemapCommand extends CConsoleCommand
{
    public $verbose=false;
    public function actionIndex($type) {...}
}

上面的代码允许我们执行一个带 verbose 选项的命令:

yiic sitemap index --verbose=1 --type=News

4. 退出代码

Note: 在控制台命令中退出代码的特性从版本 1.1.11起有效.

通过cronjob或者使用一个持续集成的服务器自动运行控制台命令的时候, 要么命令运行运行成功，要么命令运行失败. 这可以通过检查进程返回的退出代码来查看。

这些退出码是从0-254的整型值(this is the range in php world), 其中 0 表示退出成功其他的所有非0值表示出现了错误.

在一个动作方法或者控制台命令的 run() 方法中你可以在退出时返回整型值退出码 ，例如:

if (/* error */) {
    return 1; // exit with error code 1
}
// ... do something ...
return 0; // exit successfully

如果没有返回值, 应用将会退出返回 0.

5. 自定义控制台应用

默认情况下, 如果一个应用是使用yiic webapp工具创建的, 命令行应用的配置将会放在 protected/config/console.php文件中. 和一个Web应用配置文件一样, 这个文件是一个返回控制台应用实例的初始化配置值的数组的PHP脚本。所以CConsoleApplication的任何公有属性都可以在该文件中配置.

因为控制台命令经常被创建来服务于Web应用, 所以需要访问资源（如数据库连接）。我们可以在控制台配置文件中以如下方式来实现 ：

return array(
    ......
    'components'=>array(
        'db'=>array(
            ......
        ),
    ),
);

正如我们所看到的那样, 配置的格式和我们在Web应用中的配置类似.这是因为CConsoleApplication和 CWebApplication 的基类相同。