README

PHP库，用于处理命令行参数

它设计用于提供安全检索大多数常见参数类型的方法，包括字符串、整数、浮点值、布尔标志、关键词集、文件名、主机名、IP地址和电子邮件地址。

它对于处理在shell命令行中提供给PHP脚本的参数非常有用，例如。

YourPrompt$ ./example.php Hello, world.

或者它可能指的是进入基于PHP的REPL（例如自定义管理工具）的命令的参数。

安装

您可以直接使用Composer要求它

composer require jdwx/args

或从GitHub下载源代码：https://github.com/jdwx/args.git

需求

此库需要PHP 8.2或更高版本。它可能与PHP 8的早期版本兼容，但尚未对其进行了测试。

用法

<?php

declare( strict_types = 1 );

require 'vendor/autoload.php';

$args = new JDWX\Args\Arguments( $argv );

$st = $args->shiftString();
# Based on the shell example above, $st now equals "Hello,"

所有“shift”方法如果在存在但无效的参数时抛出异常

$args = new JDWX\Args\Arguments( [ 'not-an-email-address' ] );
try {
    $email = $args->shiftEmailAddress();
} catch ( JDWX\Args\BadArgumentException $e) {
    echo "Not a valid email address: ", $e->getValue(), "\n";
}

此类方法的默认形式在不存在更多参数时返回null，这在while循环迭代中非常有用

while ( $i = $args->shiftInteger() ) {
    echo "Got integer: $i\n";
}

shift方法还提供了一种变体，如果不存在更多参数则抛出异常。这有助于确保存在所需参数

while ( $st = $args->shiftString() ) {
    $i = $args->shiftIntegerEx();
    assert( is_int( $i ) );
    echo "Got: $st => $i\n";
}

还可能在不一定消费它的情况下“查看”下一个参数。这支持匹配特定前缀的字符串

# If the next argument is "prefix_example," $st will be set to "example."
# In this example, the consume flag is not set, so the argument will not
# be consumed.
if ( $st = $args->peekString( 'prefix_' ) ) {
    echo "Got: $st\n";
    $st2 = $args->shiftString();
    assert( $st2 === $st ); # Argument was not consumed.
} else {
    echo "Nope!\n";
}

或对于关键词集的字符串

$rKeywords = [ 'example', 'demo', 'test' ];
# If the next argument is "example," $st will be set to "example." In this example,
# the consume flag is set so the argument is consumed if (and only if) it matches.
# The default is kept as false for consistency with peekString(), but usually
# you do want to consume keyword-matching arguments.
if ( $st = $args->peekKeywords( $rKeywords, i_bConsume: true ) ) {
    echo "Got: $st\n";
} else {
    echo "Nope!\n";
}

库还提供了处理以两个连字符开始的可选Gnu风格参数的处理（例如，--example）

$args = new JDWX\Args\Arguments( $argv );
$rOptions = $args->handleOptions();
if ( in_array( 'help', $rOptions ) ) {
    echo "Usage: $argv[0] [options] [arguments]\n";
    echo "Options:\n";
    echo "  --help    Display this help message\n";
    exit( 0 );
}

handleOptions()方法支持布尔标志（例如，--flag和--no-flag）以及需要值（例如，--key=value）的参数。

handleOptions()方法从列表中删除已解析的参数，允许剩余的参数按常规处理。

它不支持短选项（例如，-h）或需要在下一个参数中指定值的选项（例如，-k value）。

稳定性

此库被认为是稳定的，并且在生产代码中使用。未来可能会添加额外的解析方法，但现有方法不应以破坏向后兼容性的方式删除或更改。可能会发生异常来解决安全问题或错误，但预计将很少发生。

历史

此库已经使用了多年。它于2023年从更大的代码库重构出来，并于2024年首次作为独立库发布。