README

Cmd 是一个简单的 PHP 命令行解析器，便于使用 PHP 创建命令行工具。

简单示例

#!/usr/bin/env php
<?php
require('vendor/autoload.php');

$cmd = new F2\Cmd\Cmd("Example tool", [
    'a|alpha'   => 'This is the description of the alpha parameter',
    '|beta'     => 'The beta parameter',
    'c'         => 'The charlie parameter',
]);

if ($cmd->flag('a')) {
    die("ALPHA!\n");
} else if ($cmd->flag('beta')) {
    die("BETA! VALUE OF c=".json_encode($cmd->value('c'))."\n");
} else if ($cmd->flag('c')) {
    die("VALUE OF c=".json_encode($cmd->value('c'))."\n");
}

echo "ALL OK!\n";

用法

# ./simple-example
ALL OK!
# ./simple-example --undeclared-option
simple-example: unrecognized option '--undeclared-option'
Try 'simple-example --help' for more information.
# ./simple-example -a
ALPHA!
# ./simple-example --alpha
ALPHA!
# ./simple-example --beta
BETA! VALUE OF c=null
# ./simple-example -c
VALUE OF c=true
# ./simple-example -c whatever
VALUE OF c='whatever'

安装

推荐安装 Fubber CMD 的方式是通过 Composer

$ composer require f2/cmd

API

构造函数

Cmd::__construct(string $usage, array $args=[], array $mandatoryParams=[]);

$usage 是您实用工具的简短描述。如果您的实用工具需要，您可以使用多行。

$args 是一个包含使用描述的参数数组。键包含由管道符（|）分隔的参数列表，其中第一部分是短选项的组：'abc|long1|long2'。对于每个短选项和每个长选项，您都可以指定冒号（:）以使选项需要值，或者使用双冒号（::）以使值可选。

数组键的格式

[
    'a:b:c:|long1:|long2:|long3:' => 'Three short and three long options that require a value',
    'a:b::|long1:|long2::' => 'A combination of required and optional value',
    '|no-short-option' => 'No short option available',
    ]

更多示例

$args = [
    'a' => 'The -a flag is boolean and can be checked with $cmd->flag('a')',
    'b:' => 'Requires a value: -b 20. Check with $cmd->value('b').'
    'd:e:' => 'Aliases for a value: -d 20 is equivalent to -e 20.',
    'f:|force:' => 'Short and long version -f 20 and --force=20.',
    '|no-short' => 'No short version, only long flag --no-short.',
    ];

$mandatoryParams 是命令末尾的必填参数列表

$mandatoryParams = [
    'what-to-say',
    ];

将产生以下输出

$ your-tool --help
your-tool <what-to-say>

标志

标志是布尔选项。它们有两种形式：短和长。

$cmd = new Cmd('Tool with flags', [
    'abc' => 'Flags -a, -b and -c',                 // -a, -b and -c are aliases now
    'd|the-d-flag' => 'Flags -d and --the-d-flag',  // -d and --the-d-flag are aliases
]);
$a = $cmd->flag('a');
$b = $cmd->flag('a');
$theDFlag = $cmd->flag('d');

选项

选项类似于标志，但它们有必填值。这是通过在定义中添加冒号（:）来实现的。

$cmd = new Cmd('Tool with options', [
    'a:b:c' => 'Option -a <value>, -b <value> and -c <value>',
    '|the-d-option' => 'Option --the-d-option=<value>',
    'e|the-e-option|the-extended-option' => 'Option -e <value>, --the-e-option=<value>, --the-extended-option=<value>',
]);
$a = $cmd->value('a');
$b = $cmd->value('b');
$c = $cmd->value('c');

带可选值的标志

带可选选项的标志在定义中用双冒号（::）标记。

$cmd = new Cmd('Tool with options', [
    'a::' => 'Option -a [value]',
    '|long-optional-option::' => 'Optional option',
]);

参数

参数是函数的必填参数。

$cmd = new Cmd('Tool with arguments', null, ['argument']);

参数可以通过内置的 PHP 全局变量 $argv 获取。您还可以访问一个已移除定义的标志和选项的 $argv 版本

print_r( $cmd->argv );

更多

您必须自己进行更高级的验证。如果有验证错误，只需使用 Cmd::error 方法简单说明错误即可。

$cmd->error("You can't combine -a with -b");

要自行显示命令用法

$cmd->usage();
die();