GetOptionKit
Code Quality, (*1)
, (*2)
Versions & Stats, (*3)
, (*4)
A powerful option parser toolkit for PHP, supporting type constraints,
flag, multiple flag, multiple values and required value checking., (*5)
GetOptionKit supports PHP5.3, with fine unit testing with PHPUnit testing
framework., (*6)
GetOptionKit is object-oriented, it's flexible and extendable., (*7)
Powering PHPBrew https://github.com/phpbrew/phpbrew, CLIFramework https://github.com/c9s/CLIFramework and AssetKit https://github.com/c9s/AssetKit, (*8)
Features
- Simple format.
- Type constrant.
- Multiple value, requried value, optional value checking.
- Auto-generated help text from defined options.
- Support app/subcommand option parsing.
- Option Value Validator
- Option Suggestions
- SPL library.
- HHVM support.
Requirements
Install From Composer
composer require corneltek/getoptionkit
simple flags:, (*9)
program.php -a -b -c
program.php -abc
program.php -vvv # incremental flag v=3
program.php -a -bc
with multiple values:, (*10)
program.php -a foo -a bar -a zoo -b -b -b
specify value with equal sign:, (*11)
program.php -a=foo
program.php --long=foo
with normal arguments:, (*12)
program.php -a=foo -b=bar arg1 arg2 arg3
program.php arg1 arg2 arg3 -a=foo -b=bar
Option SPEC
v|verbose flag option (with boolean value true)
d|dir: option require a value (MUST require)
d|dir+ option with multiple values.
d|dir? option with optional value
dir:=string option with type constraint of string
dir:=number option with type constraint of number
dir:=file option with type constraint of file
dir:=date option with type constraint of date
dir:=boolean option with type constraint of boolean
d single character only option
dir long option name
app [app-opts] [app arguments]
app [app-opts] subcommand [subcommand-opts] [subcommand-args]
app [app-opts] subcmd1 [subcmd-opts1] subcmd2 [subcmd-opts] subcmd3 [subcmd-opts3] [subcommand arguments....]
Documentation
See more details in the documentation, (*13)
Demo
Please check examples/demo.php., (*14)
Run:, (*15)
% php examples/demo.php -f test -b 123 -b 333
Print:, (*16)
* Available options:
-f, --foo <value> option requires a value.
-b, --bar <value>+ option with multiple value.
-z, --zoo [<value>] option with optional value.
-v, --verbose verbose message.
-d, --debug debug message.
--long long option name only.
-s short option name only.
Enabled options:
* key:foo spec:-f, --foo <value> desc:option requires a value.
value => test
* key:bar spec:-b, --bar <value>+ desc:option with multiple value.
Array
(
[0] => 123
[1] => 333
)
Synopsis
use GetOptionKit\OptionCollection;
use GetOptionKit\OptionParser;
use GetOptionKit\OptionPrinter\ConsoleOptionPrinter;
$specs = new OptionCollection;
$specs->add('f|foo:', 'option requires a value.' )
->isa('String');
$specs->add('b|bar+', 'option with multiple value.' )
->isa('Number');
$specs->add('ip+', 'Ip constraint' )
->isa('Ip');
$specs->add('email+', 'Email address constraint' )
->isa('Email');
$specs->add('z|zoo?', 'option with optional value.' )
->isa('Boolean');
$specs->add('file:', 'option value should be a file.' )
->isa('File');
$specs->add('v|verbose', 'verbose message.' );
$specs->add('d|debug', 'debug message.' );
$specs->add('long', 'long option name only.' );
$specs->add('s', 'short option name only.' );
$printer = new ConsoleOptionPrinter();
echo $printer->render($specs);
$parser = new OptionParser($specs);
echo "Enabled options: \n";
try {
$result = $parser->parse( $argv );
foreach ($result->keys as $key => $spec) {
print_r($spec);
}
$opt = $result->keys['foo']; // return the option object.
$str = $result->keys['foo']->value; // return the option value
print_r($opt);
var_dump($str);
} catch( Exception $e ) {
echo $e->getMessage();
}
Documentation
See https://github.com/c9s/GetOptionKit/wiki for more details., (*17)
Option Value Type
The option value type help you validate the input,
the following list is the current supported types:, (*18)
stringnumberbooleanfiledateurlemailipipv4ipv6regex
And here is the related sample code:, (*19)
$opt->add( 'f|foo:' , 'with string type value' )
->isa('string');
$opt->add( 'b|bar+' , 'with number type value' )
->isa('number');
$opt->add( 'z|zoo?' , 'with boolean type value' )
->isa('boolean');
$opt->add( 'file:' , 'with file type value' )
->isa('file');
$opt->add( 'date:' , 'with date type value' )
->isa('date');
$opt->add( 'url:' , 'with url type value' )
->isa('url');
$opt->add( 'email:' , 'with email type value' )
->isa('email');
$opt->add( 'ip:' , 'with ip(v4/v6) type value' )
->isa('ip');
$opt->add( 'ipv4:' , 'with ipv4 type value' )
->isa('ipv4');
$opt->add( 'ipv6:' , 'with ipv6 type value' )
->isa('ipv6');
$specs->add('r|regex:', 'with custom regex type value')
->isa('Regex', '/^([a-z]+)$/');
Please note that currently only string, number, boolean types can be validated., (*20)
ContinuousOptionParser
$specs = new OptionCollection;
$spec_verbose = $specs->add('v|verbose');
$spec_color = $specs->add('c|color');
$spec_debug = $specs->add('d|debug');
$spec_verbose->description = 'verbose flag';
// ContinuousOptionParser
$parser = new ContinuousOptionParser( $specs );
$result = $parser->parse(explode(' ','program -v -d test -a -b -c subcommand -e -f -g subcommand2'));
$result2 = $parser->continueParse();
OptionPrinter
GetOptionKit\OptionPrinter can print options for you:, (*21)
* Available options:
-f, --foo option requires a value.
-b, --bar option with multiple value.
-z, --zoo option with optional value.
-v, --verbose verbose message.
-d, --debug debug message.
--long long option name only.
-s short option name only.
Command-line app with subcommands
For application with subcommands is designed by following form:, (*22)
[app name] [app opts]
[subcommand1] [subcommand-opts]
[subcommand2] [subcommand-opts]
[subcommand3] [subcommand-opts]
[arguments]
You can check the tests/GetOptionKit/ContinuousOptionParserTest.php unit test file:, (*23)
// subcommand stack
$subcommands = array('subcommand1','subcommand2','subcommand3');
// different command has its own options
$subcommandSpecs = array(
'subcommand1' => $cmdspecs,
'subcommand2' => $cmdspecs,
'subcommand3' => $cmdspecs,
);
// for saved options
$subcommandOptions = array();
// command arguments
$arguments = array();
$argv = explode(' ','program -v -d -c subcommand1 -a -b -c subcommand2 -c subcommand3 arg1 arg2 arg3');
// parse application options first
$parser = new ContinuousOptionParser( $appspecs );
$app_options = $parser->parse( $argv );
while (! $parser->isEnd()) {
if (@$subcommands[0] && $parser->getCurrentArgument() == $subcommands[0]) {
$parser->advance();
$subcommand = array_shift( $subcommands );
$parser->setSpecs( $subcommandSpecs[$subcommand] );
$subcommandOptions[ $subcommand ] = $parser->continueParse();
} else {
$arguments[] = $parser->advance();
}
}
Todo
- Option Spec group.
- option valid value checking.
- custom command mapping.
Command Line Utility Design Concept
- main program name should be easy to type, easy to remember.
- subcommand should be easy to type, easy to remember. length should be shorter than 7 characters.
- options should always have long descriptive name
- a program should be easy to check usage.
General command interface
To list usage of all subcommands or the program itself:, (*24)
$ prog help
To list the subcommand usage, (*25)
$ prog help subcommand subcommand2 subcommand3
Hacking
Fork this repository and clone it:, (*26)
$ git clone git://github.com/c9s/GetOptionKit.git
$ cd GetOptionKit
$ composer install
Run PHPUnit to test:, (*27)
$ phpunit
License
This project is released under MIT License., (*28)
Wallogit.com
