|
| 1 | +Console Input (Arguments & Options) |
| 2 | +=================================== |
| 3 | + |
| 4 | +The most interesting part of the commands are the arguments and options that |
| 5 | +you can make available. These arguments and options allow you to pass dynamic |
| 6 | +information from the terminal to the command. |
| 7 | + |
| 8 | +Using Command Arguments |
| 9 | +----------------------- |
| 10 | + |
| 11 | +Arguments are the strings - separated by spaces - that |
| 12 | +come after the command name itself. They are ordered, and can be optional |
| 13 | +or required. For example, to add an optional ``last_name`` argument to the command |
| 14 | +and make the ``name`` argument required:: |
| 15 | + |
| 16 | + // ... |
| 17 | + use Symfony\Component\Console\Input\InputArgument; |
| 18 | + |
| 19 | + class GreetCommand extends Command |
| 20 | + { |
| 21 | + // ... |
| 22 | + |
| 23 | + protected function configure() |
| 24 | + { |
| 25 | + $this |
| 26 | + // ... |
| 27 | + ->addArgument('name', InputArgument::REQUIRED, 'Who do you want to greet?') |
| 28 | + ->addArgument('last_name', InputArgument::OPTIONAL, 'Your last name?') |
| 29 | + ; |
| 30 | + } |
| 31 | + } |
| 32 | + |
| 33 | +You now have access to a ``last_name`` argument in your command:: |
| 34 | + |
| 35 | + // ... |
| 36 | + class GreetCommand extends Command |
| 37 | + { |
| 38 | + // ... |
| 39 | + |
| 40 | + protected function execute(InputInterface $input, OutputInterface $output) |
| 41 | + { |
| 42 | + $text = 'Hi '.$input->getArgument('name'); |
| 43 | + |
| 44 | + $lastName = $input->getArgument('last_name') |
| 45 | + if ($lastName) { |
| 46 | + $text .= ' '.$lastName; |
| 47 | + } |
| 48 | + |
| 49 | + $output->writeln($text.'!'); |
| 50 | + } |
| 51 | + } |
| 52 | + |
| 53 | +The command can now be used in either of the following ways: |
| 54 | + |
| 55 | +.. code-block:: bash |
| 56 | +
|
| 57 | + $ php app/console app:greet Fabien |
| 58 | + Hi Fabien! |
| 59 | +
|
| 60 | + $ php app/console app:greet Fabien Potencier |
| 61 | + Hi Fabien Potencier! |
| 62 | +
|
| 63 | +It is also possible to let an argument take a list of values (imagine you want |
| 64 | +to greet all your friends). Only the last argument can be a list:: |
| 65 | + |
| 66 | + $this |
| 67 | + // ... |
| 68 | + ->addArgument( |
| 69 | + 'names', |
| 70 | + InputArgument::IS_ARRAY, |
| 71 | + 'Who do you want to greet (separate multiple names with a space)?' |
| 72 | + ); |
| 73 | + |
| 74 | +To use this, just specify as many names as you want: |
| 75 | + |
| 76 | +.. code-block:: bash |
| 77 | +
|
| 78 | + $ php app/console app:greet Fabien Ryan Bernhard |
| 79 | +
|
| 80 | +You can access the ``names`` argument as an array:: |
| 81 | + |
| 82 | + $names = $input->getArgument('names') |
| 83 | + if (count($names) > 0) { |
| 84 | + $text .= ' '.implode(', ', $names); |
| 85 | + } |
| 86 | + |
| 87 | +There are three argument variants you can use: |
| 88 | + |
| 89 | +=========================== =========================================================================================================== |
| 90 | +Mode Value |
| 91 | +=========================== =========================================================================================================== |
| 92 | +``InputArgument::REQUIRED`` The argument is required |
| 93 | +``InputArgument::OPTIONAL`` The argument is optional and therefore can be omitted |
| 94 | +``InputArgument::IS_ARRAY`` The argument can contain an indefinite number of arguments and must be used at the end of the argument list |
| 95 | +=========================== =========================================================================================================== |
| 96 | + |
| 97 | +You can combine ``IS_ARRAY`` with ``REQUIRED`` and ``OPTIONAL`` like this:: |
| 98 | + |
| 99 | + $this |
| 100 | + // ... |
| 101 | + ->addArgument( |
| 102 | + 'names', |
| 103 | + InputArgument::IS_ARRAY | InputArgument::REQUIRED, |
| 104 | + 'Who do you want to greet (separate multiple names with a space)?' |
| 105 | + ); |
| 106 | + |
| 107 | +Using Command Options |
| 108 | +--------------------- |
| 109 | + |
| 110 | +Unlike arguments, options are not ordered (meaning you can specify them in any |
| 111 | +order) and are specified with two dashes (e.g. ``--yell`` - you can also |
| 112 | +declare a one-letter shortcut that you can call with a single dash like |
| 113 | +``-y``). Options are *always* optional, and can be setup to accept a value |
| 114 | +(e.g. ``--dir=src``) or simply as a boolean flag without a value (e.g. |
| 115 | +``--yell``). |
| 116 | + |
| 117 | +.. tip:: |
| 118 | + |
| 119 | + There is nothing forbidding you to create a command with an option that |
| 120 | + optionally accepts a value. However, there is no way you can distinguish |
| 121 | + when the option was used without a value (``command --yell``) or when it |
| 122 | + wasn't used at all (``command``). In both cases, the value retrieved for |
| 123 | + the option will be ``null``. |
| 124 | + |
| 125 | +For example, add a new option to the command that can be used to specify |
| 126 | +how many times in a row the message should be printed:: |
| 127 | + |
| 128 | + $this |
| 129 | + // ... |
| 130 | + ->addOption( |
| 131 | + 'iterations', |
| 132 | + null, |
| 133 | + InputOption::VALUE_REQUIRED, |
| 134 | + 'How many times should the message be printed?', |
| 135 | + 1 |
| 136 | + ); |
| 137 | + |
| 138 | +Next, use this in the command to print the message multiple times:: |
| 139 | + |
| 140 | + for ($i = 0; $i < $input->getOption('iterations'); $i++) { |
| 141 | + $output->writeln($text); |
| 142 | + } |
| 143 | + |
| 144 | +Now, when you run the task, you can optionally specify a ``--iterations`` |
| 145 | +flag: |
| 146 | + |
| 147 | +.. code-block:: bash |
| 148 | +
|
| 149 | + # no --iterations provided, the default (1) is used |
| 150 | + $ php app/console app:greet Fabien |
| 151 | + Hi Fabien! |
| 152 | +
|
| 153 | + $ php app/console app:greet Fabien --iterations=5 |
| 154 | + Hi Fabien |
| 155 | + Hi Fabien |
| 156 | + Hi Fabien |
| 157 | + Hi Fabien |
| 158 | + Hi Fabien |
| 159 | +
|
| 160 | + # the order of options isn't important |
| 161 | + $ php app/console app:greet Fabien --iterations=5 --yell |
| 162 | + $ php app/console app:greet Fabien --yell --iterations=5 |
| 163 | + $ php app/console app:greet --yell --iterations=5 Fabien |
| 164 | +
|
| 165 | +There are 4 option variants you can use: |
| 166 | + |
| 167 | +=============================== ===================================================================================== |
| 168 | +Option Value |
| 169 | +=============================== ===================================================================================== |
| 170 | +``InputOption::VALUE_IS_ARRAY`` This option accepts multiple values (e.g. ``--dir=/foo --dir=/bar``) |
| 171 | +``InputOption::VALUE_NONE`` Do not accept input for this option (e.g. ``--yell``) |
| 172 | +``InputOption::VALUE_REQUIRED`` This value is required (e.g. ``--iterations=5``), the option itself is still optional |
| 173 | +``InputOption::VALUE_OPTIONAL`` This option may or may not have a value (e.g. ``--yell`` or ``--yell=loud``) |
| 174 | +=============================== ===================================================================================== |
| 175 | + |
| 176 | +You can combine ``VALUE_IS_ARRAY`` with ``VALUE_REQUIRED`` or |
| 177 | +``VALUE_OPTIONAL`` like this:: |
| 178 | + |
| 179 | + $this |
| 180 | + // ... |
| 181 | + ->addOption( |
| 182 | + 'colors', |
| 183 | + null, |
| 184 | + InputOption::VALUE_REQUIRED | InputOption::VALUE_IS_ARRAY, |
| 185 | + 'Which colors do you like?', |
| 186 | + array('blue', 'red') |
| 187 | + ); |
0 commit comments