README

PHP-CLI是一个简单的库，可以帮助创建外观美观的命令行脚本。

它负责

选项解析
帮助页面生成
自动宽度调整
彩色输出
可选PSR3兼容性

它轻量级且没有第三方依赖。注意：这仅适用于非交互式脚本。它不支持readline或类似功能。

安装

使用composer

php composer.phar require splitbrain/php-cli

用法和示例

最小示例

#!/usr/bin/php
<?php
require __DIR__ . '/../vendor/autoload.php';
use splitbrain\phpcli\CLI;
use splitbrain\phpcli\Options;

class Minimal extends CLI
{
    // register options and arguments
    protected function setup(Options $options)
    {
        $options->setHelp('A very minimal example that does nothing but print a version');
        $options->registerOption('version', 'print version', 'v');
    }

    // implement your code
    protected function main(Options $options)
    {
        if ($options->getOpt('version')) {
            $this->info('1.0.0');
        } else {
            echo $options->help();
        }
    }
}
// execute it
$cli = new Minimal();
$cli->run();

基本用法很简单

创建一个类并 扩展 splitbrain\phpcli\CLI
实现 setup($options) 方法并注册选项、参数、命令并设置帮助文本
- $options->setHelp() 添加一个通用描述
- $options->registerOption() 添加一个选项
- $options->registerArgument() 添加一个参数
- $options->registerCommand() 添加一个子命令
实现 main($options) 方法并在其中进行业务逻辑处理
- $options->getOpts 允许您访问设置的选项
- $options->getArgs() 返回移除选项后的剩余参数
- $options->getCmd() 返回用户使用的子命令
实例化您的类并对其调用 run()

更多示例可以在示例目录中找到。请参阅 API文档以获取更多信息。

异常

默认情况下，CLI类会注册一个异常处理程序，并将异常消息打印给最终用户，然后以非零退出代码退出程序。您可以通过将false传递给构造函数来禁用此行为并自己捕获所有异常。

您可以使用提供的 splitbrain\phpcli\Exception 在主代码中自己发出任何问题的信号。异常代码将用作退出代码。

堆栈跟踪将在日志级别 debug 时打印。

彩色输出

彩色输出通过 Colors 类处理。它会尝试检测是否存在彩色终端，并且只有在存在彩色终端的情况下才使用终端颜色。您始终可以通过在脚本中传递 --no-colors 来抑制彩色输出。禁用颜色也会禁用表情符号前缀。

您可以使用方便的方法 success()（绿色）、info()（青色）、error()（红色）或 fatal()（红色）来打印简单的彩色日志消息。后者还会以非零退出代码退出程序。

对于更复杂的着色，您可以在脚本中使用 $this->colors 访问颜色类。您可能想要使用 wrap() 方法。

表格格式化程序允许着色整个列。要使用该机制，请将颜色数组作为第三个参数传递给其 format() 方法。请注意，您不能在第二个参数中传递彩色文本（文本长度计算和包装将失败，破坏您的文本）。

表格格式化程序

TableFormatter 类允许您在多列中对文本进行对齐。它会尝试自行确定可用的终端宽度。可以通过设置 COLUMNS 环境变量来覆盖它。

格式化器通过format()方法使用，该方法至少期望两个数组：第一个定义列宽，第二个包含要填充到列中的文本。在每个列之间打印一条边框（默认情况下为单个空格）。

请参阅example/table.php以获取示例用法。

列宽可以以三种形式给出

通过提供整数（例如15）指定固定字符宽度
通过提供整数和百分号（例如25%）指定百分比
使用星号（例如*）标记的单个流体“剩余”列

当混合固定和百分比宽度时，百分比指的是在分配所有固定列之后的剩余空间。

边框的空间会自动计算。建议始终保留一些相对（百分比）或流体列以适应不同的终端宽度。

表格格式化器用于在通过-h或--help调用脚本时访问的自动帮助屏幕。

PSR-3 日志记录

CLI 类是一个完全符合 PSR-3 的记录器（将彩色日志数据打印到 STDOUT 和 STDERR）。当你从 CLI 调用需要 Logger 实例以产生运行时任何有意义的状态输出的后端代码时，这很有用。

如果你需要传递实现Psr\Log\LoggerInterface的类，你可以通过继承实现此接口的两个提供的类之一，而不是splitbrain\phpcli\CLI。

如果你使用的是 PSR3 的第 2 版（PHP < 8.0），请使用splitbrain\phpcli\PSR3CLI
如果你使用的是 PSR3 的第 3 版（PHP >= 8.0），请使用splitbrain\phpcli\PSR3CLIv3

然后可以将生成的对象作为记录器实例传递。两者之间的区别仅在于调整了方法签名（带有适当的类型提示）。在使用这些类时，请确保已安装建议的psr/log composer 包。

注意：如果你的后端代码要求使用 PSR-3 记录器但实际上并没有对接口进行类型检查（即仅是 LoggerAware），你也可以直接传递splitbrain\phpcli\CLI的一个实例。

日志级别

您可以使用--loglevel参数调整 CLI 工具的详细程度。支持的日志级别是 PSR-3 日志级别以及我们的success级别

debug
info
notice
success（这不是 PSR-3 中定义的）
warning
error
critical
alert
emergency

所有日志级别都提供了方便的方法。也提供了 PSR-3 中描述的占位符插值。从warning级别开始的消息将打印到STDERR，而所有以下消息将打印到STDOUT。

可以通过覆盖$logdefault成员来设置脚本的默认日志级别。

请参阅example/logging.php以获取示例。

splitbrain / php-cli

维护者

详细信息