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 | - +-------+ 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