Class ConsoleOptionParser

Handles parsing the ARGV in the command line and provides support for GetOpt compatible option definition. Provides a builder pattern implementation for creating shell option parsers.

Options

Named arguments come in two forms, long and short. Long arguments are preceded by two - and give a more verbose option name. i.e. --version. Short arguments are preceded by one - and are only one character long. They usually match with a long option, and provide a more terse alternative.

Using Options

Options can be defined with both long and short forms. By using $parser->addOption() you can define new options. The name of the option is used as its long form, and you can supply an additional short form, with the short option. Short options should only be one letter long. Using more than one letter for a short option will raise an exception.

Calling options can be done using syntax similar to most *nix command line tools. Long options cane either include an = or leave it out.

cake myshell command --connection default --name=something

Short options can be defined singly or in groups.

cake myshell command -cn

Short options can be combined into groups as seen above. Each letter in a group will be treated as a separate option. The previous example is equivalent to:

cake myshell command -c -n

Short options can also accept values:

cake myshell command -c default

Positional arguments

If no positional arguments are defined, all of them will be parsed. If you define positional arguments any arguments greater than those defined will cause exceptions. Additionally you can declare arguments as optional, by setting the required param to false.

$parser->addArgument('model', ['required' => false]);

Providing Help text

By providing help text for your positional arguments and named arguments, the ConsoleOptionParser can generate a help display for you. You can view the help for shells by using the --help or -h switch.

Namespace: Cake\Console

Property Summary

$_args protected

Cake\Console\ConsoleInputArgument[]

Positional argument definitions.
$_command protected

string

Command name.
$_description protected

string

Description text - displays before options when help is generated
$_epilog protected

string

Epilog text - displays after options when help is generated
$_options protected

Cake\Console\ConsoleInputOption[]

Option definitions.
$_shortOptions protected

array

Map of short -> long options, generated when using addOption()
$_subcommands protected

Cake\Console\ConsoleInputSubcommand[]

Subcommands for this Shell.
$_tokens protected

array

Array of args (argv).
$rootName protected

string

Root alias used in help output

Method Summary

__construct() public

Construct an OptionParser so you can define its behavior
_nextToken() protected

Find the next token in the argv set.
_optionExists() protected

Check to see if $name has an option (short/long) defined for it.
_parseArg() protected

Parse an argument, and ensure that the argument doesn't exceed the number of arguments and that the argument is a valid choice.
_parseLongOption() protected

Parse the value for a long option out of $this->_tokens. Will handle options with an = in them.
_parseOption() protected

Parse an option by its name index.
_parseShortOption() protected

Parse the value for a short option out of $this->_tokens If the $option is a combination of multiple shortcuts like -otf they will be shifted onto the token stack and parsed individually.
addArgument() public

Add a positional argument to the option parser.
addArguments() public

Add multiple arguments at once. Take an array of argument definitions. The keys are used as the argument names, and the values as params for the argument.
addOption() public

Add an option to the option parser. Options allow you to define optional or required parameters for your console application. Options are defined by the parameters they use.
addOptions() public

Add multiple options at once. Takes an array of option definitions. The keys are used as option names, and the values as params for the option.
addSubcommand() public

Append a subcommand to the subcommand list. Subcommands are usually methods on your Shell, but can also be used to document Tasks.
addSubcommands() public

Add multiple subcommands at once.
arguments() public

Gets the arguments defined in the parser.
buildFromArray() public static

Build a parser from an array. Uses an array like
command() public deprecated

Gets or sets the command name for shell/task.
create() public static

Static factory method for creating new OptionParsers so you can chain methods off of them.
description() public deprecated

Get or set the description text for shell/task.
epilog() public deprecated

Gets or sets an epilog to the parser. The epilog is added to the end of the options and arguments listing when help is generated.
findClosestItem() protected

Tries to guess the item name the user originally wanted using the some regex pattern and the levenshtein algorithm.
getCommand() public

Gets the command name for shell/task.
getCommandError() protected

Get the message output in the console stating that the command can not be found and tries to guess what the user wanted to say. Output a list of available subcommands as well.
getDescription() public

Gets the description text for shell/task.
getEpilog() public

Gets the epilog.
getOptionError() protected

Get the message output in the console stating that the option can not be found and tries to guess what the user wanted to say. Output a list of available options as well.
getShortOptionError() protected

Get the message output in the console stating that the short option can not be found. Output a list of available short options and what option they refer to as well.
help() public

Gets formatted help for this parser object.
merge() public

Get or set the command name for shell/task.
options() public

Get the defined options in the parser.
parse() public

Parse the argv array into a set of params and args. If $command is not null and $command is equal to a subcommand that has a parser, that parser will be used to parse the $argv
removeOption() public

Remove an option from the option parser.
removeSubcommand() public

Remove a subcommand from the option parser.
setCommand() public

Sets the command name for shell/task.
setDescription() public

Sets the description text for shell/task.
setEpilog() public

Sets an epilog to the parser. The epilog is added to the end of the options and arguments listing when help is generated.
setHelpAlias() public deprecated

Set the alias used in the HelpFormatter
setRootName() public

Set the root name used in the HelpFormatter
subcommands() public

Get the array of defined subcommands
toArray() public

Returns an array representation of this parser.

Method Detail

__construct() ¶ public

__construct(string|null $command = null, bool $defaultOptions = true)

Construct an OptionParser so you can define its behavior

Parameters

string|null $command optional: The command name this parser is for. The command name is used for generating help.
bool $defaultOptions optional: Whether you want the verbose and quiet options set. Setting this to false will prevent the addition of --verbose & --quiet options.

_nextToken() ¶ protected

_nextToken(): string

Find the next token in the argv set.

Returns

string

_optionExists() ¶ protected

_optionExists(string $name): bool

Check to see if $name has an option (short/long) defined for it.

Parameters

string $name: The name of the option.

Returns

bool

_parseArg() ¶ protected

_parseArg(string $argument, array $args): array

Parse an argument, and ensure that the argument doesn't exceed the number of arguments and that the argument is a valid choice.

Parameters

string $argument: The argument to append
array $args: The array of parsed args to append to.

Returns

array

Throws

Cake\Console\Exception\ConsoleException

_parseLongOption() ¶ protected

_parseLongOption(string $option, array $params): array

Parse the value for a long option out of $this->_tokens. Will handle options with an = in them.

Parameters

string $option: The option to parse.
array $params: The params to append the parsed value into

Returns

array

_parseOption() ¶ protected

_parseOption(string $name, array $params): array

Parse an option by its name index.

Parameters

string $name: The name to parse.
array $params: The params to append the parsed value into

Returns

array

Throws

Cake\Console\Exception\ConsoleException

_parseShortOption() ¶ protected

_parseShortOption(string $option, array $params): array

Parse the value for a short option out of $this->_tokens If the $option is a combination of multiple shortcuts like -otf they will be shifted onto the token stack and parsed individually.

Parameters

string $option: The option to parse.
array $params: The params to append the parsed value into

Returns

array

Throws

Cake\Console\Exception\ConsoleException
When unknown short options are encountered.

addArgument() ¶ public

addArgument(Cake\Console\ConsoleInputArgument|string $name, array $params = []): $this

Add a positional argument to the option parser.

Params

help The help text to display for this argument.
required Whether this parameter is required.
index The index for the arg, if left undefined the argument will be put onto the end of the arguments. If you define the same index twice the first option will be overwritten.
choices A list of valid choices for this argument. If left empty all values are valid.. An exception will be raised when parse() encounters an invalid value.

Parameters

Cake\Console\ConsoleInputArgument|string $name: The name of the argument. Will also accept an instance of ConsoleInputArgument.
array $params optional: Parameters for the argument, see above.

Returns

$this

addArguments() ¶ public

addArguments(array $args): $this

Add multiple arguments at once. Take an array of argument definitions. The keys are used as the argument names, and the values as params for the argument.

Parameters

array $args: Array of arguments to add.

Returns

$this

addOption() ¶ public

addOption(Cake\Console\ConsoleInputOption|string $name, array $options = []): $this

Add an option to the option parser. Options allow you to define optional or required parameters for your console application. Options are defined by the parameters they use.

Options

short - The single letter variant for this option, leave undefined for none.
help - Help text for this option. Used when generating help for the option.
default - The default value for this option. Defaults are added into the parsed params when the attached option is not provided or has no value. Using default and boolean together will not work. are added into the parsed parameters when the option is undefined. Defaults to null.
boolean - The option uses no value, it's just a boolean switch. Defaults to false. If an option is defined as boolean, it will always be added to the parsed params. If no present it will be false, if present it will be true.
multiple - The option can be provided multiple times. The parsed option will be an array of values when this option is enabled.
choices A list of valid choices for this option. If left empty all values are valid.. An exception will be raised when parse() encounters an invalid value.

Parameters

Cake\Console\ConsoleInputOption|string $name: The long name you want to the value to be parsed out as when options are parsed. Will also accept an instance of ConsoleInputOption
array $options optional: An array of parameters that define the behavior of the option

Returns

$this

addOptions() ¶ public

addOptions(array $options): $this

Add multiple options at once. Takes an array of option definitions. The keys are used as option names, and the values as params for the option.

Parameters

array $options: Array of options to add.

Returns

$this

addSubcommand() ¶ public

addSubcommand(Cake\Console\ConsoleInputSubcommand|string $name, array $options = []): $this

Append a subcommand to the subcommand list. Subcommands are usually methods on your Shell, but can also be used to document Tasks.

Options

help - Help text for the subcommand.
parser - A ConsoleOptionParser for the subcommand. This allows you to create method specific option parsers. When help is generated for a subcommand, if a parser is present it will be used.

Parameters

Cake\Console\ConsoleInputSubcommand|string $name: Name of the subcommand. Will also accept an instance of ConsoleInputSubcommand
array $options optional: Array of params, see above.

Returns

$this

addSubcommands() ¶ public

addSubcommands(array $commands): $this

Add multiple subcommands at once.

Parameters

array $commands: Array of subcommands.

Returns

$this

arguments() ¶ public

arguments(): Cake\Console\ConsoleInputArgument[]

Gets the arguments defined in the parser.

Returns

Cake\Console\ConsoleInputArgument[]

buildFromArray() ¶ public static

buildFromArray(array $spec, bool $defaultOptions = true): static

Build a parser from an array. Uses an array like

$spec = [
     'description' => 'text',
     'epilog' => 'text',
     'arguments' => [
         // list of arguments compatible with addArguments.
     ],
     'options' => [
         // list of options compatible with addOptions
     ],
     'subcommands' => [
         // list of subcommands to add.
     ]
];

Parameters

array $spec: The spec to build the OptionParser with.
bool $defaultOptions optional: Whether you want the verbose and quiet options set.

Returns

static

command() ¶ public

command(string|null $text = null): string|$this

Gets or sets the command name for shell/task.

Parameters

string|null $text optional: The text to set, or null if you want to read

Returns

string|$this

create() ¶ public static

create(string|null $command, bool $defaultOptions = true): static

Static factory method for creating new OptionParsers so you can chain methods off of them.

Parameters

string|null $command: The command name this parser is for. The command name is used for generating help.
bool $defaultOptions optional: Whether you want the verbose and quiet options set.

Returns

static

description() ¶ public

description(string|array|null $text = null): string|$this

Get or set the description text for shell/task.

Parameters

string|array|null $text optional: The text to set, or null if you want to read. If an array the text will be imploded with "\n".

Returns

string|$this

epilog() ¶ public

epilog(string|array|null $text = null): string|$this

Gets or sets an epilog to the parser. The epilog is added to the end of the options and arguments listing when help is generated.

Parameters

string|array|null $text optional: Text when setting or null when reading. If an array the text will be imploded with "\n".

Returns

string|$this

findClosestItem() ¶ protected

findClosestItem(string $needle, array $haystack): string|null

Tries to guess the item name the user originally wanted using the some regex pattern and the levenshtein algorithm.

Parameters

string $needle: Unknown item (either a subcommand name or an option for instance) trying to be used.
array $haystack: List of items available for the type $needle belongs to.

Returns

string|null

getCommand() ¶ public

getCommand(): string

Gets the command name for shell/task.

Returns

string

getCommandError() ¶ protected

getCommandError(string $command): string

Get the message output in the console stating that the command can not be found and tries to guess what the user wanted to say. Output a list of available subcommands as well.

Parameters

string $command: Unknown command name trying to be dispatched.

Returns

string

getDescription() ¶ public

getDescription(): string

Gets the description text for shell/task.

Returns

string

getEpilog() ¶ public

getEpilog(): string

Gets the epilog.

Returns

string

getOptionError() ¶ protected

getOptionError(string $option): string

Get the message output in the console stating that the option can not be found and tries to guess what the user wanted to say. Output a list of available options as well.

Parameters

string $option: Unknown option name trying to be used.

Returns

string

getShortOptionError() ¶ protected

getShortOptionError(string $option): string

Get the message output in the console stating that the short option can not be found. Output a list of available short options and what option they refer to as well.

Parameters

string $option: Unknown short option name trying to be used.

Returns

string

help() ¶ public

help(string|null $subcommand = null, string $format = 'text', int $width = 72): string

Gets formatted help for this parser object.

Generates help text based on the description, options, arguments, subcommands and epilog in the parser.

Parameters

string|null $subcommand optional: If present and a valid subcommand that has a linked parser. That subcommands help will be shown instead.
string $format optional: Define the output format, can be text or xml
int $width optional: The width to format user content to. Defaults to 72

Returns

string

merge() ¶ public

merge(arrayCake\Console\ConsoleOptionParser $spec): $this

Get or set the command name for shell/task.

Parameters

arrayCake\Console\ConsoleOptionParser $spec: ConsoleOptionParser or spec to merge with.

Returns

$this

options() ¶ public

options(): Cake\Console\ConsoleInputOption[]

Get the defined options in the parser.

Returns

Cake\Console\ConsoleInputOption[]

parse() ¶ public

parse(array $argv): array

Parse the argv array into a set of params and args. If $command is not null and $command is equal to a subcommand that has a parser, that parser will be used to parse the $argv

Parameters

array $argv: Array of args (argv) to parse.

Returns

array

Throws

Cake\Console\Exception\ConsoleException
When an invalid parameter is encountered.

removeOption() ¶ public

removeOption(string $name): $this

Remove an option from the option parser.

Parameters

string $name: The option name to remove.

Returns

$this

removeSubcommand() ¶ public

removeSubcommand(string $name): $this

Remove a subcommand from the option parser.

Parameters

string $name: The subcommand name to remove.

Returns

$this

setCommand() ¶ public

setCommand(string $text): $this

Sets the command name for shell/task.

Parameters

string $text: The text to set.

Returns

$this

setDescription() ¶ public

setDescription(string|array $text): $this

Sets the description text for shell/task.

Parameters

string|array $text: The text to set. If an array the text will be imploded with "\n".

Returns

$this

setEpilog() ¶ public

setEpilog(string|array $text): $this

Sets an epilog to the parser. The epilog is added to the end of the options and arguments listing when help is generated.

Parameters

string|array $text: The text to set. If an array the text will be imploded with "\n".

Returns

$this

setHelpAlias() ¶ public

setHelpAlias(string $alias): void

Set the alias used in the HelpFormatter

Parameters

string $alias: The alias

Returns

void

setRootName() ¶ public

setRootName(string $name): $this

Set the root name used in the HelpFormatter

Parameters

string $name: The root command name

Returns

$this

subcommands() ¶ public

subcommands(): Cake\Console\ConsoleInputSubcommand[]

Get the array of defined subcommands

Returns

Cake\Console\ConsoleInputSubcommand[]

toArray() ¶ public

toArray(): array

Returns an array representation of this parser.

Returns

array

Property Detail

`$_args` ¶ protected

Positional argument definitions.

Type

Cake\Console\ConsoleInputArgument[]

`$_command` ¶ protected

Command name.

Type

string

`$_description` ¶ protected

Description text - displays before options when help is generated

Type

string

`$_epilog` ¶ protected

Epilog text - displays after options when help is generated

Type

string

`$_options` ¶ protected

Option definitions.

Type

Cake\Console\ConsoleInputOption[]

`$_shortOptions` ¶ protected

Map of short -> long options, generated when using addOption()

Type

array

`$_subcommands` ¶ protected

Subcommands for this Shell.

Type

Cake\Console\ConsoleInputSubcommand[]

`$_tokens` ¶ protected

Array of args (argv).

Type

array

`$rootName` ¶ protected

Root alias used in help output

Type

string

Namespaces

Class ConsoleOptionParser

Options

Using Options

Positional arguments

Providing Help text

Property Summary

Method Summary

__construct() public

_nextToken() protected

_optionExists() protected

_parseArg() protected

_parseLongOption() protected

_parseOption() protected

_parseShortOption() protected

addArgument() public

addArguments() public

addOption() public

addOptions() public

addSubcommand() public

addSubcommands() public

arguments() public

buildFromArray() public static

command() public deprecated

create() public static

description() public deprecated

epilog() public deprecated

findClosestItem() protected

getCommand() public

getCommandError() protected

getDescription() public

getEpilog() public

getOptionError() protected

getShortOptionError() protected

help() public

merge() public

options() public

parse() public

removeOption() public

removeSubcommand() public

setCommand() public

setDescription() public

setEpilog() public

setHelpAlias() public deprecated

setRootName() public

subcommands() public

toArray() public

Method Detail

__construct() ¶ public

Parameters

_nextToken() ¶ protected

Returns

_optionExists() ¶ protected

Parameters

Returns

_parseArg() ¶ protected

Parameters

Returns

Throws

_parseLongOption() ¶ protected

Parameters

Returns

_parseOption() ¶ protected

Parameters

Returns

Throws

_parseShortOption() ¶ protected

Parameters

Returns

Throws

addArgument() ¶ public

Params

Parameters

Returns

addArguments() ¶ public

Parameters

Returns

See Also

addOption() ¶ public

Options