创建 Spark 命令

虽然能够像其它路由一样通过 CLI 使用控制器很方便,但你可能会发现有时需要一些不同的东西。这就是 Spark 命令的用武之地。它们是简单的类,不需要为它们定义路由,使其成为构建可以帮助开发人员简化工作的工具的完美选择,无论是通过处理迁移或数据库填充,检查任务状态,甚至为你的公司构建定制代码生成器。

创建新命令 

你可以非常轻松地创建新的命令供自己开发使用。每个类必须在其自己的文件中,并且必须扩展 CodeIgniter\CLI\BaseCommand,并实现 run() 方法。

应使用以下属性将命令列入 CLI 命令并添加帮助功能:

$group:描述命令分组的字符串。例如:数据库
$name:描述命令名称的字符串。例如:make:controller
$description:描述命令的字符串。例如:生成一个新的控制器文件。
$usage:描述命令用法的字符串。例如:make:controller <name> [options]
$arguments:描述每个命令参数的字符串数组。例如:'name' => '控制器类名。'
$options:描述每个命令选项的字符串数组。例如:'--force' => '强制覆盖现有文件。'

帮助描述将根据上述参数自动生成。

文件位置 

命令必须存储在名为 Commands 的目录中。但是,该目录必须位于 PSR-4 命名空间中,以便自动加载程序可以定位它。这可能在 app/Commands 中,或者是一个用于所有项目开发的命令目录,像 Acme/Commands。

备注

当执行命令时,会加载完整的 CodeIgniter CLI 环境,使你可以获取环境信息、路径信息,并使用控制器中会使用的任何工具。

一个示例命令 

让我们逐步创建一个示例命令,其唯一的功能是报告有关应用程序本身的一些基本信息,以演示用途。首先在 app/Commands/AppInfo.php 中创建一个新文件。它应该包含以下代码:

<?php

namespace App\Commands;

use CodeIgniter\CLI\BaseCommand;
use CodeIgniter\CLI\CLI;

class AppInfo extends BaseCommand
{
    protected $group       = 'Demo';
    protected $name        = 'app:info';
    protected $description = 'Displays basic application information.';

    public function run(array $params)
    {
        // ...
    }
}

如果运行 list 命令,你将在自己的 Demo 组下看到新命令被列出。如果仔细看,应该可以相当容易地理解它的工作方式。$group 属性简单地告诉它如何组织此命令与所有其他存在的命令,告诉它在哪个标题下列出它。

$name 属性是可以调用此命令的名称。唯一的要求是它不得包含空格,并且所有字符在命令行本身必须有效。不过,按照惯例,命令应该是小写的,并且通过在命令名称本身使用冒号进一步对命令进行分组,以帮助防止多个命令发生命名冲突。

最后一个属性 $description 是一个简短的字符串,在 list 命令中显示,并应描述命令的作用。

run()

run() 方法是在运行命令时调用的方法。$params 数组是命令名称后面的任何 CLI 参数列表,供你使用。如果 CLI 字符串是:

php spark foo bar baz

那么 foo 是命令名称, $params 数组将是:

<?php

$params = ['bar', 'baz'];

这也可以通过 CLI 库访问,但这里已经从字符串中删除了你的命令。这些参数可以用于自定义脚本的行为方式。

我们的演示命令可能有一个 run() 方法,如下所示:

<?php

namespace App\Commands;

use CodeIgniter\CLI\BaseCommand;
use CodeIgniter\CLI\CLI;

class AppInfo extends BaseCommand
{
    // ...

    public function run(array $params)
    {
        CLI::write('PHP Version: ' . CLI::color(PHP_VERSION, 'yellow'));
        CLI::write('CI Version: ' . CLI::color(\CodeIgniter\CodeIgniter::CI_VERSION, 'yellow'));
        CLI::write('APPPATH: ' . CLI::color(APPPATH, 'yellow'));
        CLI::write('SYSTEMPATH: ' . CLI::color(SYSTEMPATH, 'yellow'));
        CLI::write('ROOTPATH: ' . CLI::color(ROOTPATH, 'yellow'));
        CLI::write('Included files: ' . CLI::color(count(get_included_files()), 'yellow'));
    }
}

请参阅 CLI 库页面了解详细信息。

命令终止

默认情况下,命令以成功代码 0 退出。如果在执行命令时遇到错误,你可以通过在 run() 方法中使用 return 语句和退出代码来终止命令。

例如, return EXIT_ERROR;

这种方法可以帮助系统级调试,如果命令例如通过 crontab 运行。

你可以使用 app/Config/Constants.php 文件中定义的 EXIT_* 退出代码常量。

BaseCommand 

所有命令必须扩展的 BaseCommand 类有一些你应该熟悉的有用实用方法,当创建自己的命令时。它还具有可以通过 $this->logger 访问的日志。

class CodeIgniter\CLI\BaseCommand

call(string $command[, array $params = []])
参数:

$command (string) – 要调用的另一个命令的名称。

$params (array) – 要传递给该命令的其他 CLI 参数。

此方法允许你在当前命令执行期间运行其他命令:
<?php

$this->call('command_one');
$this->call('command_two', $params);
showError(Throwable $e)
参数:

$e (Throwable) – 用于报告错误的异常。

一种保持 CLI 错误输出一致且清晰的便捷方法:
<?php

try {
    // ...
} catch (\Exception $e) {
    $this->showError($e);
}
showHelp()

显示命令帮助的方法:(用法、参数、描述、选项)
setPad(string $item, int $max, int $extra = 2, int $indent = 0) → string
参数:

$item (string) – 字符串项目。

$max (integer) – 最大长度。

$extra (integer) – 在末尾添加的额外空格数。

$indent (integer) – 缩进空格数。

填充我们的字符串,以便所有标题的长度相同,以美观地排列描述:
use CodeIgniter\CLI\CLI;

$length = max(array_map('strlen', array_keys($this->options)));

foreach ($this->options as $option => $description) {
    CLI::write(CLI::color($this->setPad($option, $length, 2, 2), 'green') . $description);
}
/*
 * Output will be:
 *  -n     Set migration namespace
 *  -g     Set database group
 *  --all  Set for all namespaces, will ignore (-n) option
 */

getPad($array, $pad)

自 4.0.5 版本弃用: 请使用 CodeIgniter\CLI\BaseCommand::setPad()。

参数:

$array (array) – $key => $value 数组。
$pad (integer) – 填充的空格数。

计算用于 $key => $value 数组输出的填充的方法。该填充可用于在 CLI 中输出格式良好的表格。

创建 Spark 命令

创建新命令

文件位置

一个示例命令