Features

Quick build command

Install

composer require toolkit/pflag

Flags Usage

Create Flags

useToolkit\PFlag\Flags;requiredirname(__DIR__) .'/test/bootstrap.php';$flags =$_SERVER['argv'];// NOTICE: must shift first element.$scriptFile =array_shift($flags);$fs = Flags::new();// can with some config$fs->setScriptFile($scriptFile);/** @see Flags::$settings */$fs->setSettings(['descNlOnOptLen' =>26]);// ...

Define options

useToolkit\PFlag\Flag\Option;useToolkit\PFlag\FlagType;useToolkit\PFlag\Validator\EnumValidator;// add options// - quick add$fs->addOpt('age','a','this is a int option', FlagType::INT);// - use string rule$fs->addOptByRule('name,n','string;this is a string option;true');// - use array rule/** @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']),]);// -- add multi option at once.$fs->addOptsByRules(['tag,t' =>'strings;array option, allow set multi times','f'     =>'bool;this is an bool option',]);// - use Option$opt = Option::new('str1',"this is  string option,\ndesc has multi line,\nhaha...");$opt->setDefault('defVal');$fs->addOption($opt);

Define Arguments

useToolkit\PFlag\Flag\Argument;useToolkit\PFlag\FlagType;// add arguments// - quick add$fs->addArg('strArg1','the is string arg and is required','string',true);// - use string rule$fs->addArgByRule('intArg2','int;this is a int arg and with default value;no;89');// - use Argument object$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 Input

useToolkit\PFlag\Flags;useToolkit\PFlag\FlagType;// ...if (!$fs->parse($flags)) {// on render helpreturn;}vdump($fs->getOpts(),$fs->getArgs());

$ php example/flags-demo.php --help

$ php example/flags-demo.php --name inhere --age 99 --tag go -t php -t java -d one -f arg0 80 arr0 arr1

# optionsarray(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)}# argumentsarray(3) {  [0]=> string(4) "arg0"  [1]=> int(80)  [2]=> array(2) {    [0]=> string(4) "arr0"    [1]=> string(4) "arr1"  }}

Get Value

$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"}

Build simple cli app

Create simple alone command

useToolkit\Cli\Cli;useToolkit\PFlag\CliCmd;useToolkit\PFlag\FlagsParser;CliCmd::new()    ->config(function (CliCmd$cmd) {$cmd->name ='demo';$cmd->desc ='description for demo command';// config flags$cmd->options = ['age, a'  =>'int;the option age, is int','name, n' =>'the option name, is string and required;true','tags, t' =>'array;the option tags, is array',        ];// or use property// $cmd->arguments = [...];    })    ->withArguments(['arg1' =>'this is arg1, is string'    ])    ->setHandler(function (FlagsParser$fs) {        Cli::info('options:');vdump($fs->getOpts());        Cli::info('arguments:');vdump($fs->getArgs());    })    ->run();

# show helpphp example/clicmd.php -h# run commandphp example/clicmd.php --age23 --name inhere value1

Create an multi commands app

useToolkit\Cli\Cli;useToolkit\PFlag\CliApp;useToolkit\PFlag\FlagsParser;useToolkit\PFlagTest\Cases\DemoCmdHandler;$app =newCliApp();$app->add('test1',fn(FlagsParser$fs) =>vdump($fs->getOpts()), ['desc'    =>'the test 1 command','options' => ['opt1' =>'opt1 for command test1','opt2' =>'int;opt2 for command test1',    ],]);$app->add('test2',function (FlagsParser$fs) {    Cli::info('options:');vdump($fs->getOpts());    Cli::info('arguments:');vdump($fs->getArgs());}, [// 'desc'    => 'the test2 command','options' => ['opt1' =>'a string opt1 for command test2','opt2' =>'int;a int opt2 for command test2',    ],'arguments' => ['arg1' =>'required arg1 for command test2;true',    ]]);// fn - required php 7.4+$app->add('show-err',fn() =>thrownewRuntimeException('test show exception'));$app->addHandler(DemoCmdHandler::class);$app->run();

# show helpphp example/cliapp.php -h# run commandphp example/cliapp.php test2 --opt1 val1 --opt223 value1

Flag rule

useToolkit\PFlag\FlagType;$rules = [// v: only value, as name and use default type FlagType::STRING// k-v: key is name, value can be string|array'long,s',// name => rule'long,a,b' =>'int',// long is option name, a and b is shorts.'f'      => FlagType::BOOL,'str1'   => ['type' =>'int','desc' =>'an string option'],'tags'   =>'array',// can also: ints, strings'name'   =>'type;the description message;required;default',// with desc, default, required]

publicconstDEFINE_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];

Custom settings

Settings for parse

// -------------------- settings for parse option --------------------/**     * 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;// -------------------- settings for parse argument --------------------/**     * 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;

Setting for render help

// -------------------- settings for built-in render help --------------------/**     * Auto render help on provide '-h', '--help'     *     * @var bool     */protected$autoRenderHelp =true;/**     * Show flag data type on render help.     *     * if False:     *     * -o, --opt    Option desc     *     * if True:     *     * -o, --opt STRING   Option desc     *     * @var bool     */protected$showTypeOnHelp =true;/**     * Will call it on before print help message     *     * @var callable     */private$beforePrintHelp;

$fs->setHelpRenderer(function (\Toolkit\PFlag\FlagsParser$fs) {// render help messages});

Unit tests

phpunit --debug

phpdbg -dauto_globals_jit=Off -qrr$(which phpunit) --coverage-textphpdbg -dauto_globals_jit=Off -qrr$(which phpunit) --coverage-clover ./test/clover.info# use xdebugphpunit --coverage-clover ./test/clover.info

Project use

License