8000 Added documentation about the DebugFormatter helper · symfony/symfony-docs@363e38f · GitHub
[go: up one dir, main page]
Skip to content

Commit 363e38f

Browse files
wouterjwouterj
committed
Added documentation about the DebugFormatter helper
1 parent ad4c1f0 commit 363e38f

File tree

3 files changed

+111
-0
lines changed

3 files changed

+111
-0
lines changed

‎components/console/helpers/debug_formatter.rst

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
.. index::
2+
single: Console Helpers; DebugFormatter Helper
3+
4+
DebugFormatter Helper
5+
=====================
6+
7+
.. versionadded:: 2.6
8+
The DebugFormatter helper was introduced in Symfony 2.6.
9+
10+
The :class:`Symfony\\Component\\Console\\Helper\\DebugFormatterHelper` provides
11+
functions to output debug information when running an external program, for
12+
instance a process or HTTP request. It is included in the default helper set,
13+
which you can get by calling
14+
:method:`Symfony\\Component\\Console\\Command\\Command::getHelperSet`::
15+
16+
$debugFormatter = $this->getHelper('debug_formatter');
17+
18+
The formatter only formats strings, which you can use to output to the console,
19+
but also to log the information or anything else.
20+
21+
All methods of this helper have an identifier as the first argument. This is an
22+
unique value for each program. This way, the helper can debug information for
23+
multiple programs at the same time. When using the
24+
:doc:`Process component </components/process>`, you probably want to use
25+
:phpfunction:`spl_object_hash`.
26+
27+
.. tip::
28< 10000 /td>+
29+
This information is often too verbose to show by default. You can use
30+
:ref:`verbosity levels <verbosity-levels>` to only show it when in
31+
debugging mode (``-vvv``).
32+
33+
Starting a Program
34+
------------------
35+
36+
As soon as you start a program, you can use
37+
:method:`Symfony\\Component\\Console\\Helper\\DebugFormatterHelper::start` to
38+
display information that the program is started::
39+
40+
// ...
41+
$process = new Process(...);
42+
$process->run();
43+
44+
$output->writeln($debugFormatter->start(spl_object_hash($process), 'Some process description'));
45+
46+
This will output:
47+
48+
.. code-block:: text
49+
50+
RUN Some process description
51+
52+
You can tweak the prefix using the third argument::
53+
54+
$output->writeln($debugFormatter->start(spl_object_hash($process), 'Some process description', 'STARTED');
55+
// will output:
56+
// STARTED Some process description
57+
58+
Output Progress Information
59+
---------------------------
60+
61+
Some programs give output while they are running. This information can be shown
62+
using
63+
:method:`Symfony\\Component\\Console\\Helper\\DebugFormatterHelper::progress`::
64+
65+
// ...
66+
$output->writeln($debugFormatter->progress(spl_object_hash($process), $buffer, Process::ERR === $type));
67+
68+
In case of success, this will output:
69+
70+
.. code-block:: text
71+
72+
OUT The output of the process
73+
74+
And this in case of failure:
75+
76+
.. code-block:: text
77+
78+
ERR The output of the process
79+
80+
The third argument is a boolean which tells the function if the output is error
81+
output or not. When ``true``, the output is considered error output.
82+
83+
The fourth and fifth argument allow you to override the prefix for respectively
84+
the normal output and error output.
85+
86+
Stopping a Program
87+
------------------
88+
89+
When a program is stopped, you can use
90+
:method:`Symfony\\Component\\Console\\Helper\\DebugFormatterHelper::progress`
91+
to notify this to the users::
92+
93+
// ...
94+
$output->writeln($debugFormatter->progress(spl_object_hash($process), 'Some command description', $process->isSuccesfull()));
95+
96+
This will output:
97+
98+
.. code-block:: text
99+
100+
RES Some command description
101+
102+
In case of failure, this will be in red and in case of success it will be green.
103+
104+
Using multiple Programs
105+
-----------------------
106+
107+
As said before, you can also use the helper to display more programs at the
108+
same time. Information about different programs will be shown in different
109+
colors, to make it clear which output belongs to which command.

‎components/console/helpers/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ The Console Helpers
77
.. toctree::
88
:hidden:
99

10+
debug_formatter
1011
dialoghelper
1112
formatterhelper
1213
processhelper

‎components/console/helpers/map.rst.inc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
* :doc:`/components/console/helpers/debug_formatter` (new in 2.6)
12
* :doc:`/components/console/helpers/dialoghelper`
23
* :doc:`/components/console/helpers/formatterhelper`
34
* :doc:`/components/console/helpers/processhelper`

0 commit comments

Comments
 (0)
0