PHP command line parser API

PHP command line parser API

Overview

There is 3 major kinds of objects in the PHP API.

The *Info classes represent the PHP counterparts of the elements defined in a program interface definition XML file.
The *Result classes store the state of the program elements after a command line argument processing
The Parser class parses command line arguments according to *Info rules and output corresponding *Results

Info objects

In a basic usage of the PHP API. You shouldn't have to take care of the *Info classes since the build-php.sh will automatically generate an extended ProgramInfo class populated with all options, subcommands and positional arguments descriptions. The only thing to do is to instanciate this class and give it to a Parser instance.

																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																												$info = new miniappProgramInfo;
																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																												
$parser = new Parser($info);

Result objects

OptionResult

All options result share a common ancestor OptionResult with the following properties

Member / Method	Type / Return type	Description
`$isSet`	`boolean`	`true` if the option is present in the command line arguments and if its presence and value is valid
`value(...)`	`mixed`	Value of the option. The returned type depends on the option type
`__invoke(...)`	`mixed`	A shortcut to call the `value(...)` method

SwithOptionResult

Result of a switch option. The value() method returns the value of the $isSet member

ArgumentOptionResult

Result of a single-argument option. The value() method returns the value of the option argument if the option is present. Otherwise null

MultiArgumentOptionResult

Result of a multi-argument option. The value(...) method returns an array containing the option arguments.

Thus, value(...) (and __invoke(...)) accept arguments

																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																													$optionRes->value(2, 3);
																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																													
// or 
																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																														
$optionRes->value( array(2, 3) );

will return arguments at index 2 and 3 only

SubcommandResult

Contains an array of OptionResult where the array keys are the option's bound variable name defined by the <prg:variable> node of the XML definition file.

Option values can be accessed by the operator []

																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																															$subcommand["optionVarName"]->value();
																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																														

As a pseudo member (thanks to the magic method __get())

																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																															$subcommand->optionVarName->value();
																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																														

Or as a pseudo method (thanks to the magic method __call())

																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																															$subcommand->optionVarName();
																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																														

Finally, getOptionIterator() returns an ArrayIterator to iterate through all options of the subcommand.

ProgramResult

The main object returned by the Parser

Parser

Member / Method	Type / Return type	Description
`$subcommandName`	`string`	Main name of the selected subcommand if set. Otherwise `null`
`$subcommand`	`SubcommandResult`	Reference to the selected subcommand result if set. Otherwise `null`
`__invoke()`	`boolean`	`true` if the command line argument parsing completes successfully (no error raised)
`valueCount()`	`integer`	Number of positional arguments
operator [key]	mixed	If key is a number. value of the keyth positional argument. Otherwise, value of the global option bound to variable key
`Iterator` interface		Iterate through positional arguments
`getMessages(min, max)`	array	Get a list of messages generated during command line argument parsing. The min and max arguments allow to filter messages by importance (debug, warnings, errors and fatal error)

Options can also be accsssed as in SubcommandResult (by pseudo variable/method)