|
| 1 | +.. index:: |
| 2 | + single: Console; Console arguments |
| 3 | + |
| 4 | +Understand how Console Arguments are Handled |
| 5 | +============================================ |
| 6 | + |
| 7 | +It can be difficult to understand the way arguments are handled by the console application. |
| 8 | +The Symfony Console application, like many other CLI utility tools, follows the behavior |
| 9 | +described in the `docopt`_ standards. |
| 10 | + |
| 11 | +Have a look at the following command that has three options:: |
| 12 | + |
| 13 | + namespace Acme\Console\Command; |
| 14 | + |
| 15 | + use Symfony\Component\Console\Command\Command; |
| 16 | + use Symfony\Component\Console\Input\InputArgument; |
| 17 | + use Symfony\Component\Console\Input\InputInterface; |
| 18 | + use Symfony\Component\Console\Input\InputOption; |
| 19 | + use Symfony\Component\Console\Output\OutputInterface; |
| 20 | + |
| 21 | + class DemoArgsCommand extends Command |
| 22 | + { |
| 23 | + protected function configure() |
| 24 | + { |
| 25 | + $this |
| 26 | + ->setName('demo:args') |
| 27 | + ->setDescription('Describe args behaviors') |
| 28 | + ->setDefinition( |
| 29 | + new InputDefinition(array( |
| 30 | + new InputOption('foo', 'f'), |
| 31 | + new InputOption('bar', 'b', InputOption::VALUE_REQUIRED), |
| 32 | + new InputOption('cat', 'c', InputOption::VALUE_OPTIONAL), |
| 33 | + )) |
| 34 | + ); |
| 35 | + } |
| 36 | + |
| 37 | + protected function execute(InputInterface $input, OutputInterface $output) |
| 38 | + { |
| 39 | + // ... |
| 40 | + } |
| 41 | + } |
| 42 | + |
| 43 | +Since the ``foo`` option doesn't accept a value, it will be either ``false`` |
| 44 | +(when it is not passed to the command) or ``true`` (when ``--foo`` was passed |
| 45 | +by the user). The value of the ``bar`` option (and its ``b`` shortcut respectively) |
| 46 | +is required. It can be separated from the option name either by spaces or |
| 47 | +``=`` characters. The ``cat`` option (and its ``c`` shortcut) behaves similar |
| 48 | +except that it doesn't require a value. Have a look at the following table |
| 49 | +to get an overview of the possible ways to pass options: |
| 50 | + |
| 51 | +===================== ========= =========== ============ |
| 52 | +Input ``foo`` ``bar`` ``cat`` |
| 53 | +===================== ========= =========== ============ |
| 54 | +``--bar=Hello`` ``false`` ``"Hello"`` ``null`` |
| 55 | +``--bar Hello`` ``false`` ``"Hello"`` ``null`` |
| 56 | +``-b=Hello`` ``false`` ``"Hello"`` ``null`` |
| 57 | +``-b Hello`` ``false`` ``"Hello"`` ``null`` |
| 58 | +``-bHello`` ``false`` ``"Hello"`` ``null`` |
| 59 | +``-fcWorld -b Hello`` ``true`` ``"Hello"`` ``"World"`` |
| 60 | +``-cfWorld -b Hello`` ``false`` ``"Hello"`` ``"fWorld"`` |
| 61 | +``-cbWorld`` ``false`` ``null`` ``"bWorld"`` |
| 62 | +===================== ========= =========== ============ |
| 63 | + |
| 64 | +Things get a little bit more tricky when the command also accepts an optional |
| 65 | +argument:: |
| 66 | + |
| 67 | + // ... |
| 68 | + |
| 69 | + new InputDefinition(array( |
| 70 | + // ... |
| 71 | + new InputArgument('arg', InputArgument::OPTIONAL), |
| 72 | + )); |
| 73 | + |
| 74 | +You might have to use the special ``--`` separator to separate options from |
| 75 | +arguments. Have a look at the fifth example in the following table where it |
| 76 | +is used to tell the command that ``World`` is the value for ``arg`` and not |
| 77 | +the value of the optional ``cat`` option: |
| 78 | + |
| 79 | +============================== ================= =========== =========== |
| 80 | +Input ``bar`` ``cat`` ``arg`` |
| 81 | +============================== ================= =========== =========== |
| 82 | +``--bar Hello`` ``"Hello"`` ``null`` ``null`` |
| 83 | +``--bar Hello World`` ``"Hello"`` ``null`` ``"World"`` |
| 84 | +``--bar "Hello World"`` ``"Hello World"`` ``null`` ``null`` |
| 85 | +``--bar Hello --cat World`` ``"Hello"`` ``"World"`` ``null`` |
| 86 | +``--bar Hello --cat -- World`` ``"Hello"`` ``null`` ``"World"`` |
| 87 | +``-b Hello -c World`` ``"Hello"`` ``"World"`` ``null`` |
| 88 | +============================== ================= =========== =========== |
| 89 | + |
| 90 | +.. _docopt: http://docopt.org/ |
0 commit comments