ParamsApp
in package
Uses
HasParams, HasHelp, HasError
An abstract base class for making your own CLI app which can parse command line options using the Params class.
Basically create a new class extending this one, define your parameter groups and parameters inside a initialize_params($params) method defined in your class, and then define a handle_{command_name} method for any of the commands, or a handle_params method if you don't want to use the commands feature or want to have a default command if the user doesn't specify any command line options.
Since this abstract class is using the HasParams method, simple using:
$params->useHelp()
in your initialize_params method will enable the ability to use:
php yourscript.php --help
to get a screen of basic usage information and a list of further help topics you can look up, as well as:
php yourscript.php --help={topic}
where {topic} is the name of any ParamGroup you defined to show the full information regarding the specific parameter group.
Table of Contents
- $app_params : mixed
- The initialized parameters. Set in the constructor.
- $error_prefix : mixed
- A default prefix for any error messages.
- $no_command_message : mixed
- A default error message if no valid command was found in the parsed command line options.
- $usage_message : mixed
- A default usage message for the error() method.
- __construct() : mixed
- A super simple constructor that creates a Params instance, passes it to the initialize_params() method your app class defined with the initialized params.
- error() : mixed
- A method to display an error message along with a quick note about how to get further help information.
- run() : mixed
- A super simple method that will use the dispatch_params() method to find an appropriate handler method and call it with the parsed parameters. See the HasParams trait for more details.
- stderr() : int
- A small wrapper method to write a string to STDERR.
- dispatch_params() : mixed
- A method to parse the command line parameters, get the command, and dispatch to a method named handle_{groupname} where {groupname} is the 'name' property of the ParamGroup object that matched the command spec.
- getParamsInstance() : mixed
- A method to return the Params instance. Needed by HasError.
- handle_default() : mixed
- A default handler for when commands are specified but no valid command can be determined from the command line options.
- handle_help() : mixed
- A default handler for the 'help' command.
- handle_help_usage() : mixed
- A default handler for the 'help_usage' command.
- handle_usage() : mixed
- A default handler for the 'usage' command.
- initialize_params() : mixed
- Implement this method in your class to set up the Params object.
Properties
$app_params
The initialized parameters. Set in the constructor.
protected
mixed
$app_params
$error_prefix
A default prefix for any error messages.
protected
mixed
$error_prefix
= ''
This is completely optional, but could be something like "ERROR: " or really anything you want.
$no_command_message
A default error message if no valid command was found in the parsed command line options.
protected
mixed
$no_command_message
= "No valid command specified"
$usage_message
A default usage message for the error() method.
protected
mixed
$usage_message
= "For usage information use {help}"
Will replace the {help} string literal with the usage command.
Methods
__construct()
A super simple constructor that creates a Params instance, passes it to the initialize_params() method your app class defined with the initialized params.
public
__construct([array<string|int, mixed> $opts = [] ]) : mixed
Parameters
- $opts : array<string|int, mixed> = []
-
Options to pass to the Params instance.
Return values
mixed —error()
A method to display an error message along with a quick note about how to get further help information.
public
error(string $errmsg[, int $errcode = 1 ]) : mixed
Parameters
- $errmsg : string
-
The error message to write to STDERR.
- $errcode : int = 1
-
The error code to exit the app with (default: 1)
Not sure why you'd want to do this, but if the $errcode is less than 0 or greater than 254, the exit() statement will not be called at all.
Note this requires a class instance property to exist called 'usage_message' which will be a template with the help placeholder, which by default is {help} which will be replaced with the appropriate usage command line parameter.
Return values
mixed —run()
A super simple method that will use the dispatch_params() method to find an appropriate handler method and call it with the parsed parameters. See the HasParams trait for more details.
public
run() : mixed
Return values
mixed —The output from the dispatched method.
stderr()
A small wrapper method to write a string to STDERR.
public
static stderr(string $message) : int
Parameters
- $message : string
-
The message to write to STDERR.
Return values
int —The number of bytes written, or false on error.
dispatch_params()
A method to parse the command line parameters, get the command, and dispatch to a method named handle_{groupname} where {groupname} is the 'name' property of the ParamGroup object that matched the command spec.
protected
dispatch_params(Params $params) : mixed
If the method doesn't exist, an exception will be thrown.
If no command groups were defined, or none of the defined commands matched, it looks for a handle_default() method instead.
Alternatively, if no command groups were defined, a method called handle_params() may be used instead of handle_default(). Likewise if commands were defined, but no command matched, a method called handle_no_command() may be used instead of handle_default().
The parsed parameters array will be passed to the matching method as the first argument, the Params instance will be passed as the second argument. No other arguments are passed.
If no valid methods at all were found, this will throw an Exception.
Parameters
- $params : Params
-
The Params instance we are using.
Return values
mixed —The output from the matched method.
getParamsInstance()
A method to return the Params instance. Needed by HasError.
protected
getParamsInstance() : mixed
Return values
mixed —handle_default()
A default handler for when commands are specified but no valid command can be determined from the command line options.
protected
handle_default(mixed $opts, mixed $params) : mixed
This version simply calls the the error() method with the no_command_message property.
Feel free to override in your subclass if so desired.
Parameters
- $opts : mixed
- $params : mixed
Return values
mixed —handle_help()
A default handler for the 'help' command.
protected
handle_help(mixed $opts, mixed $params) : mixed
Returns the output from the $params->getHelp() method.
Parameters
- $opts : mixed
- $params : mixed
Return values
mixed —handle_help_usage()
A default handler for the 'help_usage' command.
protected
handle_help_usage(mixed $opts, mixed $params) : mixed
Depending on the value of the $params->help_usage_combo parameter, this will either return $params->getUsage() or $params->getHelp().
Parameters
- $opts : mixed
- $params : mixed
Return values
mixed —handle_usage()
A default handler for the 'usage' command.
protected
handle_usage(mixed $opts, mixed $params) : mixed
Returns the output from the $params->getUsage() method.
Parameters
- $opts : mixed
- $params : mixed
Return values
mixed —initialize_params()
Implement this method in your class to set up the Params object.
protected
abstract initialize_params(Params $params, array<string|int, mixed> $opts) : mixed
You can use the public methods in the Params instance to define any parameters and parameter groups for your app using a friendly syntax.
Parameters
- $params : Params
-
The Params object created by the constructor.
- $opts : array<string|int, mixed>
-
The options passed to the constructor.