README

1. 简介

PHP 命令行参数解析器。

在开发 PHP 可执行命令行脚本时，我们可能试图实现以下目标

告诉用户可用的选项
捕获用户作为命令参数传递的值
如果未提供选项，提示用户输入
允许使用短选项名和长选项名（例如 -h 和 -help）
验证选项值，如果无效，则显示错误消息或要求用户重新输入

Dlin\Getopt 是为了让您摆脱编写所有这些重复任务而设计的。

2. 安装

使用 composer，将其添加到您的 composer.json 中

{
    require: {
        "dlin/getopt": "dev-master"
    }
}

对于不使用 composer 的人

下载此包
将文件 /src/Dlin/Getopt/getopt_inc.php 包含到您的脚本中。

3. 基本用法

以下部分使用的示例假设我们正在处理一个名为 myScript.php 的命令行 PHP 脚本

构造函数

Geocoder 类的构造函数接受一个可选的选项配置数组作为参数。请参阅配置部分以了解选项配置设置。

//include composer autoload or getopt_inc.php
include './vendor/autoload.php';

$configs = array();
$configs[] = array('arg'=>'s'); //script accepts a 's' option i.e. -s
$configs[] = array('arg'=>'t'); //script accepts a 't' option, i.e. -t

$getOpt = new GetOpt(configs);

或者您可以在创建实例后设置选项配置

$getOpt = new GetOpt();
$getOpt->setOption(array('arg'=>'s'));
$getOpt->setOption(array('arg'=>'t'));

$getOpt->parse();

在命令行传递选项参数

在命令行提供的选项参数必须是以下格式之一

短格式：'-' 后跟单个字母。例如 -h
长格式：'--' 后跟多个字母。例如 --help

字符串格式无效的选项将被视为普通参数

选项参数值是选项参数字符串之后的第一个参数。无论值是否以空格开头都无关紧要。然而，值不能包含任何空格。

如果未提供匹配的选项参数（例如 -h 或 --help），它将通过 '_' 属性在脚本中可用。（见下一节）

在脚本中获取选项值

- 可解析选项

//php myScript.php -s 10 -t int foo bar zee

echo $getOpt->t; // output int
echo $getOpt->s; // output 10
echo $getOpt->foo; //null
echo $getOpt->nonexist; //null

- 不可解析选项

'_'（下划线）属性包含一个其他不可解析参数的数组

//php myScript.php -s 10 -t int foo bar zee

echo $getOpt->_; //Array with values ['foo', 'bar', 'zee']

- 无效选项参数

无效选项参数可能会导致意外结果

//php myScript.php --s 10 -type int   (wrong)

echo $getOpt->s; // null
echo $getOpt->type; // null
echo $getOpt->_; //Array, ['--s', '10', '-type', int]

//php myScript.php -s 10 --type int   (the right way)

echo $getOpt->s; // 10
echo $getOpt->type; // int
echo $getOpt->_; //Array, [ ]

#####别名

您可以定义一个选项以具有别名。例如 -t 有别名 -type，-s 有别名 -size。选项及其别名可以互换使用。别名名称不需要比 'arg' 名称更长或更短。'arg' 名称不需要是单个字符。

$getOpt = new GetOpt();

$getOpt->setOption(array('arg'=>'s', 'alias'=>'size')); //normal
$getOpt->setOption(array('arg'=>'type', 'alias'=>'t')); //this also work

//php myScript.php -s 10 -t int foo bar zee
//or
//php myScript.php --size 10 -t int foo bar zee
//or
//php myScript.php --size 10 --type int foo bar zee

echo $getOpt->t; // output int
echo $getOpt->type; // output int
echo $getOpt->s; // output 10
echo $getOpt->size; // output 10

4. 选项配置

选项配置只是一个关联数组（对象）。

###字段

arg [必需] 选项名称
alias [可选] 别名名称
default [可选] 当选项未作为参数传递时的默认值
help [可选] 此选项的帮助文本。例如：生成项目的类型
required [可选] 指定此选项是必需的。默认为 false
requiredMsg [可选] 当此必需选项未提供时显示的消息。默认如下所示：'选项 -t 是必需的。
pattern [可选] 指定此选项的值必须匹配给定的正则表达式模式。默认为 '/\S+/'
patternMsg [可选] 当提供的值不匹配所需模式时显示的消息。默认如下所示：'选项 -t 必须匹配模式 /\d+/'
prompt [可选] 如果未传递参数，则要求用户输入选项。默认为 false
promptMsg [可选] 当请求用户输入选项值时显示的消息。默认显示如下：'请输入: (要生成的项的类型)'，括号中的文本是帮助文本。

###示例

$config = array(
	'arg'   => 's',
	'alias' => 'size',
	'help'	=> 'Size of generated array',
	'default' => 10,
	'required'		=>  true,
	'requiredMsg'	=>  'Size is missing',
	'pattern'		=>	'/\d+/',
	'patternMsg'	=>	'Size must be a integer',
	'prompt'		=>	true,
	'promptMsg'		=>  'Please enter size of the array to generate'
);

###注意

如果存在 'required'，则忽略 'default'。'required' 表示该选项必须作为参数传递。
选项不需要有值来满足 'required' 要求。例如：'php myScript.php -s'
'default' 仅在选项不是作为参数传递时适用。如果传递了一个不带值的选项，例如 'php myScript.php -s'，则 's' 的值为布尔值 true。
如果存在 'required'，则忽略 'prompt'。再次强调，'required' 表示该选项必须作为参数传递。如果它被传递，就没有提示输入的意义。
'arg**' 和 'alias**' 是区分大小写的。

5. 显示用法

默认情况下，当传递参数 -h 或 --help 时，GetOpt 将终止当前脚本，并输出如下所示的使用信息

Usage: php myScript.php

Options:
	-s,size	 	Size of generated array
	-t,type		Type of items in the generated array

右侧的描述性文本是选项的 'help' 属性。用法行可以自定义

$getopt->setUsage('/usr/bin/php $0 -s [num] -t [num]');

echo $getopt->getUsage();

//OUTPUT:  Usage: /usr/bin/php myScript.php -s [num] -t [num]

6. 高级配置

您可以进一步自定义

消息的输出方式
脚本的终止方式
用户输入的捕获方式

通过向构造函数提供您自己的函数来实现


$reportFunc = function($msg){ echo touppercase($msg); };

$exitFunc = function(){}; //do not terminate

$inputFunc = function(){/* read and return a line from a file instead */ };

...
$getopt = new Getopt(null, $reportFunc , $existFunc, $inputFunc);
...

如果未提供，以下为默认实现的 3 个函数

$this->reportFunction =  function ($msg) {
    echo $msg;
    echo "\n";
};
$this->exitFunction =  function () {
    exit;
};
$this->inputFunction =   function () {
    return trim(fgets(STDIN));
};

7. 许可证

此库是免费的。请参阅根目录中的许可证文件以获取详细许可证信息。

dlin / getopt

维护者

详细信息