README

在PHP中将命令行字符串拆分为命令参数数组的简单方法。

您想在PHP中构建一个交互式的命令行界面（CLI）工具，该工具从STDIN读取基于行的用户输入，现在您想将此命令行分解为其单独的命令参数？那么这个库就是为您准备的！

这类似于当您执行 ./example.php "hello world" 时，bash（或您选择的终端）为您做的事情，它随后启动您的脚本并向它传递一个单独的参数。如果您只需要在启动时这样做，那么使用您的 $argv 可能就足够了。但许多其他工具在它们的运行时可能也需要类似的解析。

支持我们
快速入门示例
用法
- split()
- UnclosedQuotesException
安装
测试
许可
更多

支持我们

我们在开发、维护和更新我们出色的开源项目上投入了大量的时间。您可以通过在GitHub上成为赞助商来帮助我们保持我们工作的高质量。赞助商将获得许多回报，请参阅我们的赞助页面了解详细信息。

让我们一起把这些项目提升到新的水平！🚀

快速入门示例

以下示例代码演示了如何使用此库构建一个非常简单的交互式命令行界面（CLI）工具，该工具接受用户输入的命令行（通过 STDIN），然后执行一些非常简单的演示命令

<?php

require __DIR__ . '/vendor/autoload.php';

while (true) {
    $line = fgets(STDIN, 1024);

    $args = Clue\Arguments\split($line);
    $command = array_shift($args);

    if ($command === 'exit') {
        break;
    } elseif ($command === 'sleep') {
        sleep($args[0]);
    } elseif ($command === 'echo') {
        echo join(' ', $args) . PHP_EOL;
    } else {
        echo 'Invalid command' . PHP_EOL;
    }
}

另请参阅示例。

用法

这个轻量级的库仅包含一个简单的函数。所有内容都位于 Clue\Arguments 命名空间下。

以下示例假设您使用类似于以下的导入语句

use Clue\Arguments;

Arguments\split(…);

或者，您也可以使用它们的完全限定名来引用它们

\Clue\Arguments\split(…);

split()

可以使用 split(string $line) : array 函数将给定的命令行字符串拆分为任何单个命令参数字符串数组。

对于以下示例，让我们假设我们想要像这样处理一个简单的 addUser 命令

// example command syntax:
// addUser <username> <realname> <homepage> <comment>

$line = 'adduser example Demo example.com Hi!';

$args = Arguments\split($line);

assert(count($args) === 5);
assert($args[0] === 'adduser');
assert($args[1] === 'example');
assert($args[2] === 'Demo');
assert($args[3] === 'example.com');
assert($args[4] === 'Hi!');

虽然这个简单的示例看起来像是简单调用 $args = explode(' ', $line) 的工作，但 split() 函数实际上要复杂得多。它还支持解析以下内容

单引号字符串（'hello world'），它保留任何空白字符，并且只接受转义序列 \\ 和 \'，例如 'let\'s go'。
双引号字符串（"hello world"），它保留任何空白字符，并支持常见的转义序列，如 \t\r\n 等，Unicode 转义序列，如 \u0020，十六进制转义序列，如 \x20 和八进制转义序列，如 \040，例如 "hi there\nworld!"。
未引用的字符串在下一个（未转义的）空白字符处终止，并像双引号字符串一样支持常见的转义序列，例如 hi\ there\nworld!。
忽略参数周围的过多空白，例如尾随空白或参数之间的多个空格。
对输入编码的假设非常少，因此允许输入包含原始二进制数据以及完整的UTF-8（Unicode）支持。Unicode字符可以是正常的UTF-8字符串，例如hällö，也可以是双引号和未引号字符串中的Unicode转义序列，例如h\u00e4ll\u00f6。

例如，这意味着以下内容也可以按预期解析

$line = 'adduser clue \'Christian Lück\' https://lueck.tv/ "Hällo\tWörld\n"';

$args = Arguments\split($line);

assert(count($args) === 5);
assert($args[0] === 'adduser');
assert($args[1] === 'clue');
assert($args[2] === 'Christian Lück');
assert($args[3] === 'https://lueck.tv');
assert($args[4] === "Hällo\tWörld\n");

验证任何参数（检查长度或值范围等）留给了更高层次，即这个库的消费者。这也允许你明确地传递空参数，例如这样

$line = 'sendmail "" clue';

$args = Arguments\split($line);

assert(count($args) === 3);
assert($args[0] === 'sendmail');
assert($args[1] === '');
assert($args[2] === 'clue');

解析空输入行或只包含空白的输入行将返回一个空数组

$line = "\r\n";

$args = Arguments\split($line);

assert(count($args) === 0);

解析含有不平衡引号（即一个带引号的参数开始而没有结束引号）的输入行，这将抛出UnclosedQuotesException。这可以用于要求用户纠正他们的输入

$line = 'sendmail "hello world';

try {
    Arguments\split($line);
    // throws RuntimeException
} catch (Arguments\UnclosedQuotesException $e) {
    echo 'Please check your input.';
}

如果您想（尝试）自动纠正用户输入行，请参阅以下章节。

UnclosedQuotesException

UnclosedQuotesException将在输入行含有不平衡引号（即一个带引号的参数开始而没有结束引号）时，由split()函数引发。

此类扩展PHP的InvalidArgumentException。

可以使用getQuotes(): string方法获取此参数开始的引号

$quotes = $e->getQuotes();

例如，这可以用来（尝试）纠正用户输入行，例如这样

$line = 'sendmail "hello world';

try {
    $args = Arguments\split($line);
    // throws RuntimeException
} catch (Arguments\UnclosedQuotesException $e) {
    // retry parsing with closing quotes appended
    $args = Arguments\split($line . $e->getQuotes());
}

注意：输入行可能以反斜杠结尾，在这种情况下，附加的关闭引号实际上会被标记为转义。您可以选择自行处理这些，或将此代码块包裹在另一个try-catch中。

可以使用getPosition(): int方法获取引号在输入字符串中的字符位置。在之前的例子中，这将是在$line[9]

$pos = $e->getPosition();

assert($pos === 9);
assert($line[$pos] === $e->getQuotes());

安装

推荐通过Composer安装此库。您是Composer的新手吗？初学者指南？

此项目遵循SemVer。这将安装最新支持的版本

composer require clue/arguments:^2.1

有关版本升级的详细信息，请参阅变更日志。

此项目旨在在任何平台上运行，因此不需要任何PHP扩展，并支持在旧版PHP 5.3到当前PHP 8+和HHVM上运行。强烈建议使用此项目支持的最新PHP版本。

测试

要运行测试套件，首先需要克隆此仓库，然后通过Composer安装所有依赖项

composer install

要运行测试套件，请转到项目根目录并运行

vendor/bin/phpunit

许可

此项目在MIT许可下发布。

你知道吗？我提供定制开发服务，并为发行版赞助和贡献发布发票。请联系我（@clue）以获取详细信息。

如果您想注册/路由可用的命令及其参数，您可能需要查看使用clue/commander。
如果您想构建交互式CLI工具，您可能需要查看使用clue/reactphp-stdio以响应用户从STDIN发出的命令。

clue / arguments

维护者

详细信息

README

支持我们

快速入门示例

用法

split()

UnclosedQuotesException

安装

测试

许可

更多