Documentation

Params
in package

Application

Uses ParamOpts

A class representing the parameters/options for a CLI script.

Can parse the command line options using getopt, and can generate usage information.

OPT_ALIASES = ["rowWidth" => "max_row_width", "indentLabels" => "indent_labels", "indentParams" => "indent_params", "indentListing" => "indent_listing", "listingHeader" => "listing_header", "autoChain" => "auto_chain"]
OPT_EXCEPTIONS = ['params', 'param_groups', 'command_groups', 'visible_groups', 'listed_groups']
$auto_chain : mixed: If this is true then we use ParamGroup chaining when adding groups using the group() or command() method. What this means is the ParamGroup object will be returned instead of the Params object, and any subsequent methods to add parameters will automatically add those parameters to the group.
$help_placeholder : mixed
$help_standalone : mixed
$help_usage_combo : mixed
$indent_labels : mixed: Indent group labels by this many spaces.
$indent_listing : mixed: Indent help topic listing items by this many spaces.
$indent_params : mixed: Indent parameter lines by this many spaces.
$listing_col_width : mixed
$listing_header : mixed: A header for the list of additional help topics. A reasonable English default is provided here. The string literal {help} will be replaced with the actual registered parameter name to display help topics.
$max_row_width : mixed: Maximum width of a help text row.
$return_param_on_add : mixed: If this is true, then any of the commands that create and add Param objects will return the new Param object instead of the Params instance.
$usage_standalone : mixed
$command_groups : mixed
$listed_groups : mixed
$param_groups : mixed
$params : mixed
$visible_groups : mixed
__construct() : mixed: Create a new Params instance.
_getopts() : (array|false): Use our Param objects to generate a getopt statement and return the results from that statement.
_makeGroup() : mixed: Create a ParamGroup object and return it.
_makeParam() : mixed: Create a Param object and return it.
add_group() : mixed: Add a ParamGroup object.
add_param() : Params: Add a Param object.
autoChain() : Params: Change the auto_chain property value in a method chaining fashion.
command() : mixed: Create a ParamGroup with group() but automatically set the "is_command" => true option.
flag() : Params: Add a flag type parameter.
getCommand() : (string|\Lum\CLI\ParamGroup): Scan all parameter groups listed as Commands and see which one if any has all of it's parameters set to non-empty, non-false values.
getGroup() : ParamGroup: Return a ParamGroup by it's name.
getGroups() : array<string|int, mixed>: Get all ParamGroup objects.
getHelp() : mixed: Generates the help text for a specific ParamGroup.
getHelpGroup() : mixed: Get the getHelp command group if it's been defined.
getParams() : (array|\Lum\CLI\Param): Find Param objects matching a specific query.
getParamsByOpt() : (array|\Lum\CLI\Param): A wrapper around getParams() that sets the query to be for the optname property.
getParamsByVar() : (array|\Lum\CLI\Param): A wrapper around getParams() that sets the query to be for the varname property.
getUsage() : mixed: Show a short help message with instructions for how to get further help. This is the output of --help when used alone.
getUsageGroup() : mixed: Get the getUsage command group if it's been defined.
group() : mixed: Create a ParamGroup using _makeGroup() and add it with add_group().
hasCommands() : mixed: Return if this Params instance has any ParamGroups set as Commands.
optional() : Params: Add a parameter with an optional value.
param() : Params: Create a param with _makeParam(), then add it with add_param().
parse() : array<string|int, mixed>: Run _getopts() and then parse that output further to make it more sane.
returnParam() : Params: Change the return_param_on_add property value in a method chaining way.
toggle() : Params: Add a toggle type parameter.
useHelp() : Params: Set up special arguments for getting help.
value() : Params: Add a parameter with a mandatory value.
__construct_opts() : mixed: Set instance properties based on an array of options.
add_param_to_group() : mixed

OPT_ALIASES


    public
        mixed
    OPT_ALIASES
    = ["rowWidth" => "max_row_width", "indentLabels" => "indent_labels", "indentParams" => "indent_params", "indentListing" => "indent_listing", "listingHeader" => "listing_header", "autoChain" => "auto_chain"]

OPT_EXCEPTIONS


    public
        mixed
    OPT_EXCEPTIONS
    = ['params', 'param_groups', 'command_groups', 'visible_groups', 'listed_groups']

$auto_chain

If this is true then we use ParamGroup chaining when adding groups using the group() or command() method. What this means is the ParamGroup object will be returned instead of the Params object, and any subsequent methods to add parameters will automatically add those parameters to the group.


    public
        mixed
    $auto_chain
     = false

Note that any other method that don't add parameters will directly call the corresponding method on the Params instance, and return the Params instance as the active context in the chain.

Constructor aliases: "autoChain"

$help_placeholder


    public
        mixed
    $help_placeholder
     = "{help}"

$help_standalone


    public
        mixed
    $help_standalone
     = "help"

$help_usage_combo


    public
        mixed
    $help_usage_combo
     = "help_usage"

$indent_labels

Indent group labels by this many spaces.


    public
        mixed
    $indent_labels
     = 0

Constructor aliases: "indentLabels"

$indent_listing

Indent help topic listing items by this many spaces.


    public
        mixed
    $indent_listing
     = 2

Constructor aliases: "indentListing"

$indent_params

Indent parameter lines by this many spaces.


    public
        mixed
    $indent_params
     = 2

Constructor aliases: "indentParams"

$listing_col_width


    public
        mixed
    $listing_col_width
     = 8

$listing_header

A header for the list of additional help topics. A reasonable English default is provided here. The string literal {help} will be replaced with the actual registered parameter name to display help topics.


    public
        mixed
    $listing_header
     = "\nFor additional help use {help}=<topic> with one of the following topics:\n"

Constructor aliases: "listingHeader"

$max_row_width

Maximum width of a help text row.


    public
        mixed
    $max_row_width
     = 80

By default we use 80 as that's the typical size of a CLI terminal.

Constructor aliases: "rowWidth"

$return_param_on_add

If this is true, then any of the commands that create and add Param objects will return the new Param object instead of the Params instance.


    public
        mixed
    $return_param_on_add
     = false

This is used by the auto_chain feature, and isn't really meant for regular use as it breaks the method chaining entirely.

$usage_standalone


    public
        mixed
    $usage_standalone
     = "usage"

$command_groups


    protected
        mixed
    $command_groups
     = []

$listed_groups


    protected
        mixed
    $listed_groups
     = []

$param_groups


    protected
        mixed
    $param_groups
     = []

$params


    protected
        mixed
    $params
     = []

$visible_groups


    protected
        mixed
    $visible_groups
     = []

__construct()

Create a new Params instance.


    public
                    __construct([array<string|int, mixed> $opts = [] ]) : mixed

Parameters

$opts : array<string|int, mixed> = []: Optional, any properties in this that have corresponding class properties will be populated.

Additionally supports the following extra options:

"help" => If specified, passed to useHelp() as the help optname. "usage" => If specified, passed to useHelp() as the usage optname.

Return values

mixed —

_getopts()

Use our Param objects to generate a getopt statement and return the results from that statement.


    public
                    _getopts([bool $retStatements = false ][, mixed &$optind = null ]) : (array|false)

Noting that PHP's getopt() function has some really bizarre design decisions, such as using 'false' for parameters without arguments.

I recommend using parse() instead as it's a more normalized format. In my opinion of course!

Parameters

$retStatements : bool = false: If true, instead of returning the results from the getopt() statement, this will return a 2 element array representing the arguments which would have been passed to the getopt() function. The need for this seems even less likely than calling _getopts() directly, but once again, it's here in case it's needed.
$optind : mixed = null: If specified, passed by ref to getopt(); Not used at all if $retStatements=true.

Return values

(array|false) —

See PHP's getopt() function for more info.

_makeGroup()

Create a ParamGroup object and return it.


    public
                    _makeGroup(string $name[, array<string|int, mixed> $opts = [] ]) : mixed

Like _makeParam(), you shouldn't have to call this manually. Also like _makeParam() it can't be used in chained method calls.

Parameters

$name : string: The group name/identifier (ParamGroup::$name)
$opts : array<string|int, mixed> = []: Optional, any options to pass to the constructor.

Return values

mixed —

_makeParam()

Create a Param object and return it.


    public
                    _makeParam(string $opt[, string $var = null ][, array<string|int, mixed> $opts = [] ]) : mixed

You shouldn't have to call this manually, but just in case you have some custom requirements, it's available.

Unlike the majority of public methods in this class, this does not return the $this instance, so cannot be used in chained method calls.

Parameters

$opt : string: The optname for the Param we are creating.
$var : string = null: The varname for the Param. Optional.
$opts : array<string|int, mixed> = []: Optional, any options to pass to the constructor.

Return values

mixed —

add_group()

Add a ParamGroup object.


    public
                    add_group(ParamGroup $group[, array<string|int, mixed> $opts = [] ][, mixed $chain = null ]) : mixed

Like with add_param(), you shouldn't have to call this manually.

Parameters

$group : ParamGroup: The ParamGroup object we are adding.
$opts : array<string|int, mixed> = []: Reserved for future use.
$chain : mixed = null: (Optional) Enable ParamGroup chaining? If true, returns the ParamGroup instead of the Params instance. Then subsequent commands to add Param objects will automatically add the Param objects to the ParamGroup as well, and will require a $mandatory argument before the regular arguments. If it's not set at all it defaults to the value of the 'auto_chain' instance property.

Return values

mixed —

Either the ParamGroup or Params depending on options.

add_param()

Add a Param object.


    public
                    add_param(Param $param[, array<string|int, mixed> $opts = [] ]) : Params

Unless you're doing some really custom stuff you shouldn't need to call this manually, but it's here just in case.

Parameters

$param : Param: The Param object we are adding.
$opts : array<string|int, mixed> = []: Special options:

'needGroups' => An array of ParamGroup names to add this Param to and set the 'mandatory' flag to true.

'wantGroups' => An array of ParamGroup names to add this Param to and set the 'mandatory' flag to false.

Return values

Params —

$this

Actually the return value depends on the 'return_param_on_add' property. If it's true, this will return the Param. If it's false it returns the Params instance. As it's not recommended to change that property manually it's not usually an issue, but documenting it anyway.

autoChain()

Change the auto_chain property value in a method chaining fashion.


    public
                    autoChain([bool $value = null ]) : Params

Parameters

$value : bool = null: The value to set the property to. If not specified, this will toggle between states.

Return values

Params —

$this

command()

Create a ParamGroup with group() but automatically set the "is_command" => true option.


    public
                    command(string $name[, mixed $opts = [] ][, mixed $chain = null ]) : mixed

As such it uses the same parameters as group().

Parameters

$name : string
$opts : mixed = []
$chain : mixed = null

Return values

mixed —

flag()

Add a flag type parameter.


    public
                    flag(string $opt, string $desc[, string $var = null ][, array<string|int, mixed> $opts = [] ]) : Params

The output from the parse() method will be the number of times the parameter was specified. Which is obviously 0 if it wasn't specified.

As long as it's a short parameter (a one character optname), you can specify it multiple times in two different ways. For example say the optname is 'a' then you could do:

./script.php -a -a # $params['a'] => 2 ./script.php -aaa # $params['a'] => 3 ./script.php --nada # $params['a'] => 0

Parameters

$opt : string: The optname for the Param.
$desc : string: A description of the Param.
$var : string = null: (Optional) The varname for the Param.
$opts : array<string|int, mixed> = []: (Optional) Further options for param().

Return values

Params —

$this

getCommand()

Scan all parameter groups listed as Commands and see which one if any has all of it's parameters set to non-empty, non-false values.


    public
                    getCommand([array<string|int, mixed> $parsedOpts = null ][, bool $retGroup = false ]) : (string|\Lum\CLI\ParamGroup)

The first one to match will be returned. If none match returns null.

Parameters

$parsedOpts : array<string|int, mixed> = null: Optional: the output from parse().
$retGroup : bool = false: Optional: if true returns the ParamGroup object.

Return values

(string|\Lum\CLI\ParamGroup) —

Either the name of the group, or the instance.

getGroup()

Return a ParamGroup by it's name.


    public
                    getGroup(string $name) : ParamGroup

Parameters

$name : string: The name of the ParamGroup.

Return values

ParamGroup —

The ParamGroup.

getGroups()

Get all ParamGroup objects.


    public
                    getGroups() : array<string|int, mixed>

Return values

array<string|int, mixed> —

All ParamGroup objects regardless of type.

getHelp()

Generates the help text for a specific ParamGroup.


    public
                    getHelp(string $topic) : mixed

This is the output of --help=.

Parameters

$topic : string

Return values

mixed —

getHelpGroup()

Get the getHelp command group if it's been defined.


    public
                    getHelpGroup() : mixed

Will look for the standalone 'help' group first, and the combined 'help_usage' group second.

Return values

mixed —

getParams()

Find Param objects matching a specific query.


    public
                    getParams([array<string|int, mixed> $query = [] ][, bool $first = false ]) : (array|\Lum\CLI\Param)

All arguments are optional. If no arguments are supplied, then this method will return all defined Param objects.

Parameters

$query : array<string|int, mixed> = []: A map of Param properties that must match. If this is empty, return all Param objects. Default: []
$first : bool = false: If this is true return the first matching Param. If $query is empty, this argument is ignored. Default: false

Return values

(array|\Lum\CLI\Param) —

The output depends on the $first argument. If $first is false, returns an array of Param objects. If $first is true, returns the first matching Param object.

getParamsByOpt()

A wrapper around getParams() that sets the query to be for the optname property.


    public
                    getParamsByOpt(string $optname[, bool $first = false ]) : (array|\Lum\CLI\Param)

Parameters

$optname : string: (Mandatory) The optname we are searching for.
$first : bool = false: (Optional) See getParams() for details.

Return values

(array|\Lum\CLI\Param) —

See getParams() for details.

getParamsByVar()

A wrapper around getParams() that sets the query to be for the varname property.


    public
                    getParamsByVar(string $varname[, bool $first = false ]) : (array|\Lum\CLI\Param)

Parameters

$varname : string: (Mandatory) The varname we are searching for.
$first : bool = false: (Optional) See getParams() for details.

Return values

(array|\Lum\CLI\Param) —

See getParams() for details.

getUsage()

Show a short help message with instructions for how to get further help. This is the output of --help when used alone.


    public
                    getUsage() : mixed

Return values

mixed —

getUsageGroup()

Get the getUsage command group if it's been defined.


    public
                    getUsageGroup() : mixed

Will look for the standalone 'usage' group first, and the combined 'help_usage' group second.

Return values

mixed —

group()

Create a ParamGroup using _makeGroup() and add it with add_group().


    public
                    group(string $name[, mixed $opts = [] ][, mixed $chain = null ]) : mixed

This uses the same parameters as _makeGroup() and add_group().

Parameters

$name : string
$opts : mixed = []
$chain : mixed = null

Return values

mixed —

hasCommands()

Return if this Params instance has any ParamGroups set as Commands.


    public
                    hasCommands() : mixed

Return values

mixed —

optional()

Add a parameter with an optional value.


    public
                    optional(string $opt, string $val, string $dv, string $dt[, string $var = null ][, array<string|int, mixed> $opts = [] ]) : Params

This is a parameter that can have a value or not have a value.

Parameters

$opt : string: The optname for the Param.
$val : string: The value_placeholder for the Param.
$dv : string: A description of the Param for when it has a value.
$dt : string: A description of the Param when no value is specified.
$var : string = null: (Optional) The varname for the Param.
$opts : array<string|int, mixed> = []: (Optional) Additional options to pass to param().

The $opts aren't required, but anything supported by param() can be specified. A few common options you might want to specify:

'varname' The varname for the Param. 'toggle_true' What to use if the parameter is specified with no value. 'toggle_false' What to use if the parameter is not specified at all.

Return values

Params —

$this

param()

Create a param with _makeParam(), then add it with add_param().


    public
                    param(string $opt[, mixed $var = null ][, mixed $opts = [] ]) : Params

This uses the exact same parameters as _makeParam() and also supports any additional options used by add_param().

Parameters

$opt : string
$var : mixed = null
$opts : mixed = []

Return values

Params —

$this

parse()

Run _getopts() and then parse that output further to make it more sane.


    public
                    parse() : array<string|int, mixed>

This method accepts two optional parameters which both default to false if not specified.

Return values

array<string|int, mixed> —

An array of parsed options.

In addition to the regular parsed options, the following keys will also be added to the options array:

"+args" => An array of positional arguments. May be empty.

returnParam()

Change the return_param_on_add property value in a method chaining way.


    public
                    returnParam([bool $value = null ]) : Params

Parameters

$value : bool = null: The value to set the property to. If not specified, this will toggle between states.

Return values

Params —

$this

toggle()

Add a toggle type parameter.


    public
                    toggle(string $opt, string $desc[, string $var = null ][, array<string|int, mixed> $opts = [] ]) : Params

The output from the parse() method will be boolean true if the the parameter was included, or false if it was not.

Parameters

$opt : string: The optname for the Param.
$desc : string: A description of the Param.
$var : string = null: (Optional) The varname for the Param.
$opts : array<string|int, mixed> = []: (Optional) Further options for param().

Return values

Params —

$this

useHelp()

Set up special arguments for getting help.


    public
                    useHelp([string $help = "help" ][, string $usage = null ]) : Params

Parameters

$help : string = "help": The optname for the getHelp() command. Optional. Default: "help"
$usage : string = null: The optname for the getUsage() command. Optional. Default: null

If $usage isn't specified or is null, it will default to the same name as $help. If you call useHelp() with no parameters, both will be "help".

If $help and $usage have the same name, then one Param with a varname of 'help_usage' will be added with $help as the optname. It will be set to has_value=>true, value_required=>false and added to one ParamGroup also with a name of 'help_usage' with is_command=>true, and the single param will be mandatory.

If $help and $usage have different names, then two Param objects and two ParamGroup objects will be created with 'help' and 'usage' varname/name properties, and $help and $usage optname properties. The 'help' Param will be has_value=>true, whereas the 'usage' Param will be a toggle. Both will be the sole mandatory Param in their corresponding ParamGroup.

Return values

Params —

$this

value()

Add a parameter with a mandatory value.


    public
                    value(string $opt, string $val, string $desc[, string $var = null ][, array<string|int, mixed> $opts = [] ]) : Params

This is a command line parameter that must have a value specified.

Parameters

$opt : string: The optname for the Param.
$val : string: The value_placeholder for the Param
$desc : string: A description of the Param.
$var : string = null: (Optional) The varname for the Param.
$opts : array<string|int, mixed> = []: (Optional) Additional options to pass to param().

Return values

Params —

$this

__construct_opts()

Set instance properties based on an array of options.


    protected
                    __construct_opts(array<string|int, mixed> $opts[, array<string|int, mixed> $exceptions = [] ][, array<string|int, mixed> $aliases = [] ]) : mixed

Parameters

$opts : array<string|int, mixed>: The associative array of options passed.
$exceptions : array<string|int, mixed> = []: A flat array of property/option names to skip.
$aliases : array<string|int, mixed> = []: An associative array of "alias" => "property".

Return values

mixed —

add_param_to_group()


    protected
                    add_param_to_group(Param $param, mixed $group, mixed $mandatory) : mixed

Parameters

$param : Param
$group : mixed
$mandatory : mixed

Return values

mixed —

Params in package Application Uses ParamOpts

Table of Contents

Constants

OPT_ALIASES

OPT_EXCEPTIONS

Properties

$auto_chain

$help_placeholder

$help_standalone

$help_usage_combo

$indent_labels

$indent_listing

$indent_params

$listing_col_width

$listing_header

$max_row_width

$return_param_on_add

$usage_standalone

$command_groups

$listed_groups

$param_groups

$params

$visible_groups

Methods

__construct()

Parameters

Return values

_getopts()

Parameters

Return values

_makeGroup()

Parameters

Return values

_makeParam()

Parameters

Return values

add_group()

Parameters

Return values

add_param()

Parameters

Return values

autoChain()

Parameters

Return values

command()

Parameters

Return values

flag()

Parameters

Return values

getCommand()

Parameters

Return values

getGroup()

Parameters

Return values

getGroups()

Return values

getHelp()

Parameters

Return values

getHelpGroup()

Return values

getParams()

Parameters

Return values

getParamsByOpt()

Parameters

Return values

getParamsByVar()

Parameters

Return values

getUsage()

Return values

getUsageGroup()

Return values

group()

Parameters

Return values

Params
in package

Application

Uses ParamOpts