Skip to content

Commit bd9cd26

Browse files
fabpotfabpot
committed
added docs for the new Table console helper
1 parent cadca3b commit bd9cd26

File tree

4 files changed

+153
-0
lines changed

4 files changed

+153
-0
lines changed

‎components/console/helpers/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ The Console Helpers
1010
dialoghelper
1111
formatterhelper
1212
progresshelper
13+
table
1314
tablehelper
1415

1516
The Console component comes with some useful helpers. These helpers contain

‎components/console/helpers/map.rst.inc

+1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
* :doc:`/components/console/helpers/dialoghelper`
22
* :doc:`/components/console/helpers/formatterhelper`
33
* :doc:`/components/console/helpers/progresshelper`
4+
* :doc:`/components/console/helpers/table`
45
* :doc:`/components/console/helpers/tablehelper`

‎components/console/helpers/table.rst

+144
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
.. index::
2+
single: Console Helpers; Table
3+
4+
Table
5+
=====
6+
7+
.. versionadded:: 2.5
8+
The ``Table`` class was introduced in Symfony 2.5 as a replacement for the
9+
:doc:`Table Helper </components/console/helpers/tablehelper>`.
10+
11+
When building a console application it may be useful to display tabular data:
12+
13+
.. code-block:: text
14+
15+
+---------------+--------------------------+------------------+
16+
| ISBN | Title | Author |
17+
+---------------+--------------------------+------------------+
18+
| 99921-58-10-7 | Divine Comedy | Dante Alighieri |
19+
| 9971-5-0210-0 | A Tale of Two Cities | Charles Dickens |
20+
| 960-425-059-0 | The Lord of the Rings | J. R. R. Tolkien |
21+
| 80-902734-1-6 | And Then There Were None | Agatha Christie |
22+
+---------------+--------------------------+------------------+
23+
24+
To display a table, use :class:`Symfony\\Component\\Console\\Helper\\Table`,
25+
set the headers, set the rows and then render the table::
26+
27+
use Symfony\Component\Helper\Table;
28+
29+
$table = new Table($output);
30+
$table
31+
->setHeaders(array('ISBN', 'Title', 'Author'))
32+
->setRows(array(
33+
array('99921-58-10-7', 'Divine Comedy', 'Dante Alighieri'),
34+
array('9971-5-0210-0', 'A Tale of Two Cities', 'Charles Dickens'),
35+
array('960-425-059-0', 'The Lord of the Rings', 'J. R. R. Tolkien'),
36+
array('80-902734-1-6', 'And Then There Were None', 'Agatha Christie'),
37+
))
38+
;
39+
$table->render();
40+
41+
You can add a table separator anywhere in the output by passing an instance of
42+
:class:`Symfony\\Component\\Console\\Helper\\TableSeparator` as a row::
43+
44+
use Symfony\Component\Helper\TableSeparator;
45+
46+
$table->setRows(array(
47+
array('99921-58-10-7', 'Divine Comedy', 'Dante Alighieri'),
48+
array('9971-5-0210-0', 'A Tale of Two Cities', 'Charles Dickens'),
49+
new TableSeparator(),
50+
array('960-425-059-0', 'The Lord of the Rings', 'J. R. R. Tolkien'),
51+
array('80-902734-1-6', 'And Then There Were None', 'Agatha Christie'),
52+
));
53+
54+
.. code-block:: text
55+
56+
+---------------+--------------------------+------------------+
57+
| ISBN | Title | Author |
58+
+---------------+--------------------------+------------------+
59+
| 99921-58-10-7 | Divine Comedy | Dante Alighieri |
60+
| 9971-5-0210-0 | A Tale of Two Cities | Charles Dickens |
61+
+---------------+--------------------------+------------------+
62+
| 960-425-059-0 | The Lord of the Rings | J. R. R. Tolkien |
63+
| 80-902734-1-6 | And Then There Were None | Agatha Christie |
64+
+---------------+--------------------------+------------------+
65+
66+
The table style can be changed to any built-in styles via
67+
:method:`Symfony\\Component\\Console\\Helper\\Table::setStyle`::
68+
69+
// same as calling nothing
70+
$table->setStyle('default');
71+
72+
// changes the default style to compact
73+
$table->setStyle('compact');
74+
$table->render();
75+
76+
This code results in:
77+
78+
.. code-block:: text
79+
80+
ISBN Title Author
81+
99921-58-10-7 Divine Comedy Dante Alighieri
82+
9971-5-0210-0 A Tale of Two Cities Charles Dickens
83+
960-425-059-0 The Lord of the Rings J. R. R. Tolkien
84+
80-902734-1-6 And Then There Were None Agatha Christie
85+
86+
You can also set the style to ``borderless``::
87+
88+
$table->setStyle('borderless');
89+
$table->render();
90+
91+
which outputs:
92+
93+
.. code-block:: text
94+
95+
=============== ========================== ==================
96+
ISBN Title Author
97+
=============== ========================== ==================
98+
99921-58-10-7 Divine Comedy Dante Alighieri
99+
9971-5-0210-0 A Tale of Two Cities Charles Dickens
100+
960-425-059-0 The Lord of the Rings J. R. R. Tolkien
101+
80-902734-1-6 And Then There Were None Agatha Christie
102+
=============== ========================== ==================
103+
104+
If the built-in styles do not fit your need, define your own::
105+
106+
.. code-block:: php
107+
108+
use Symfony\Component\Helper\TableStyle;
109+
110+
// by default, this is based on the default style
111+
$style = new TableStyle();
112+
113+
// customize the style
114+
$style
115+
->setHorizontalBorderChar('<fg=magenta>|</>')
116+
->setVerticalBorderChar('<fg=magenta>-</>')
117+
->setCrossingChar(' ')
118+
;
119+
120+
// use the style for this table
121+
$table->setStyle($style);
122+
123+
Here is a full list of things you can customize:
124+
125+
* :method:`Symfony\\Component\\Console\\Helper\\TableStyle::setPaddingChar`
126+
* :method:`Symfony\\Component\\Console\\Helper\\TableStyle::setHorizontalBorderChar`
127+
* :method:`Symfony\\Component\\Console\\Helper\\TableStyle::setVerticalBorderChar`
128+
* :method:`Symfony\\Component\\Console\\Helper\\TableStyle::setCrossingChar`
129+
* :method:`Symfony\\Component\\Console\\Helper\\TableStyle::setCellHeaderFormat`
130+
* :method:`Symfony\\Component\\Console\\Helper\\TableStyle::setCellRowFormat`
131+
* :method:`Symfony\\Component\\Console\\Helper\\TableStyle::setBorderFormat`
132+
* :method:`Symfony\\Component\\Console\\Helper\\TableStyle::setPadType`
133+
134+
.. tip::
135+
136+
You can also register a style globally::
137+
138+
// register the style under the colorful name
139+
Table::setStyleDefinition('colorful', $style);
140+
141+
// use it for a table
142+
$table->setStyle('colorful');
143+
144+
This method can also be used to override a built-in style.

‎components/console/helpers/tablehelper.rst

+7
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,13 @@ Table Helper
77
.. versionadded:: 2.3
88
The ``table`` helper was added in Symfony 2.3.
99

10+
.. caution::
11+
12+
The Table Helper was deprecated in Symfony 2.5 and will be removed in
13+
Symfony 3.0. You should now use the
14+
:doc:`Table </components/console/helpers/table>` class instead which is
15+
more powerful.
16+
1017
When building a console application it may be useful to display tabular data:
1118

1219
.. image:: /images/components/console/table.png

0 commit comments

Comments
 (0)