8000 Reorganized the contents of the new output sections · symfony/symfony-docs@925499b · GitHub
[go: up one dir, main page]
Skip to content

Commit 925499b

Browse files
javiereguiluzjaviereguiluz
committed
Reorganized the contents of the new output sections
1 parent 944e534 commit 925499b

File tree

4 files changed

+142
-153
lines changed

4 files changed

+142
-153
lines changed

‎components/console/helpers/progressbar.rst

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -342,3 +342,43 @@ of the custom placeholders::
342342
$progressBar->advance();
343343
// 2/100 -- Importing invoices... (client-001/invoices.xml)
344344
}
345+
346+
.. _console-multiple-progress-bars:
347+
348+
Displaying Multiple Progress Bars
349+
---------------------------------
350+
351+
.. versionadded:: 4.1
352+
The feature to display multiple progress bars using output sections was
353+
introduced in Symfony 4.1.
354+
355+
When using :ref:`Console output sections <console-output-sections>` it's
356+
possible to display multiple progress bars at the same time and change their
357+
progress independently::
358+
359+
$section1 = $output->section();
360+
$section2 = $output->section();
361+
362+
$progress1 = new ProgressBar($section1);
363+
$progress2 = new ProgressBar($section2);
364+
365+
$progress1->start(100);
366+
$progress2->start(100);
367+
368+
$i = 0;
369+
while (++$i < 100) {
370+
$progress1->advance();
371+
372+
if ($i % 2 === 0) {
373+
$progress2->advance(4);
374+
}
375+
376+
usleep(50000);
377+
}
378+
379+
After a couple of iterations, the output in the terminal will look like this:
380+
381+
.. code-block:: text
382+
383+
34/100 [=========>------------------] 34%
384+
68/100 [===================>--------] 68%

‎components/console/helpers/table.rst

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -324,3 +324,47 @@ This outputs:
324324
325325
You can use the ``colspan`` and ``rowspan`` options at the same time which allows
326326
you to create any table layout you may wish.
327+
328+
.. _console-modify-rendered-tables:
329+
330+
Modifying Rendered Tables
331+
-------------------------
332+
333+
.. versionadded:: 4.1
334+
The feature to modify rendered tables was introduced in Symfony 4.1.
335+
336+
The ``render()`` method requires passing the entire table contents. However,
337+
sometimes that information is not available beforehand because it's generated
338+
dynamically. In those cases, use the
339+
:method:`Symfony\\Component\\Console\\Helper\\Table::appendRow` method, which
340+
takes the same arguments as the ``addRow()`` method, to add rows at the bottom
341+
of an already rendered table.
342+
343+
The only requirement to append rows is that the table must be rendered inside a
344+
:ref:`Console output section <console-output-sect 8000 ions>`::
345+
346+
use Symfony\Component\Console\Helper\Table;
347+
// ...
348+
349+
class SomeCommand extends Command
350+
{
351+
public function execute(InputInterface $input, OutputInterface $output)
352+
{
353+
$section = $output->section();
354+
$table = new Table($section);
355+
356+
$table->addRow(['Row 1']);
357+
$table->render();
358+
359+
$table->addRow(['Row 2']);
360+
}
361+
}
362+
363+
This will display the following table in the terminal:
364+
365+
.. code-block:: terminal
366+
367+
+-------+
368+
| Row 1 |
369+
| Row 2 |
370+
+-------+

‎console.rst

Lines changed: 58 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -87,9 +87,13 @@ After configuring and registering the command, you can execute it in the termina
8787
$ php bin/console app:create-user
8888
8989
As you might expect, this command will do nothing as you didn't write any logic
90-
yet. Add your own logic inside the ``execute()`` method, which has access to the
91-
input stream (e.g. options and arguments) and the output stream (to write
92-
messages to the console)::
90+
yet. Add your own logic inside the ``execute()`` method.
91+
92+
Console Output
93+
--------------
94+
95+
The ``execute()`` method has access to the output stream to write messages to
96+
the console::
9397

9498
// ...
9599
protected function execute(InputInterface $input, OutputInterface $output)
@@ -128,6 +132,57 @@ Now, try executing the command:
128132
Whoa!
129133
You are about to create a user.
130134
135+
.. _console-output-sections:
136+
137+
Output Sections
138+
~~~~~~~~~~~~~~~
139+
140+
.. versionadded:: 4.1
141+
Output sections were introduced in Symfony 4.1.
142+
143+
The regular console output can be divided into multiple independent regions
144+
called "output sections". Create one or more of these sections when you need to
145+
clear and overwrite the output information.
146+
147+
Sections are created with the
148+
:method:`Symfony\\Component\\Console\\Output\\ConsoleOutput::section` method,
149+
which returns an instance of
150+
:class:`Symfony\\Component\\Console\\Output\\ConsoleSectionOutput`::
151+
152+
class MyCommand extends Command
153+
{
154+
protected function execute(InputInterface $input, OutputInterface $output)
155+
{
156+
$section1 = $output->section();
157+
$section2 = $output->section();
158+
$section1->writeln('Hello');
159+
$section2->writeln('World!');
160+
// Output displays "Hello\nWorld!\n"
161+
162+
// overwrite() replaces all the existing section contents with the given content
163+
$section1->overwrite('Goodbye');
164+
// Output now displays "Goodbye\nWorld!\n"
165+
166+
// clear() deletes all the section contents...
167+
$section2->clear();
168+
// Output now displays "Goodbye\n"
169+
170+
// ...but you can also delete a given number of lines
171+
// (this example deletes the last two lines of the section)
172+
$section1->clear(2);
173+
// Output is now completely empty!
174+
}
175+
}
176+
177+
.. note::
178+
179+
A new line is appended automatically when displaying information in a section.
180+
181+
Output sections let you manipulate the Console output in advanced ways, such as
182+
:ref:`displaying multiple progress bars <console-multiple-progress-bars>` which
183+
are updated independently and :ref:`appending rows to tables <console-modify-rendered-tables>`
184+
that have already been rendered.
185+
131186
Console Input
132187
-------------
133188

‎console/manipulating_output.rst

Lines changed: 0 additions & 150 deletions
This file was deleted.

0 commit comments

Comments
 (0)
0