|
| 1 | +.. index:: |
| 2 | + single: Console Helpers; DebugFormatter Helper |
| 3 | + |
| 4 | +Debug Formatter Helper |
| 5 | +====================== |
| 6 | + |
| 7 | +.. versionadded:: 2.6 |
| 8 | + The Debug Formatter 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 | +and you can get it by calling |
| 14 | +:method:`Symfony\\Component\\Console\\Command\\Command::getHelper`:: |
| 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 do anything else. |
| 20 | + |
| 21 | +All methods of this helper have an identifier as the first argument. This is a |
| 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 be shown 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 | + use Symfony\Component\Process\Process; |
| 66 | + |
| 67 | + // ... |
| 68 | + $process = new Process(...); |
| 69 | + |
| 70 | + $process->run(function ($type, $buffer) use ($output, $debugFormatter, $process) { |
| 71 | + $output->writeln( |
| 72 | + $debugFormatter->progress(spl_object_hash($process), $buffer, Process::ERR === $type) |
| 73 | + ); |
| 74 | + }); |
| 75 | + // ... |
| 76 | + |
| 77 | +In case of success, this will output: |
| 78 | + |
| 79 | +.. code-block:: text |
| 80 | +
|
| 81 | + OUT The output of the process |
| 82 | +
|
| 83 | +And this in case of failure: |
| 84 | + |
| 85 | +.. code-block:: text |
| 86 | +
|
| 87 | + ERR The output of the process |
| 88 | +
|
| 89 | +The third argument is a boolean which tells the function if the output is error |
| 90 | +output or not. When ``true``, the output is considered error output. |
| 91 | + |
| 92 | +The fourth and fifth argument allow you to override the prefix for the normal |
| 93 | +output and error output respectively. |
| 94 | + |
| 95 | +Stopping a Program |
| 96 | +------------------ |
| 97 | + |
| 98 | +When a program is stopped, you can use |
| 99 | +:method:`Symfony\\Component\\Console\\Helper\\DebugFormatterHelper::run` to |
| 100 | +notify this to the users:: |
| 101 | + |
| 102 | + // ... |
| 103 | + $output->writeln( |
| 104 | + $debugFormatter->stop( |
| 105 | + spl_object_hash($process), |
| 106 | + 'Some command description', |
| 107 | + $process->isSuccessfull() |
| 108 | + ) |
| 109 | + ); |
| 110 | + |
| 111 | +This will output: |
| 112 | + |
| 113 | +.. code-block:: text |
| 114 | +
|
| 115 | + RES Some command description |
| 116 | +
|
| 117 | +In case of failure, this will be in red and in case of success it will be green. |
| 118 | + |
| 119 | +Using multiple Programs |
| 120 | +----------------------- |
| 121 | + |
| 122 | +As said before, you can also use the helper to display more programs at the |
| 123 | +same time. Information about different programs will be shown in different |
| 124 | +colors, to make it clear which output belongs to which command. |
0 commit comments