Options
in package
Class Options
Parses command line options passed to the CLI script. Allows CLI scripts to easily register all accepted options and commands and even generates a help text from this setup.
Tags
Table of Contents
Properties
- $args : array<string|int, mixed>
- $bin : string
- $colors : Colors
- $command : string
- $newline : string
- $options : array<string|int, mixed>
- $setup : array<string|int, mixed>
Methods
- __construct() : mixed
- Constructor
- checkArguments() : mixed
- Checks the actual number of arguments against the required number
- getArgs() : array<string|int, mixed>
- Get all the arguments passed to the script
- getBin() : mixed
- Gets the bin value
- getCmd() : string
- Return the found command if any
- getOpt() : bool|string|array<string|int, string>
- Get the value of the given option
- help() : string
- Builds a help screen from the available options. You may want to call it from -h or on error
- parseOptions() : mixed
- Parses the given arguments for known options and command
- registerArgument() : mixed
- Register the names of arguments for help generation and number checking
- registerCommand() : mixed
- This registers a sub command
- registerOption() : mixed
- Register an option for option parsing and help generation
- setCommandHelp() : mixed
- Sets the help text for the tools commands itself
- setHelp() : mixed
- Sets the help text for the tool itself
- useCompactHelp() : mixed
- Use a more compact help screen with less new lines
- readPHPArgv() : array<string|int, mixed>
- Safely read the $argv PHP array across different PHP configurations.
Properties
$args
protected
array<string|int, mixed>
$args
= array()
passed non-option arguments
$bin
protected
string
$bin
the executed script
$colors
protected
Colors
$colors
for colored help output
$command
protected
string
$command
= ''
current parsed command if any
$newline
protected
string
$newline
= "\n"
newline used for spacing help texts
$options
protected
array<string|int, mixed>
$options
= array()
store parsed options
$setup
protected
array<string|int, mixed>
$setup
keeps the list of options to parse
Methods
__construct()
Constructor
public
__construct([Colors $colors = null ]) : mixed
Parameters
- $colors : Colors = null
-
optional configured color object
Tags
checkArguments()
Checks the actual number of arguments against the required number
public
checkArguments() : mixed
Throws an exception if arguments are missing.
This is run from CLI automatically and usually does not need to be called directly
Tags
getArgs()
Get all the arguments passed to the script
public
getArgs() : array<string|int, mixed>
This will not contain any recognized options or the script name itself
Return values
array<string|int, mixed>getBin()
Gets the bin value
public
getBin() : mixed
getCmd()
Return the found command if any
public
getCmd() : string
Return values
stringgetOpt()
Get the value of the given option
public
getOpt([mixed $option = null ][, bool|string $default = false ]) : bool|string|array<string|int, string>
Please note that all options are accessed by their long option names regardless of how they were specified on commandline.
Can only be used after parseOptions() has been run
Parameters
- $option : mixed = null
- $default : bool|string = false
-
what to return if the option was not set
Return values
bool|string|array<string|int, string>help()
Builds a help screen from the available options. You may want to call it from -h or on error
public
help() : string
Tags
Return values
stringparseOptions()
Parses the given arguments for known options and command
public
parseOptions() : mixed
The given $args array should NOT contain the executed file as first item anymore! The $args array is stripped from any options and possible command. All found otions can be accessed via the getOpt() function
Note that command options will overwrite any global options with the same name
This is run from CLI automatically and usually does not need to be called directly
Tags
registerArgument()
Register the names of arguments for help generation and number checking
public
registerArgument(string $arg, string $help[, bool $required = true ][, string $command = '' ]) : mixed
This has to be called in the order arguments are expected
Parameters
- $arg : string
-
argument name (just for help)
- $help : string
-
help text
- $required : bool = true
-
is this a required argument
- $command : string = ''
-
if theses apply to a sub command only
Tags
registerCommand()
This registers a sub command
public
registerCommand(string $command, string $help) : mixed
Sub commands have their own options and use their own function (not main()).
Parameters
- $command : string
- $help : string
Tags
registerOption()
Register an option for option parsing and help generation
public
registerOption(string $long, string $help[, string|null $short = null ][, bool|string $needsarg = false ][, string $command = '' ]) : mixed
Parameters
- $long : string
-
multi character option (specified with --)
- $help : string
-
help text for this option
- $short : string|null = null
-
one character option (specified with -)
- $needsarg : bool|string = false
-
does this option require an argument? give it a name here
- $command : string = ''
-
what command does this option apply to
Tags
setCommandHelp()
Sets the help text for the tools commands itself
public
setCommandHelp(string $help) : mixed
Parameters
- $help : string
setHelp()
Sets the help text for the tool itself
public
setHelp(string $help) : mixed
Parameters
- $help : string
useCompactHelp()
Use a more compact help screen with less new lines
public
useCompactHelp([bool $set = true ]) : mixed
Parameters
- $set : bool = true
readPHPArgv()
Safely read the $argv PHP array across different PHP configurations.
private
readPHPArgv() : array<string|int, mixed>
Will take care on register_globals and register_argc_argv ini directives
Tags
Return values
array<string|int, mixed> —the $argv PHP array or PEAR error if not registered