Understanding how Console Arguments and Options Are Handled

Edit this page

Symfony Console applications follow the same docopt standard used in most CLI utility tools. This article explains how to handle edge-cases when the commands define options with required values, without values, etc. Read this other article to learn about using arguments and options inside Symfony Console commands.

Have a look at the following command that has three options:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
namespace Acme\Console\Command;

use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Attribute\Option;

#[AsCommand(name: 'demo:args', description: 'Describe args behaviors')]
class DemoArgsCommand
{
    public function __invoke(
        #[Option(shortcut: 'f')] bool $foo = false,
        #[Option(shortcut: 'b')] string $bar = '',
        #[Option(shortcut: 'c')] string|bool $cat = false,
    ): int {
        // ...
    }
}

This example uses invokable commands with the #[Option] attribute. If you prefer the classic approach:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
namespace Acme\Console\Command;

use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputDefinition;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Output\OutputInterface;

#[AsCommand(name: 'demo:args', description: 'Describe args behaviors')]
class DemoArgsCommand extends Command
{
    protected function configure(): void
    {
        $this
            ->setDefinition(
                new InputDefinition([
                    new InputOption('foo', 'f'),
                    new InputOption('bar', 'b', InputOption::VALUE_REQUIRED),
                    new InputOption('cat', 'c', InputOption::VALUE_OPTIONAL),
                ])
            );
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        // ...
    }
}

Since the foo option doesn't accept a value, it will be either false (when it is not passed to the command) or true (when --foo was passed by the user). The value of the bar option (and its b shortcut respectively) is required. It can be separated from the option name either by spaces or = characters. The cat option (and its c shortcut) behaves similar except that it doesn't require a value. Have a look at the following table to get an overview of the possible ways to pass options:

Input foo bar cat
--bar=Hello false "Hello" null
--bar Hello false "Hello" null
-b=Hello false "=Hello" null
-b Hello false "Hello" null
-bHello false "Hello" null
-fcWorld -b Hello true "Hello" "World"
-cfWorld -b Hello false "Hello" "fWorld"
-cbWorld false null "bWorld"

Things get a little bit more tricky when the command also accepts an optional argument:

1
2
3
4
5
6
// ...

new InputDefinition([
    // ...
    new InputArgument('arg', InputArgument::OPTIONAL),
]);

You might have to use the special -- separator to separate options from arguments. Have a look at the fifth example in the following table where it is used to tell the command that World is the value for arg and not the value of the optional cat option:

Input bar cat arg
--bar Hello "Hello" null null
--bar Hello World "Hello" null "World"
--bar "Hello World" "Hello World" null null
--bar Hello --cat World "Hello" "World" null
--bar Hello --cat -- World "Hello" null "World"
-b Hello -c World "Hello" "World" null

Option Attribute Constraints

When using the #[Option] attribute in invokable commands, the following rules are enforced to ensure consistent behavior:

  • Options must always have a default value. Unlike arguments, options cannot be required since users may simply not provide them;
  • Nullable bool options (?bool) cannot have a true or false default. Use null as the default to enable negatable behavior;
  • Nullable non-bool options (e.g. ?string) must have null as the default value;
  • Union types are only allowed for string|bool, int|bool, and float|bool, and must have false as the default value.

Examples of valid option definitions:

1
2
3
4
5
6
7
8
#[Option] bool $verbose = false           // VALUE_NONE
#[Option] bool $colors = true             // VALUE_NEGATABLE (--colors or --no-colors)
#[Option] ?bool $debug = null             // VALUE_NEGATABLE (--debug or --no-debug)
#[Option] string $format = 'json'         // VALUE_REQUIRED
#[Option] ?string $filter = null          // VALUE_REQUIRED (optional value)
#[Option] int $limit = 10                 // VALUE_REQUIRED
#[Option] array $roles = []               // VALUE_IS_ARRAY
#[Option] string|bool $output = false     // VALUE_OPTIONAL (--output or --output=file.txt)

Examples of invalid option definitions:

1
2
3
4
5
#[Option] string $format                  // ERROR: no default value
#[Option] ?bool $debug = true             // ERROR: nullable bool with true default
#[Option] ?string $filter = 'default'     // ERROR: nullable with non-null default
#[Option] string|bool $output = true      // ERROR: union type with true default
#[Option] array|bool $items = false       // ERROR: unsupported union type
This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version