Args options are passed after the command name(s). Each option has a
long name that is prefixed by two dashes ("--") and optionally a short name
that is prefixed by one dash only ("-"). The long name must have at least
two characters, the short name must contain a single letter only.
In the example below, "--verbose" and "-v" are the long and short names of
the same option:
$ console server --verbose
$ console server -v
The long and short names are passed to the constructor of this class. The
leading dashes can be omitted:
php
$option = new Option('verbose', 'v');
If an option accepts a value, you must pass one of the flags
{@link VALUE_REQUIRED}, {@link VALUE_OPTIONAL} or {@link MULTI_VALUED} to
the constructor:
php
$option = new Option('format', 'f', Option::VALUE_REQUIRED);
* The flag {@link VALUE_REQUIRED} indicates that a value must always be
passed.
* The flag {@link VALUE_OPTIONAL} indicates that a value may optionally be
passed. If no value is passed, the default value passed to the constructor
is returned, which defaults to null.
* The flag {@link MULTI_VALUED} indicates that the option can be passed
multiple times with different values. The passed values are returned to
the application as array. The value of a multi-valued option is always
required.
/**
* Adds an option at the end of the options list.
*
* The existing options stored in the builder are preserved.
*
* @param Option $option The option to add.
*
* @return static The current instance.
*
* @throws CannotAddOptionException If the option cannot be added.
*
* @see addOptions()
*/
public function addOption(Option $option)
{
$longName = $option->getLongName();
$shortName = $option->getShortName();
if ($this->hasOption($longName) || $this->hasCommandOption($longName)) {
throw CannotAddOptionException::existsAlready($longName);
}
if ($shortName && ($this->hasOption($shortName) || $this->hasCommandOption($shortName))) {
throw CannotAddOptionException::existsAlready($shortName);
}
$this->options[$longName] = $option;
if ($shortName) {
$this->optionsByShortName[$shortName] = $option;
}
return $this;
}
/**
* Renders an option.
*
* @param BlockLayout $layout The layout.
* @param Option $option The option to render.
*/
protected function renderOption(BlockLayout $layout, Option $option)
{
$description = $option->getDescription();
$defaultValue = $option->getDefaultValue();
if ($option->isLongNamePreferred()) {
$preferredName = '--' . $option->getLongName();
$alternativeName = $option->getShortName() ? '-' . $option->getShortName() : null;
} else {
$preferredName = '-' . $option->getShortName();
$alternativeName = '--' . $option->getLongName();
}
$name = '<c1>' . $preferredName . '</c1>';
if ($alternativeName) {
$name .= sprintf(' (%s)', $alternativeName);
}
if ($option->acceptsValue() && null !== $defaultValue && (!is_array($defaultValue) || count($defaultValue))) {
$description .= sprintf(' <b>(default: %s)</b>', $this->formatValue($defaultValue));
}
if ($option->isMultiValued()) {
$description .= ' <b>(multiple values allowed)</b>';
}
$layout->add(new LabeledParagraph($name, $description));
}
/**
* Creates an input option for the given option.
*
* @param Option $option The option.
*
* @return InputOption The created input option.
*/
private function adaptOption(Option $option)
{
$mode = null;
if ($option->isMultiValued()) {
$mode |= InputOption::VALUE_IS_ARRAY;
}
if ($option->isValueOptional()) {
$mode |= InputOption::VALUE_OPTIONAL;
}
if ($option->isValueRequired()) {
$mode |= InputOption::VALUE_REQUIRED;
}
return new InputOption($option->getLongName(), $option->getShortName(), $mode, $option->getDescription(), $option->getDefaultValue());
}
/**
* @dataProvider getInvalidParseValueTests
* @expectedException \Webmozart\Console\Api\Args\Format\InvalidValueException
*/
public function testParseValueFailsIfInvalid($flags, $input)
{
$option = new Option('option', 'o', $flags);
$option->parseValue($input);
}
