|
| 1 | +How To Manipulate Console Output |
| 2 | +================================ |
| 3 | + |
| 4 | +The console comes with a powerful class to print information to the terminal. This |
| 5 | +information can be manipulated by clearing or overwriting the displayed content. |
| 6 | + |
| 7 | +In order to manipulate the content, you need to create a new output section. An output section is |
| 8 | +a part in the terminal where information will be displayed from the console. |
| 9 | + |
| 10 | +A section can be manipulated individually, and multiple sections can be appended to the output. |
| 11 | + |
| 12 | +To create a new output section, you need to use the |
| 13 | +:method:`Symfony\\Component\\Console\\Output\\ConsoleOutput::section` method:: |
| 14 | + |
| 15 | + class MyCommand extends Command |
| 16 | + { |
| 17 | + protected function execute(InputInterface $input, OutputInterface $output) |
| 18 | + { |
| 19 | + $section = $output->section(); |
| 20 | + } |
| 21 | + } |
| 22 | + |
| 23 | +This will return an instance of the :class:`Symfony\\Component\\Console\\Output\\ConsoleSectionOutput` |
| 24 | + |
| 25 | +.. tip:: |
| 26 | + |
| 27 | + You can create multiple sections by calling the |
| 28 | + :method:`Symfony\\Component\\Console\\Output\\ConsoleOutput::section` method multiple times. |
| 29 | + This will append a new section after the previous one. |
| 30 | + |
| 31 | +.. caution:: |
| 32 | + |
| 33 | + Displaying information in a section will always append a new line to the output. |
| 34 | + |
| 35 | +Overwriting Output |
| 36 | +------------------ |
| 37 | + |
| 38 | +When displaying information in the console, you can overwrite the output by using the |
| 39 | +:method:`Symfony\\Component\\Console\\Output\\ConsoleSectionOutput::overwrite` method:: |
| 40 | + |
| 41 | + $section->writeln('Hello'); |
| 42 | + $section->overwrite('World!'); |
| 43 | + |
| 44 | +The only information displayed in the terminal will be ``World!`` as the first part will |
| 45 | +be overwritten. |
| 46 | + |
| 47 | +Clearing a Section |
| 48 | +------------------ |
| 49 | + |
| 50 | +You can clear all the content in a section by using the |
| 51 | +:method:`Symfony\\Component\\Console\\Output\\ConsoleSectionOutput::clear` method. |
| 52 | + |
| 53 | +Clearing a section will erase all the content that is displayed in that section:: |
| 54 | + |
| 55 | + $section->writeln('Hello World!'); |
| 56 | + $section->clear(); |
| 57 | + |
| 58 | +This will leave your terminal clean without any output displayed. |
| 59 | + |
| 60 | +You can also clear a specific number of lines from the output instead of clearing all the |
| 61 | +output:: |
| 62 | + |
| 63 | + $section->writeln('One!'); |
| 64 | + $section->writeln('Two!'); |
| 65 | + $section->writeln('Three!'); |
| 66 | + $section->writeln('Four!'); |
| 67 | + |
| 68 | + $section->clear(2); |
| 69 | + |
| 70 | +This will only leave the lines ``One!`` and ``Two!`` displaying in the terminal. |
| 71 | + |
| 72 | +Modifying Content In Previous Sections |
| 73 | +-------------------------------------- |
| 74 | + |
| 75 | +When you append multiple sections to the terminal, you can manipulate the output of |
| 76 | +only a specific section, leaving the rest intact:: |
| 77 | + |
| 78 | + $section1 = $output->section(); |
| 79 | + $section2 = $output->section(); |
| 80 | + |
| 81 | + $section1->writeln('Hello World!'); |
| 82 | + $section2->writeln('This is comes second'); |
| 83 | + |
| 84 | + $section1->overwrite('This comes first'); |
| 85 | + |
| 86 | +This will result in the following output in the terminal: |
| 87 | + |
| 88 | +.. code-block:: text |
| 89 | +
|
| 90 | + This comes first |
| 91 | + This comes second |
| 92 | +
|
| 93 | +Displaying Multiple Progress Bars |
| 94 | +--------------------------------- |
| 95 | + |
| 96 | +You can display multiple progress bars underneath each other, and changing the progress |
| 97 | +of one of the bars at a time:: |
| 98 | + |
| 99 | + $section1 = $output->section(); |
| 100 | + $section2 = $output->section(); |
| 101 | + |
| 102 | + $progress1 = new ProgressBar($section1); |
| 103 | + $progress2 = new ProgressBar($section2); |
| 104 | + |
| 105 | + $progress1->start(100); |
| 106 | + $progress2->start(100); |
| 107 | + |
| 108 | + $c = 0; |
| 109 | + while (++$c < 100) { |
| 110 | + $progress1->advance(); |
| 111 | + |
| 112 | + if ($c % 2 === 0) { |
| 113 | + $progress2->advance(4); |
| 114 | + } |
| 115 | + |
| 116 | + usleep(500000); |
| 117 | + } |
| 118 | + |
| 119 | +After a couple of iterations, the output in the terminal will look like this: |
| 120 | + |
| 121 | +.. code-block:: text |
| 122 | +
|
| 123 | + 34/100 [=========>------------------] 34% |
| 124 | + 68/100 [===================>--------] 68% |
| 125 | +
|
| 126 | +Appending Rows To a Table |
| 127 | +------------------------- |
| 128 | + |
| 129 | +If you are displaying a table in the terminal, you can append rows to an already rendered table |
| 130 | +by using the :method:`Symfony\\Component\\Console\\Helper\\Table::appendRow` method. |
| 131 | + |
| 132 | +This method takes the same arguments as the :method:`Symfony\\Component\\Console\\Helper\\Table::addRow` |
| 133 | +method, but if the table is already rendered, then it will append the row to the table. |
| 134 | + |
| 135 | + $section = $output->section(); |
| 136 | + $table = new Table($section); |
| 137 | + |
| 138 | + $table->addRow(['Row 1']); |
| 139 | + $table->render(); |
| 140 | + |
| 141 | + $table->addRow(['Row 2']); |
| 142 | + |
| 143 | +This will display the following table in the terminal: |
| 144 | + |
| 145 | +.. code-block:: text |
| 146 | +
|
| 147 | + +-------+ |
| 148 | + | Row 1 | |
| 149 | + | Row 2 | |
| 150 | + +-------+ |
0 commit comments