diff --git a/components/console/helpers/progressbar.rst b/components/console/helpers/progressbar.rst index 5b3cdec56bd..e9a6457eef8 100644 --- a/components/console/helpers/progressbar.rst +++ b/components/console/helpers/progressbar.rst @@ -342,3 +342,43 @@ of the custom placeholders:: $progressBar->advance(); // 2/100 -- Importing invoices... (client-001/invoices.xml) } + +.. _console-multiple-progress-bars: + +Displaying Multiple Progress Bars +--------------------------------- + +.. versionadded:: 4.1 + The feature to display multiple progress bars using output sections was + introduced in Symfony 4.1. + +When using :ref:`Console output sections ` it's +possible to display multiple progress bars at the same time and change their +progress independently:: + + $section1 = $output->section(); + $section2 = $output->section(); + + $progress1 = new ProgressBar($section1); + $progress2 = new ProgressBar($section2); + + $progress1->start(100); + $progress2->start(100); + + $i = 0; + while (++$i < 100) { + $progress1->advance(); + + if ($i % 2 === 0) { + $progress2->advance(4); + } + + usleep(50000); + } + +After a couple of iterations, the output in the terminal will look like this: + +.. code-block:: text + + 34/100 [=========>------------------] 34% + 68/100 [===================>--------] 68% diff --git a/components/console/helpers/table.rst b/components/console/helpers/table.rst index 3129e8eb2d9..fc4bc97a41f 100644 --- a/components/console/helpers/table.rst +++ b/components/console/helpers/table.rst @@ -324,3 +324,47 @@ This outputs: You can use the ``colspan`` and ``rowspan`` options at the same time which allows you to create any table layout you may wish. + +.. _console-modify-rendered-tables: + +Modifying Rendered Tables +------------------------- + +.. versionadded:: 4.1 + The feature to modify rendered tables was introduced in Symfony 4.1. + +The ``render()`` method requires passing the entire table contents. However, +sometimes that information is not available beforehand because it's generated +dynamically. In those cases, use the +:method:`Symfony\\Component\\Console\\Helper\\Table::appendRow` method, which +takes the same arguments as the ``addRow()`` method, to add rows at the bottom +of an already rendered table. + +The only requirement to append rows is that the table must be rendered inside a +:ref:`Console output section `:: + + use Symfony\Component\Console\Helper\Table; + // ... + + class SomeCommand extends Command + { + public function execute(InputInterface $input, OutputInterface $output) + { + $section = $output->section(); + $table = new Table($section); + + $table->addRow(['Row 1']); + $table->render(); + + $table->addRow(['Row 2']); + } + } + +This will display the following table in the terminal: + +.. code-block:: terminal + + +-------+ + | Row 1 | + | Row 2 | + +-------+ diff --git a/console.rst b/console.rst index ae0499f2ff8..7b7fc4dc79c 100644 --- a/console.rst +++ b/console.rst @@ -87,9 +87,13 @@ After configuring and registering the command, you can execute it in the termina $ php bin/console app:create-user As you might expect, this command will do nothing as you didn't write any logic -yet. Add your own logic inside the ``execute()`` method, which has access to the -input stream (e.g. options and arguments) and the output stream (to write -messages to the console):: +yet. Add your own logic inside the ``execute()`` method. + +Console Output +-------------- + +The ``execute()`` method has access to the output stream to write messages to +the console:: // ... protected function execute(InputInterface $input, OutputInterface $output) @@ -128,6 +132,57 @@ Now, try executing the command: Whoa! You are about to create a user. +.. _console-output-sections: + +Output Sections +~~~~~~~~~~~~~~~ + +.. versionadded:: 4.1 + Output sections were introduced in Symfony 4.1. + +The regular console output can be divided into multiple independent regions +called "output sections". Create one or more of these sections when you need to +clear and overwrite the output information. + +Sections are created with the +:method:`Symfony\\Component\\Console\\Output\\ConsoleOutput::section` method, +which returns an instance of +:class:`Symfony\\Component\\Console\\Output\\ConsoleSectionOutput`:: + + class MyCommand extends Command + { + protected function execute(InputInterface $input, OutputInterface $output) + { + $section1 = $output->section(); + $section2 = $output->section(); + $section1->writeln('Hello'); + $section2->writeln('World!'); + // Output displays "Hello\nWorld!\n" + + // overwrite() replaces all the existing section contents with the given content + $section1->overwrite('Goodbye'); + // Output now displays "Goodbye\nWorld!\n" + + // clear() deletes all the section contents... + $section2->clear(); + // Output now displays "Goodbye\n" + + // ...but you can also delete a given number of lines + // (this example deletes the last two lines of the section) + $section1->clear(2); + // Output is now completely empty! + } + } + +.. note:: + + A new line is appended automatically when displaying information in a section. + +Output sections let you manipulate the Console output in advanced ways, such as +:ref:`displaying multiple progress bars ` which +are updated independently and :ref:`appending rows to tables ` +that have already been rendered. + Console Input ------------- diff --git a/console/manipulating_output.rst b/console/manipulating_output.rst deleted file mode 100644 index 3c361c5ef69..00000000000 --- a/console/manipulating_output.rst +++ /dev/null @@ -1,150 +0,0 @@ -How To Manipulate Console Output -================================ - -The console comes with a powerful class to print information to the terminal. This -information can be manipulated by clearing or overwriting the displayed content. - -In order to manipulate the content, you need to create a new output section. An output section is -a part in the terminal where information will be displayed from the console. - -A section can be manipulated individually, and multiple sections can be appended to the output. - -To create a new output section, you need to use the -:method:`Symfony\\Component\\Console\\Output\\ConsoleOutput::section` method:: - - class MyCommand extends Command - { - protected function execute(InputInterface $input, OutputInterface $output) - { - $section = $output->section(); - } - } - -This will return an instance of the :class:`Symfony\\Component\\Console\\Output\\ConsoleSectionOutput` - -.. tip:: - - You can create multiple sections by calling the - :method:`Symfony\\Component\\Console\\Output\\ConsoleOutput::section` method multiple times. - This will append a new section after the previous one. - -.. caution:: - - Displaying information in a section will always append a new line to the output. - -Overwriting Output ------------------- - -When displaying information in the console, you can overwrite the output by using the -:method:`Symfony\\Component\\Console\\Output\\ConsoleSectionOutput::overwrite` method:: - - $section->writeln('Hello'); - $section->overwrite('World!'); - -The only information displayed in the terminal will be ``World!`` as the first part will -be overwritten. - -Clearing a Section ------------------- - -You can clear all the content in a section by using the -:method:`Symfony\\Component\\Console\\Output\\ConsoleSectionOutput::clear` method. - -Clearing a section will erase all the content that is displayed in that section:: - - $section->writeln('Hello World!'); - $section->clear(); - -This will leave your terminal clean without any output displayed. - -You can also clear a specific number of lines from the output instead of clearing all the -output:: - - $section->writeln('One!'); - $section->writeln('Two!'); - $section->writeln('Three!'); - $section->writeln('Four!'); - - $section->clear(2); - -This will only leave the lines ``One!`` and ``Two!`` displaying in the terminal. - -Modifying Content In Previous Sections --------------------------------------- - -When you append multiple sections to the terminal, you can manipulate the output of -only a specific section, leaving the rest intact:: - - $section1 = $output->section(); - $section2 = $output->section(); - - $section1->writeln('Hello World!'); - $section2->writeln('This is comes second'); - - $section1->overwrite('This comes first'); - -This will result in the following output in the terminal: - -.. code-block:: text - - This comes first - This comes second - -Displaying Multiple Progress Bars ---------------------------------- - -You can display multiple progress bars underneath each other, and changing the progress -of one of the bars at a time:: - - $section1 = $output->section(); - $section2 = $output->section(); - - $progress1 = new ProgressBar($section1); - $progress2 = new ProgressBar($section2); - - $progress1->start(100); - $progress2->start(100); - - $c = 0; - while (++$c < 100) { - $progress1->advance(); - - if ($c % 2 === 0) { - $progress2->advance(4); - } - - usleep(500000); - } - -After a couple of iterations, the output in the terminal will look like this: - -.. code-block:: text - - 34/100 [=========>------------------] 34% - 68/100 [===================>--------] 68% - -Appending Rows To a Table -------------------------- - -If you are displaying a table in the terminal, you can append rows to an already rendered table -by using the :method:`Symfony\\Component\\Console\\Helper\\Table::appendRow` method. - -This method takes the same arguments as the :method:`Symfony\\Component\\Console\\Helper\\Table::addRow` -method, but if the table is already rendered, then it will append the row to the table. - - $section = $output->section(); - $table = new Table($section); - - $table->addRow(['Row 1']); - $table->render(); - - $table->addRow(['Row 2']); - -This will display the following table in the terminal: - -.. code-block:: text - - +-------+ - | Row 1 | - | Row 2 | - +-------+