php-toolkit/pflag
是一個PHP編寫的,通用的命令列標誌(選項和引數)解析庫。
Github 倉庫: php-toolkit/pflag
功能說明
- 通用的命令列選項和引數解析器
- 支援設定值資料型別(
int,string,bool,array
),將自動格式化輸入值 - 支援為選項/引數設定預設值
- 支援為一個選項設定多個短名稱
- 支援從環境變數讀取標誌值
- 支援設定選項/引數為必須的(
required
) - 支援設定驗證器以檢查輸入值
- 支援自動渲染漂亮的幫助資訊。
命令列選項:
- 選項以
-
或者--
開頭的,且首字元必須是字母 - 以
--
開頭的為長選項. eg:--long
--long value
- 以
-
開頭的為短選項-s -a value
- 支援定義陣列選項
- eg:
--tag php --tag go
將會得到$tag = [php, go]
- eg:
命令列引數:
- 不能滿足選項的都認作引數
- 支援繫結命名引數
- 支援定義陣列引數
安裝
composer 安裝
composer require toolkit/pflag
Flags 使用
Flags - 是一個命令列標誌(選項和引數)解析器和管理器。
示例程式碼請參見 example/flags-demo.php
建立解析器
建立和初始化解析器
use Toolkit\PFlag\Flags;
require dirname(__DIR__) . '/test/bootstrap.php';
$flags = $_SERVER['argv'];
// NOTICE: must shift first element.
$scriptFile = array_shift($flags);
$fs = Flags::new();
// (可選的)可以新增一些自定義設定
$fs->setScriptFile($scriptFile);
/** @see Flags::$settings */
$fs->setSettings([
'descNlOnOptLen' => 26
]);
// ...
定義選項
定義選項 - 定義好支援的選項設定,解析時將會根據定義來解析輸入
新增選項定義的示例:
use Toolkit\PFlag\Flag\Option;
use Toolkit\PFlag\FlagType;
use Toolkit\PFlag\Validator\EnumValidator;
// add options
// - quick add
$fs->addOpt('age', 'a', 'this is a int option', FlagType::INT);
// - 使用字串規則快速新增選項定義
$fs->addOptByRule('name,n', 'string;this is a string option;true');
// -- 一次新增多個選項
$fs->addOptsByRules([
'tag,t' => 'strings;array option, allow set multi times',
'f' => 'bool;this is an bool option',
]);
// - 使用陣列定義
/** @see Flags::DEFINE_ITEM for array rule */
$fs->addOptByRule('name-is-very-lang', [
'type' => FlagType::STRING,
'desc' => 'option name is to lang, desc will print on newline',
'shorts' => ['d','e','f'],
// TIP: add validator limit input value.
'validator' => EnumValidator::new(['one', 'two', 'three']),
]);
// - 使用 Option 物件
$opt = Option::new('str1', "this is string option, \ndesc has multi line, \nhaha...");
$opt->setDefault('defVal');
$fs->addOption($opt);
定義引數
定義引數 - 定義好支援的選項設定,解析時將會根據定義來解析輸入
新增引數定義的示例:
use Toolkit\PFlag\Flag\Argument;
use Toolkit\PFlag\FlagType;
// add arguments
// - quick add
$fs->addArg('strArg1', 'the is string arg and is required', 'string', true);
// - 使用字串規則快速新增定義
$fs->addArgByRule('intArg2', 'int;this is a int arg and with default value;no;89');
// - 使用 Argument 物件
$arg = Argument::new('arrArg');
// OR $arg->setType(FlagType::ARRAY);
$arg->setType(FlagType::STRINGS);
$arg->setDesc("this is an array arg,\n allow multi value,\n must define at last");
$fs->addArgument($arg);
解析命令列輸入
最後呼叫 parse()
解析命令列輸入資料
// ...
if (!$fs->parse($flags)) {
// on render help
return;
}
vdump($fs->getOpts(), $fs->getArgs());
顯示幫助
當輸入 -h
或 --help
會自動渲染幫助資訊。
$ php example/flags-demo.php --help
Output:
執行示例:
$ php example/flags-demo.php --name inhere --age 99 --tag go -t php -t java -d one -f arg0 80 arr0 arr1
輸出結果:
# 選項資料
array(6) {
["str1"]=> string(6) "defVal"
["name"]=> string(6) "inhere"
["age"]=> int(99)
["tag"]=> array(3) {
[0]=> string(2) "go"
[1]=> string(3) "php"
[2]=> string(4) "java"
}
["name-is-very-lang"]=> string(3) "one"
["f"]=> bool(true)
}
# 引數資料
array(3) {
[0]=> string(4) "arg0"
[1]=> int(80)
[2]=> array(2) {
[0]=> string(4) "arr0"
[1]=> string(4) "arr1"
}
}
獲取輸入值
獲取flag值很簡單,使用方法 getOpt(string $name)
getArg($nameOrIndex)
即可.
TIP: 將通過定義的資料型別自動格式化輸入值
選項資料
$force = $fs->getOpt('f'); // bool(true)
$age = $fs->getOpt('age'); // int(99)
$name = $fs->getOpt('name'); // string(inhere)
$tags = $fs->getOpt('tags'); // array{"php", "go", "java"}
引數資料
$arg0 = $fs->getArg(0); // string(arg0)
// get an array arg
$arrArg = $fs->getArg(1); // array{"arr0", "arr1"}
// get value by name
$arrArg = $fs->getArg('arrArg'); // array{"arr0", "arr1"}
擴充套件:規則定義
選項引數規則。使用規則可以快速定義一個選項或引數。
- string 字串規則以分號
;
分割每個部分 (完整規則:type;desc;required;default;shorts
). - array 規則按
SFlags::DEFINE_ITEM
設定定義 - 支援的型別常量請看
FlagType::*
use Toolkit\PFlag\FlagType;
$rules = [
// v: 只有值,作為名稱並使用預設型別 FlagType::STRING
// k-v: 鍵是名稱,值可以是字串|陣列
'long,s',
// name => rule
'long,a,b' => 'int;an int option', // long is option name, a and b is shorts.
'f' => FlagType::BOOL,
'str1' => ['type' => 'int', 'desc' => 'an string option'],
'tags' => 'array; an array option', // can also: ints, strings
'name' => 'type;the description message;required;default', // with desc, default, required
]
對於選項
- 選項允許設定短名稱
shorts
TIP: 例如
long,a,b
-long
是選項名稱. 剩餘的a,b
都是它的短選項名.
對於引數
- 引數沒有別名或者短名稱
- 陣列引數只允許定義在最後
陣列定義項
常量 Flags::DEFINE_ITEM
:
public const DEFINE_ITEM = [
'name' => '',
'desc' => '',
'type' => FlagType::STRING,
'helpType' => '', // use for render help
// 'index' => 0, // only for argument
'required' => false,
'default' => null,
'shorts' => [], // only for option
// value validator
'validator' => null,
// 'category' => null
];
自定義設定
解析設定
// -------------------- 選項解析設定 --------------------
/**
* Stop parse option on found first argument.
*
* - Useful for support multi commands. eg: `top --opt ... sub --opt ...`
*
* @var bool
*/
protected $stopOnFistArg = true;
/**
* Skip on found undefined option.
*
* - FALSE will throw FlagException error.
* - TRUE will skip it and collect as raw arg, then continue parse next.
*
* @var bool
*/
protected $skipOnUndefined = false;
// -------------------- 引數解析設定 --------------------
/**
* Whether auto bind remaining args after option parsed
*
* @var bool
*/
protected $autoBindArgs = true;
/**
* Strict match args number.
* if exist unbind args, will throw FlagException
*
* @var bool
*/
protected $strictMatchArgs = false;
渲染幫助設定
support some settings for render help
// -------------------- settings for built-in render help --------------------
/**
* 自動渲染幫助資訊當輸入 '-h', '--help' 選項時
*
* @var bool
*/
protected $autoRenderHelp = true;
/**
* 在渲染的幫助資訊上顯示資料型別
*
* if False:
*
* -o, --opt Option desc
*
* if True:
*
* -o, --opt STRING Option desc
*
* @var bool
*/
protected $showTypeOnHelp = true;
/**
* 將在列印幫助訊息之前呼叫它
*
* @var callable
*/
private $beforePrintHelp;
自定義幫助訊息渲染:
$fs->setHelpRenderer(function (\Toolkit\PFlag\FlagsParser $fs) {
// render help messages
});
單元測試
phpunit --debug
test with coverage:
phpdbg -qrr $(which phpunit) --coverage-text
使用pflag的專案
Check out these projects, which use github.com/php-toolkit/pflag :
- inhere/console Full-featured php command line application library.
- kite Kite is a tool for help development.
- More, please see Packagist
Github 倉庫: php-toolkit/pflag
本作品採用《CC 協議》,轉載必須註明作者和本文連結
GIthub github.com/inhere