feature #3756 [WCM][Console] Add Process Helper documentation (romain…

…neutron)

This PR was merged into the master branch.

Discussion
----------

[WCM][Console] Add Process Helper documentation

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | yes (symfony/symfony#10627)
| Applies to    | 2.5+
| Fixed tickets | n/a

Commits
-------

1705231 [Console] Add Process Helper documentation

components/console/helpers/index.rst

@@ -9,6 +9,7 @@ The Console Helpers
 
     dialoghelper
     formatterhelper
+    processhelper
     progressbar
     progresshelper
     table

components/console/helpers/map.rst.inc

@@ -1,5 +1,6 @@
 * :doc:`/components/console/helpers/dialoghelper`
 * :doc:`/components/console/helpers/formatterhelper`
+* :doc:`/components/console/helpers/processhelper`
 * :doc:`/components/console/helpers/progressbar`
 * :doc:`/components/console/helpers/progresshelper`
 * :doc:`/components/console/helpers/table`

components/console/helpers/processhelper.rst

@@ -0,0 +1,56 @@
+.. index::
+    single: Console Helpers; Process Helper
+
+Process Helper
+==============
+
+.. versionadded:: 2.5
+    The Process Helper was introduced in Symfony 2.5.
+
+The Process Helper shows processes as they're running and reports
+useful information about process status.
+
+To display process details, use the :class:`Symfony\\Component\\Console\\Helper\\ProcessHelper`
+and run your command with verbosity. For example, running the following code with
+a very verbose verbosity (e.g. -vv)::
+
+    use Symfony\Component\Process\ProcessBuilder;
+
+    $helper = $this->getHelperSet()->get('process');
+    $process = ProcessBuilder::create(array('figlet', 'Symfony'))->getProcess();
+
+    $helper->run($output, $process);
+
+will result in this output:
+
+.. image:: /images/components/console/process-helper-verbose.png
+
+It will result in more detailed output with debug verbosity (e.g. -vvv):
+
+.. image:: /images/components/console/process-helper-debug.png
+
+In case the process fails, debugging is easier:
+
+.. image:: /images/components/console/process-helper-error-debug.png
+
+There are three ways to use the process helper: using a command line string, an array
+of arguments that would be escaped or a :class:`Symfony\\Component\\Process\\Process`
+object.
+
+You can display a customized error message using the third argument of the
+:method:`Symfony\\Component\\Console\\Helper\\ProcessHelper::run` method::
+
+    $helper->run($output, $process, 'The process failed :(');
+
+A custom process callback can be passed as fourth argument, refer to the
+:doc:`Process Component </components/process>` for callback documentation::
+
+    use Symfony\Component\Process\Process;
+
+    $helper->run($output, $process, 'The process failed :(', function ($type, $data) {
+        if (Process::ERR === $type) {
+            // do something with the stderr output
+        } else {
+            // do something with the stdout
+        }
+    });