|
| 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 | + |
| 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. |
0 commit comments