README

此库是一个命令行参数解析器，可以在不查看文档的情况下合理使用。

特性

• 显式声明。
• 支持必需、可选和多个值。
• 检查值类型。
• 简单标记。
• 自动生成使用说明。

安装

待编写

用法

方法链声明

ping 命令的示例。
如果您想看其他示例，请参阅 examples/chain/ 目录下的脚本。

<?php
use PhpFlags\Parser;
use PhpFlags\Spec\ApplicationSpec;

// example ping
$spec = ApplicationSpec::create();
$spec->version('1.0.0')->clearShort();
$count = $spec->flag('count')->short('c')->default(-1)
    ->desc('Number of times to send an ICMP request. The default of -1 sends an unlimited number of requests.')
    ->validRule(function($count) {
        return $count >= -1;
    })
    ->int('request count');
$timeout = $spec->flag('timeout')->short('t')->default(5)
    ->desc('Timeout seconds for ICMP requests.')
    ->validRule(function($timeout) {
        return $timeout >= 0;
    })
    ->int('request count');
$verbose = $spec->flag('verbose')->short('v')
    ->desc('verbose output.')
    ->bool();
$host = $spec->arg()
    ->desc('IP of the host for the ICMP request.')
    ->validRule(function($ip){
        return preg_match('/^(([1-9]?[0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5]).){3}([1-9]?[0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$/', $ip);
    })
    ->string('host');
try {
    Parser::create($spec)->parse($argv);
} catch (PhpFlags\InvalidArgumentsException $e) {
    echo $e->getMessage(), PHP_EOL;
    exit(1);
} catch (PhpFlags\InvalidSpecException $e) {
    echo $e->getMessage(), PHP_EOL;
    exit(1);
}
echo "  count: ", $count->get(), PHP_EOL;
echo "timeout: ", $timeout->get(), PHP_EOL;
echo "verbose: ", $verbose->get() ? 'true' : 'false', PHP_EOL;
echo "   host: ", $host->get(), PHP_EOL;

# If the option is not defined in the argument, the default value is taken.
$ php ping.php 127.0.0.1
  count: -1
timeout: 5
verbose: false
   host: 127.0.0.1

# If a flag is specified, the value is stored in the corresponding object.
   $ php ping.php -c 3 -t 10 -v 127.0.0.1
or $ php ping.php -c=3 -t=10 -v 127.0.0.1
  count: 3
timeout: 10
verbose: true
   host: 127.0.0.1

# InvalidArgumentsException is thrown 
# if a validRule is violated or the type of the passed value does not match the specified type. 
$ php ping.php -t=foo 127.0.0.1
The values does not matched the specified type. expect_type:int, given_type:string, value:foo

$ php ping.php -t=-1 127.0.0.1
invalid by validRule. flag:--timeout, value:-1

用法会自动生成，无需任何特殊配置。

   $ php ping.php --help
or $ php ping.php -h
Usage:
        php ping.php [FLAG]... (host)

FLAG:
        -c [request count], --count[=request count]
                Number of times to send an ICMP request. The default of -1 sends an unlimited
                number of requests.

        -t [timeout second], --timeout[=timeout second]
                Timeout seconds for ICMP requests.

        -v, --verbose
                verbose output.

ARG:
        host
                IP of the host for the ICMP request.

由于版本已定义，您可以使用 --version 标志检查版本。

$ php ping.php --version
version 1.0.0

文档

支持类型

• int
• float
• bool
• string
• date

构建标志和参数选项

构建标志附加选项

帮助标志附加选项

版本标志附加选项

自定义帮助

默认情况下，帮助已定义，标志包括 --help 和 -h。
如果这些标志在命令行中指定，它通常会输出格式化的帮助消息，并在解析时退出，状态码为 0。
可以更改标志并自定义指定它们时的行为。

如果您想查看更多信息，请参阅 examples/chain/customVersionHelp.php 目录下的脚本。

<?php

use PhpFlags\Spec\ApplicationSpec;

$appSpec = ApplicationSpec::create();
$appSpec->help()->long('show-help')->short('s')
    ->action(function ($helpMessage) {
        fputs(STDERR, $helpMessage);
        exit(1);
    });
$appSpec->flag('example-flag')->desc('example flag declaration')->int();
$appSpec->arg()->desc('example arg declaration')->int('EXAMPLE-ARG');
// ...

将标志值从 "help" 更改为 "show-help"，短标识从 "h" 更改为 "s"，并将退出状态码从 "0" 更改为 "1"。

   $ php examples/chain/customVersionHelp.php --show-help; echo $?
or $ php examples/chain/customVersionHelp.php -s; echo $?
Usage:
        php examples/chain/customVersionHelp.php --example-flag=int [FLAG]... (EXAMPLE-ARG)

FLAG:
        --example-flag=int
                example flag declaration

ARG:
        EXAMPLE-ARG
                example arg declaration

1 # return exit 1 status code

自定义版本

将标志值从 "version" 更改为 "ver"，短标识从 "v" 更改为大写 "V"，并将退出状态码从 "0" 更改为 "1"。

<?php

use PhpFlags\Spec\ApplicationSpec;

$appSpec = ApplicationSpec::create();
$appSpec->version('1.0')->long('ver')->short('V')
    ->format('app version: {{VERSION}}')
    ->action(function ($versionMessage) {
        fputs(STDERR, $versionMessage);
        exit(1);
    });
// ...

   $ php examples/chain/customVersionHelp.php --ver; echo $?
or $ php examples/chain/customVersionHelp.php -V; echo $?
app version: 1.0
1 # return exit 1 status code