Merge remote-tracking branch 'upstream/5.2' into 5.2

* upstream/5.2:
  [#15270] Minor fixes
  [Console] Document console cursor

Author: javiereguiluz

.doctor-rst.yaml

@@ -103,3 +103,4 @@ whitelist:
         - '.. code-block:: twig'
         - '.. versionadded:: 3.6' # MonologBundle
         - 'End to End Tests (E2E)'
+        - '.. code-block:: php'

_images/components/console/cursor.gif

@@ -0,0 +1,104 @@
+.. index::
+    single: Console Helpers; Cursor Helper
+
+Cursor Helper
+=============
+
+.. versionadded:: 5.1
+
+    The :class:`Symfony\\Component\\Console\\Cursor` class was introduced
+    in Symfony 5.1.
+
+The :class:`Symfony\\Component\\Console\\Cursor` allows you to change the
+cursor position in a console command. This allows you to write on any position
+of the output:
+
+.. image:: /_images/components/console/cursor.gif
+   :align: center
+
+.. code-block:: php
+
+    // src/Command/MyCommand.php
+    namespace App\Command;
+
+    use Symfony\Component\Console\Command\Command;
+    use Symfony\Component\Console\Cursor;
+    use Symfony\Component\Console\Input\InputInterface;
+    use Symfony\Component\Console\Output\OutputInterface;
+
+    class MyCommand extends Command
+    {
+        // ...
+
+        public function execute(InputInterface $input, OutputInterface $output): int
+        {
+            // ...
+
+            $cursor = new Cursor($output);
+
+            // moves the cursor to a specific column (1st argument) and
+            // row (2nd argument) position
+            $cursor->moveToPosition(7, 11);
+
+            // and write text on this position using the output
+            $output->write('My text');
+
+            // ...
+        }
+    }
+
+Using the cursor
+----------------
+
+Moving the cursor
+.................
+
+There are fews methods to control moving the command cursor::
+
+    // moves the cursor 1 line up from its current position
+    $cursor->moveUp();
+
+    // moves the cursor 3 lines up from its current position
+    $cursor->moveUp(3);
+
+    // same for down
+    $cursor->moveDown();
+
+    // moves the cursor 1 column right from its current position
+    $cursor->moveRight();
+
+    // moves the cursor 3 columns right from its current position
+    $cursor->moveRight(3);
+
+    // same for left
+    $cursor->moveLeft();
+
+    // move the cursor to a specific (column, row) position from the
+    // top-left position of the terminal
+    $cursor->moveToPosition(7, 11);
+
+You can get the current command's cursor position by using::
+
+    $position = $cursor->getCurrentPosition();
+    // $position[0] // columns (aka x coordinate)
+    // $position[1] // rows (aka y coordinate)
+
+Clearing output
+...............
+
+The cursor can also clear some output on the screen::
+
+    // clears all the output from the current line
+    $cursor->clearLine();
+
+    // clears all the output from the current line after the current position
+    $cursor->clearLineAfter();
+
+    // clears all the output from the cursors' current position to the end of the screen
+    $cursor->clearOutput();
+
+    // clears the entire screen
+    $cursor->clearScreen();
+
+You also can leverage the :method:`Symfony\\Component\\Console\\Cursor::show`
+and :method:`Symfony\\Component\\Console\\Cursor::hide` methods on the cursor.

components/console/helpers/cursor.rst

@@ -13,6 +13,7 @@ The Console Helpers
     questionhelper
     table
     debug_formatter
+    cursor
 
 The Console component comes with some useful helpers. These helpers contain
 functions to ease some common tasks.

components/console/helpers/index.rst

@@ -4,3 +4,4 @@
 * :doc:`/components/console/helpers/questionhelper`
 * :doc:`/components/console/helpers/table`
 * :doc:`/components/console/helpers/debug_formatter`
+* :doc:`/components/console/helpers/cursor`

components/console/helpers/map.rst.inc

@@ -349,7 +349,7 @@ placeholder before displaying the progress bar::
     // 0/100 -- Start
 
     $progressBar->setMessage('Task is in progress...');
-    $progressBar->advance();    
+    $progressBar->advance();
     // 1/100 -- Task is in progress...
 
 Messages can be combined with custom placeholders too. In this example, the

components/console/helpers/progressbar.rst

@@ -446,5 +446,6 @@ tools capable of helping you with different tasks:
 * :doc:`/components/console/helpers/table`: displays tabular data as a table
 * :doc:`/components/console/helpers/debug_formatter`: provides functions to
   output debug information when running an external program
+* :doc:`/components/console/helpers/cursor`: allows to manipulate the cursor in the terminal
 
 .. _`exit status`: https://en.wikipedia.org/wiki/Exit_status