W3cubDocs

/CakePHP 4.1

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 my_command --connection default --name=something

Short options can be defined singly or in groups.

cake my_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 my_command -c -n

Short options can also accept values:

cake my_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

Properties 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()

  • $_subcommandSort protected
    bool

    Subcommand sorting option

  • $_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.

  • 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.

  • addSubcommand() public

    Append a subcommand to the subcommand list.

  • addSubcommands() public

    Add multiple subcommands at once.

  • argumentNames() public

    Get the list of argument names.

  • arguments() public

    Gets the arguments defined in the parser.

  • buildFromArray() public static

    Build a parser from an array. Uses an array like

  • create() public static

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

  • enableSubcommandSort() public

    Enables sorting of subcommands

  • getCommand() public

    Gets the command name for shell/task.

  • getDescription() public

    Gets the description text for shell/task.

  • getEpilog() public

    Gets the epilog.

  • help() public

    Gets formatted help for this parser object.

  • isSubcommandSortEnabled() public

    Checks whether or not sorting is enabled for subcommands.

  • 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.

  • 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 $command, bool $defaultOptions)

Construct an OptionParser so you can define its behavior

Parameters

string $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()

Find the next token in the argv set.

Returns

string

next token or ''

_optionExists() protected 

_optionExists(string $name)

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)

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

string[]

Args

Throws

Cake\Console\Exception\ConsoleException

_parseLongOption() protected 

_parseLongOption(string $option, array $params)

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

Params with $option added in.

_parseOption() protected 

_parseOption(string $name, array $params)

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

Params with $option added in.

Throws

Cake\Console\Exception\ConsoleException

_parseShortOption() protected 

_parseShortOption(string $option, array $params)

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

Params with $option added in.

Throws

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

addArgument() public 

addArgument(mixed $name, array $params)

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)

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

See Also

\Cake\Console\ConsoleOptionParser::addArgument()

addOption() public 

addOption(mixed $name, array $options)

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)

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

See Also

\Cake\Console\ConsoleOptionParser::addOption()

addSubcommand() public 

addSubcommand(mixed $name, array $options)

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)

Add multiple subcommands at once.

Parameters

array $commands

Array of subcommands.

Returns

$this

argumentNames() public 

argumentNames()

Get the list of argument names.

Returns

string[]

arguments() public 

arguments()

Gets the arguments defined in the parser.

Returns

\Cake\Console\ConsoleInputArgument[]

buildFromArray() public static 

buildFromArray(array $spec, bool $defaultOptions)

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

create() public static 

create(string $command, bool $defaultOptions)

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

Parameters

string $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

enableSubcommandSort() public 

enableSubcommandSort(bool $value)

Enables sorting of subcommands

Parameters

bool $value optional

Whether or not to sort subcommands

Returns

$this

getCommand() public 

getCommand()

Gets the command name for shell/task.

Returns

string

The value of the command.

getDescription() public 

getDescription()

Gets the description text for shell/task.

Returns

string

The value of the description

getEpilog() public 

getEpilog()

Gets the epilog.

Returns

string

The value of the epilog.

help() public 

help(?string $subcommand, string $format, int $width)

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

Generated help.

isSubcommandSortEnabled() public 

isSubcommandSortEnabled()

Checks whether or not sorting is enabled for subcommands.

Returns

bool

merge() public 

merge(mixed $spec)

Get or set the command name for shell/task.

Parameters

array|\Cake\Console\ConsoleOptionParser $spec

ConsoleOptionParser or spec to merge with.

Returns

$this

options() public 

options()

Get the defined options in the parser.

Returns

\Cake\Console\ConsoleInputOption[]

parse() public 

parse(array $argv)

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

[$params, $args]

Throws

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

removeOption() public 

removeOption(string $name)

Remove an option from the option parser.

Parameters

string $name

The option name to remove.

Returns

$this

removeSubcommand() public 

removeSubcommand(string $name)

Remove a subcommand from the option parser.

Parameters

string $name

The subcommand name to remove.

Returns

$this

setCommand() public 

setCommand(string $text)

Sets the command name for shell/task.

Parameters

string $text

The text to set.

Returns

$this

setDescription() public 

setDescription(mixed $text)

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(mixed $text)

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

setRootName() public 

setRootName(string $name)

Set the root name used in the HelpFormatter

Parameters

string $name

The root command name

Returns

$this

subcommands() public 

subcommands()

Get the array of defined subcommands

Returns

\Cake\Console\ConsoleInputSubcommand[]

toArray() public 

toArray()

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

$_subcommandSort protected

Subcommand sorting option

Type

bool

$_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

© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/4.1/class-Cake.Console.ConsoleOptionParser.html