Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commitbe5a15d

Browse files
committed
Document console completion
1 parent0718196 commitbe5a15d

File tree

4 files changed

+202
-33
lines changed

4 files changed

+202
-33
lines changed
150 KB
Loading

‎console.rst‎

Lines changed: 109 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -9,15 +9,90 @@ The Symfony framework provides lots of commands through the ``bin/console`` scri
99
created with the:doc:`Console component</components/console>`. You can also
1010
use it to create your own commands.
1111

12-
The Console: APP_ENV & APP_DEBUG
13-
---------------------------------
12+
Running Commands
13+
----------------
14+
15+
Each Symfony application comes with a large set of commands. You can use
16+
the ``list`` command to view all available commands in the application:
17+
18+
..code-block::terminal
19+
20+
$ php bin/console list
21+
...
22+
23+
Available commands:
24+
about Display information about the current project
25+
completion Dump the shell completion script
26+
help Display help for a command
27+
list List commands
28+
assets
29+
assets:install Install bundle's web assets under a public directory
30+
cache
31+
cache:clear Clear the cache
32+
...
33+
34+
If you find the command you need, you can run it with the ``--help`` option
35+
to view the command's documentation:
36+
37+
..code-block::terminal
38+
39+
$ php bin/console assets:install --help
40+
41+
APP_ENV & APP_DEBUG
42+
~~~~~~~~~~~~~~~~~~~
1443

1544
Console commands run in the:ref:`environment<config-dot-env>` defined in the ``APP_ENV``
1645
variable of the ``.env`` file, which is ``dev`` by default. It also reads the ``APP_DEBUG``
1746
value to turn "debug" mode on or off (it defaults to ``1``, which is on).
1847

1948
To run the command in another environment or debug mode, edit the value of ``APP_ENV``
20-
and ``APP_DEBUG``.
49+
and ``APP_DEBUG``. You can also define this env vars when running the
50+
command, for instance:
51+
52+
..code-block::terminal
53+
54+
# clears the cache for the prod environment
55+
$ APP_ENV=prod bin/console cache:clear
56+
57+
.. _console-completion-setup:
58+
59+
Console Completion
60+
~~~~~~~~~~~~~~~~~~
61+
62+
..versionadded::5.4
63+
64+
Console completion for Bash was introduced in Symfony 5.4.
65+
66+
If you are using the Bash shell, you can install Symfony's completion
67+
script to get auto completion when typing commands in the terminal. All
68+
commands support name and option completion, and some can even complete
69+
values.
70+
71+
..image::/_images/components/console/completion.gif
72+
73+
First, make sure you installed and setup the "bash completion" package for
74+
your OS (typically named ``bash-completion``). Then, install the Symfony
75+
completion bash script *once* by running the ``completion`` command in a
76+
Symfony app installed on your computer:
77+
78+
..code-block::terminal
79+
80+
$ php bin/console completion bash | sudo tee /etc/bash_completion.d/console-events-terminate
81+
# after the installation, restart the shell
82+
83+
Now you are all set to use the auto completion for all Symfony Console
84+
applications on your computer. By default, you can get a list of complete
85+
options by pressing the Tab key.
86+
87+
..tip::
88+
89+
Many PHP tools are build using the Symfony Console component (e.g.
90+
Composer, PHPstan and Behat). If they are using version 5.4 or higher,
91+
you can also install their completion script to enable console completion:
92+
93+
..code-block::terminal
94+
95+
$ php vendor/bin/phpstan completion bash | sudo tee /etc/bash_completion.d/phpstan
2196
2297
Creating a Command
2398
------------------
@@ -38,11 +113,6 @@ want a command to create a user::
38113
// the name of the command (the part after "bin/console")
39114
protected static $defaultName = 'app:create-user';
40115

41-
protected function configure(): void
42-
{
43-
// ...
44-
}
45-
46116
protected function execute(InputInterface $input, OutputInterface $output): int
47117
{
48118
// ... put here the code to create the user
@@ -74,37 +144,41 @@ want a command to create a user::
74144
The ``Command::INVALID`` constant was introduced in Symfony 5.3
75145

76146
Configuring the Command
77-
-----------------------
147+
~~~~~~~~~~~~~~~~~~~~~~~
78148

79149
You can optionally define a description, help message and the
80-
:doc:`input options and arguments</console/input>`::
150+
:doc:`input options and arguments</console/input>` by overriding the
151+
``configure()`` method::
81152

82-
// ...
83-
// the command description shown when running "php bin/console list"
84-
protected static $defaultDescription = 'Creates a new user.';
153+
// src/Command/CreateUserCommand.php
85154

86155
// ...
87-
protected function configure(): void
156+
class CreateUserCommand extends Command
88157
{
89-
$this
90-
// If you don't like using the $defaultDescription static property,
91-
// you can also define the short description using this method:
92-
// ->setDescription('...')
158+
// the command description shown when running "php bin/console list"
159+
protected static $defaultDescription = 'Creates a new user.';
93160

94-
// the command help shown when running the command with the "--help" option
95-
->setHelp('This command allows you to create a user...')
96-
;
161+
// ...
162+
protected function configure(): void
163+
{
164+
$this
165+
// the command help shown when running the command with the "--help" option
166+
->setHelp('This command allows you to create a user...')
167+
;
168+
}
97169
}
98170

99-
Defining the ``$defaultDescription`` static property instead of using the
100-
``setDescription()`` method allows to get the command description without
101-
instantiating its class. This makes the ``php bin/console list`` command run
102-
much faster.
171+
..tip::
172+
173+
Defining the ``$defaultDescription`` static property instead of using the
174+
``setDescription()`` method allows to get the command description without
175+
instantiating its class. This makes the ``php bin/console list`` command run
176+
much faster.
103177

104-
If you want to always run the ``list`` command fast, add the ``--short`` option
105-
to it (``php bin/console list --short``). This will avoid instantiating command
106-
classes, but it won't show any description for commands that use the
107-
``setDescription()`` method instead of the static property.
178+
If you want to always run the ``list`` command fast, add the ``--short`` option
179+
to it (``php bin/console list --short``). This will avoid instantiating command
180+
classes, but it won't show any description for commands that use the
181+
``setDescription()`` method instead of the static property.
108182

109183
..versionadded::5.3
110184

@@ -144,7 +218,7 @@ available in the ``configure()`` method::
144218
}
145219

146220
Registering the Command
147-
-----------------------
221+
~~~~~~~~~~~~~~~~~~~~~~~
148222

149223
In PHP 8 and newer versions, you can register the command by adding the
150224
``AsCommand`` attribute to it::
@@ -155,6 +229,8 @@ In PHP 8 and newer versions, you can register the command by adding the
155229
use Symfony\Component\Console\Attribute\AsCommand;
156230
use Symfony\Component\Console\Command\Command;
157231

232+
// the "name" and "description" arguments of AsCommand replace the
233+
// static $defaultName and $defaultDescription properties
158234
#[AsCommand(
159235
name: 'app:create-user',
160236
description: 'Creates a new user.',
@@ -176,8 +252,8 @@ If you can't use PHP attributes, register the command as a service and
176252
:ref:`default services.yaml configuration<service-container-services-load-example>`,
177253
this is already done for you, thanks to:ref:`autoconfiguration<services-autoconfigure>`.
178254

179-
Executing the Command
180-
---------------------
255+
Running the Command
256+
~~~~~~~~~~~~~~~~~~~
181257

182258
After configuring and registering the command, you can run it in the terminal:
183259

@@ -468,7 +544,7 @@ call ``setAutoExit(false)`` on it to get the command result in ``CommandTester``
468544

469545
$application = new Application();
470546
$application->setAutoExit(false);
471-
547+
472548
$tester = new ApplicationTester($application);
473549

474550
..note::

‎console/input.rst‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -308,4 +308,90 @@ The above code can be simplified as follows because ``false !== null``::
308308
$yell = ($optionValue !== false);
309309
$yellLouder = ($optionValue === 'louder');
310310

311+
Adding Argument/Option Value Completion
312+
---------------------------------------
313+
314+
..versionadded::5.4
315+
316+
Console completion was introduced in Symfony 5.4.
317+
318+
If:ref:`Console completion is installed<console-completion-setup>`,
319+
command and option names will be auto completed by the shell. However, you
320+
can also implement value completion for the input in your commands. For
321+
instance, you may want to complete all usernames from the database in the
322+
``name`` argument of your greet command.
323+
324+
To achieve this, override the ``complete()`` method in the command::
325+
326+
// ...
327+
use Symfony\Component\Console\Completion\CompletionInput;
328+
use Symfony\Component\Console\Completion\CompletionSuggestions;
329+
330+
class GreetCommand extends Command
331+
{
332+
// ...
333+
334+
public function complete(CompletionInput $input, CompletionSuggestions $suggestions): void
335+
{
336+
if ($input->mustSuggestArgumentValuesFor('names')) {
337+
// the user asks for completion input for the "names" option
338+
339+
// the value the user already typed, e.g. when typing "app:greet Fa" before
340+
// pressing Tab, this will contain "Fa"
341+
$currentValue = $input->getCompletionValue();
342+
343+
// get the list of username names from somewhere (e.g. the database)
344+
// you may use $currentValue to filter down the names
345+
$availableUsernames = ...;
346+
347+
// then add the retrieved names as suggested values
348+
$suggestions->suggestValues($availableUsernames);
349+
}
350+
}
351+
}
352+
353+
That's all you need! Assuming users "Fabien" and "Fabrice" exist, pressing
354+
tab after typing ``app:greet Fa`` will give you these names as a suggestion.
355+
356+
..tip::
357+
358+
The bash script will automatically filter the suggested values based on
359+
the existing input from the user. You do not have to implement any
360+
filter logic in the command.
361+
362+
You may use ``CompletionInput::getCompletionValue()`` to get the
363+
current input if that helps improving performance (e.g. by reducing the
364+
number of rows fetched from the database).
365+
366+
Testing the Completion script
367+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
368+
369+
The Console component comes with a special
370+
:class:`Symfony\\Component\\Console\\Test\\CommandCompletionTester`` class
371+
to help you unit test the completion logic::
372+
373+
// ...
374+
use Symfony\Component\Console\Application;
375+
376+
class GreetCommandTest extends TestCase
377+
{
378+
public function testComplete()
379+
{
380+
$application = new Application();
381+
$application->add(new GreetCommand());
382+
383+
// create a new tester with the greet command
384+
$tester = new CommandCompletionTester($application->get('app:greet'));
385+
386+
// complete the input without any existing input (the empty string represents
387+
// the position of the cursor)
388+
$suggestions = $tester->complete(['']);
389+
$this->assertSame(['Fabien', 'Fabrice', 'Wouter'], $suggestions);
390+
391+
// complete the input with "Fa" as input
392+
$suggestions = $tester->complete(['Fa']);
393+
$this->assertSame(['Fabien', 'Fabrice'], $suggestions);
394+
}
395+
}
396+
311397
.. _`docopt standard`:http://docopt.org/

‎page_creation.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -195,6 +195,13 @@ the debugging routes in the next section.
195195

196196
You'll learn about many more commands as you continue!
197197

198+
..tip::
199+
200+
If you are using the Bash shell, you can set-up completion support.
201+
This autocompletes commands and other input when using ``bin/console``.
202+
See:ref:`the Console document<console-completion-setup>` for more
203+
information on how to set-up completion.
204+
198205
.. _web-debug-toolbar:
199206

200207
The Web Debug Toolbar: Debugging Dream

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp