创建 Spark 命令

虽然像任何其他路由一样通过 CLI 使用控制器很方便，但您可能会发现有时需要一些不同的东西。这就是 Spark 命令的用武之地。它们是简单的类，不需要为其定义路由，这使得它们非常适合构建开发人员可以用来简化工作流程的工具，无论是处理迁移或数据库播种，检查 cronjob 状态，甚至构建您公司的自定义代码生成器。

创建新命令 

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

为了在 CLI 命令中列出并为您的命令添加帮助功能，应使用以下属性

$group: 一个字符串，用于描述在列出命令时命令归入的组。例如：Database
$name: 用于描述命令名称的字符串。例如：make:controller
$description: 用于描述命令的字符串。例如：Generates a new controller file.
$usage: 用于描述命令用法的字符串。例如：make:controller <name> [options]
$arguments: 用于描述每个命令参数的字符串数组。例如：'name' => 'The controller class name.'
$options: 用于描述每个命令选项的字符串数组。例如：'--force' => 'Force overwrite existing file.'

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

文件位置 

命令必须存储在名为 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() 方法的 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。如果在执行命令时遇到错误，可以使用 return 语言结构在 run() 方法中返回退出代码来终止命令。

例如，return EXIT_ERROR;

这种方法可以帮助在系统级别进行调试，例如，如果命令是通过 crontab 运行的。

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

BaseCommand 

所有命令必须扩展的 BaseCommand 类包含一些有用的实用程序方法，在创建自己的命令时应该熟悉这些方法。它还提供了一个 Logger，可以在 $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 命令

创建新命令

文件位置

示例命令

run()

命令终止

BaseCommand

创建新命令 

文件位置 

示例命令 

BaseCommand 