diff --git a/components/console/helpers/debug_formatter.rst b/components/console/helpers/debug_formatter.rst new file mode 100644 index 00000000000..6368686b78d --- /dev/null +++ b/components/console/helpers/debug_formatter.rst @@ -0,0 +1,124 @@ +.. index:: + single: Console Helpers; DebugFormatter Helper + +Debug Formatter Helper +====================== + +.. versionadded:: 2.6 + The Debug Formatter helper was introduced in Symfony 2.6. + +The :class:`Symfony\\Component\\Console\\Helper\\DebugFormatterHelper` provides +functions to output debug information when running an external program, for +instance a process or HTTP request. It is included in the default helper set +and you can get it by calling +:method:`Symfony\\Component\\Console\\Command\\Command::getHelper`:: + + $debugFormatter = $this->getHelper('debug_formatter'); + +The formatter only formats strings, which you can use to output to the console, +but also to log the information or do anything else. + +All methods of this helper have an identifier as the first argument. This is a +unique value for each program. This way, the helper can debug information for +multiple programs at the same time. When using the +:doc:`Process component `, you probably want to use +:phpfunction:`spl_object_hash`. + +.. tip:: + + This information is often too verbose to be shown by default. You can use + :ref:`verbosity levels ` to only show it when in + debugging mode (``-vvv``). + +Starting a Program +------------------ + +As soon as you start a program, you can use +:method:`Symfony\\Component\\Console\\Helper\\DebugFormatterHelper::start` to +display information that the program is started:: + + // ... + $process = new Process(...); + $process->run(); + + $output->writeln($debugFormatter->start(spl_object_hash($process), 'Some process description')); + +This will output: + +.. code-block:: text + + RUN Some process description + +You can tweak the prefix using the third argument:: + + $output->writeln($debugFormatter->start(spl_object_hash($process), 'Some process description', 'STARTED'); + // will output: + // STARTED Some process description + +Output Progress Information +--------------------------- + +Some programs give output while they are running. This information can be shown +using +:method:`Symfony\\Component\\Console\\Helper\\DebugFormatterHelper::progress`:: + + use Symfony\Component\Process\Process; + + // ... + $process = new Process(...); + + $process->run(function ($type, $buffer) use ($output, $debugFormatter, $process) { + $output->writeln( + $debugFormatter->progress(spl_object_hash($process), $buffer, Process::ERR === $type) + ); + }); + // ... + +In case of success, this will output: + +.. code-block:: text + + OUT The output of the process + +And this in case of failure: + +.. code-block:: text + + ERR The output of the process + +The third argument is a boolean which tells the function if the output is error +output or not. When ``true``, the output is considered error output. + +The fourth and fifth argument allow you to override the prefix for the normal +output and error output respectively. + +Stopping a Program +------------------ + +When a program is stopped, you can use +:method:`Symfony\\Component\\Console\\Helper\\DebugFormatterHelper::run` to +notify this to the users:: + + // ... + $output->writeln( + $debugFormatter->stop( + spl_object_hash($process), + 'Some command description', + $process->isSuccessfull() + ) + ); + +This will output: + +.. code-block:: text + + RES Some command description + +In case of failure, this will be in red and in case of success it will be green. + +Using multiple Programs +----------------------- + +As said before, you can also use the helper to display more programs at the +same time. Information about different programs will be shown in different +colors, to make it clear which output belongs to which command. diff --git a/components/console/helpers/index.rst b/components/console/helpers/index.rst index 909671fb08c..96034459478 100644 --- a/components/console/helpers/index.rst +++ b/components/console/helpers/index.rst @@ -7,6 +7,7 @@ The Console Helpers .. toctree:: :hidden: + debug_formatter dialoghelper formatterhelper processhelper diff --git a/components/console/helpers/map.rst.inc b/components/console/helpers/map.rst.inc index 15e6e9f8da9..f1794ef3d5e 100644 --- a/components/console/helpers/map.rst.inc +++ b/components/console/helpers/map.rst.inc @@ -6,3 +6,4 @@ * :doc:`/components/console/helpers/questionhelper` * :doc:`/components/console/helpers/table` * :doc:`/components/console/helpers/tablehelper` +* :doc:`/components/console/helpers/debug_formatter` (new in 2.6) pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy