A library to generate HTML tables with PHP.
Table structure:
- Named rows and columns, so they can be targeted with string keys.
- Colspan and rowspan using col groups and row groups.
- Automatically fills up empty cells, to preserve the structural integrity.
- Automatically warns on cell collisions.
Tag attributes:
- Easily add row classes.
- Easily add row striping classes (odd/even zebra striping and more).
- Easily add column classes that apply to all cells in the column.
- (more planned)
API design:
- Method chaining instead of huge arrays of doom.
- Shortcut notations for frequently used stuff.
- Return value and parameter types nicely documented, so your IDE can let you know about possible operations.
- Exceptions thrown for integrity violation.
- Composer and PSR-4.
A simple 3x3 table with the diagonal cells filled.
$table = \Donquixote\Cellbrush\Table\Table::create()
->addRowNames(['row0', 'row1', 'row2'])
->addColNames(['col0', 'col1', 'col2'])
->td('row0', 'col0', 'Diag 0')
->td('row1', 'col1', 'Diag 1')
->td('row2', 'col2', 'Diag 2')
;
$html = $table->render();| Diag 0 | ||
| Diag 1 | ||
| Diag 2 |
Too verbose? Look for "Shortcut syntax" below.
A table like above, but with added thead section.
Column names are shared between table sections, but new rows need to be defined for each section.
$table = ...
$table->thead()
->addRowName('head row')
->th('head row', 'col0', 'H0')
->th('head row', 'col1', 'H1')
->th('head row', 'col2', 'H2')
;
$html = $table->render();| H0 | H1 | H2 |
|---|---|---|
| Diag 0 | ||
| Diag 1 | ||
| Diag 2 |
By default, every addRowName() and td() or th() goes into the main tbody section.
So, the following two are equivalent:
$table->td('row0', 'col0', 'Cell contents');
$table->tbody()->td('row0', 'col0', 'Cell contents');More named tbody sections can be added like this:
$table->tbody('tb1')
->addRowName(..)
->td(..)Again, the column definitions are shared between table sections, but row definitions need to be added separately.
To let a cell span the entire width of the table, simply set the column name to ''. Likewise, set the row name to '' to span the entire height of the table section.
$table->thead()
->addRowName('head row')
->td('head row', '', 'Horizontal cell in thead.')
;
$table
->...
->td('', 'col1', 'Vertical cell')
;| Horizontal cell in thead. | ||
| # | Vertical cell | # |
| # | # | |
| # | # | |
Named column groups allow for cells with colspan. In the below example, the column name "products" specifies a colspan cell that spans all 3 products.* cells, whereas "products.a", "products.b" and "products.c" specifies specific cells without colspan.
$table->addColNames(['legend', 'products.a', 'products.b', 'products.c']);
$table->thead()
->addRowName('head')
->th('head', 'legend', 'Legend')
// The "Products" label will span 3 columns: products.a, products.b, products.c
->th('head', 'products', 'Products')
->addRowName('name')
->th('name', 'legend', 'Product name')
->th('name', 'products.a', 'Product A')
->th('name', 'products.b', 'Product B')
->th('name', 'products.c', 'Product C')
;
$table
->addRowName('width')
->th('width', 'legend', 'Width')
->td('width', 'products.a', '55 cm')
->td('width', 'products.b', '102 cm')
..
->addRowName('height')
..
->addRowName('price')
->td('price', 'products.a', '7.66 EUR')| Legend | Products | ||
|---|---|---|---|
| Product name | Product A | Product B | Product C |
| Width | 55 cm | 102 cm | 7 cm |
Similar to column groups.
$table = Table::create()
->addColNames(['legend', 'sublegend', 0, 1])
->addRowNames(['dimensions.width', 'dimensions.height', 'price'])
->th('dimensions', 'legend', 'Dimensions')
->th('dimensions.width', 'sublegend', 'Width')
->th('dimensions.height', 'sublegend', 'Height')
->th('price', 'legend', 'Price')
;
$table->headRow()->thMultiple(['Product 0', 'Product 1']);
$table->rowHandle('dimensions.width')->tdMultiple(['2cm', '5cm']);
$table->rowHandle('dimensions.height')->tdMultiple(['14g', '22g']);
$table->rowHandle('price')->tdMultiple(['7,- EUR', '5,22 EUR']);| Product 0 | Product 1 | ||
|---|---|---|---|
| Dimensions | Width | 2cm | 5cm |
| Height | 14g | 22g | |
| Price | 7,- EUR | 5,22 EUR |
$table = (new Table())
// Add columns.
->addColName('name')
->addColNames(['info.color', 'info.price'])
// Add banana row group.
->addRowNames(['banana.description', 'banana.info'])
->th('banana', 'name', 'Banana')
->td('banana.description', 'info', 'A yellow fruit.')
->td('banana.info', 'info.color', 'yellow')
->td('banana.info', 'info.price', '60 cent')
;
// Alternative syntax with handles, see "Shortcut syntax" below.
$table->addRow('coconut')->th('name', 'Coconut');
$table->addRow('coconut.description')->td('info', 'Has liquid inside.');
$table->addRow('coconut.info')
->td('info.color', 'brown')
->td('info.price', '3 dollar')
;
$table->headRow()
->th('name', 'Name')
->th('info.color', 'Color')
->th('info.price', 'Price')
;| Name | Color | Price |
|---|---|---|
| Banana | A yellow fruit. | |
| yellow | 60 cent | |
| Coconut | Has liquid inside. | |
| brown | 3 dollar | |
Groups can have unlimited depth.
$table = Table::create()
->addRowNames(['T', 'B.T', 'B.B.T', 'B.B.B'])
->addColNames(['L', 'R.L', 'R.R.L', 'R.R.R'])
->td('T', '', 'top')
->td('B', 'L', 'bottom left')
->td('B.T', 'R', 'B.T / R')
->td('B.B', 'R.L', 'B.B / R.L')
->td('B.B.T', 'R.R', 'B.B.T / R.R')
->td('B.B.B', 'R.R.L', 'B.B.B / R.R.L')
->td('B.B.B', 'R.R.R', 'B.B.B / R.R.R')
;| top | |||
| bottom left | B.T / R | ||
| B.B / R.L | B.B.T / R.R | ||
| B.B.B / R.R.L | B.B.B / R.R.R | ||
Open-end cells allow overlapping colspan cells, like bricks in a wall.
$table = (new Table())->addColNames([0, 1, 2, 3, 4, 5, 6, 7]);
$table->addRow(0)->tdMultiple([0, 1, 2, 3, 4, 5, 6, 7]);
$table->addRow(1)
->tdOpenEnd(0, '0..2')
->tdOpenEnd(3, '3..4')
->tdOpenEnd(5, '5')
->tdOpenEnd(6, '6..7')
;
$table->addRow(2)
->tdOpenEnd(0, '0..1')
->tdOpenEnd(2, '2..3')
->tdOpenEnd(4, '4..6')
->tdOpenEnd(7, '7')
;| 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
| 0..2 | 3..4 | 5 | 6..7 | ||||
| 0..1 | 2..3 | 4..6 | 7 | ||||
RowHandle and *ColHandle allow you to omit one of $rowName and $colName to address a table cell.
$table = (new Table())
->addRowNames(['row0', 'row1', 'row2'])
->addColNames(['legend', 'col0', 'col1', 'col2'])
...
;
// Add cells in a "head0" row in the thead section.
$table->headRow()
->th('col0', 'Column 0')
->th('col1', 'Column 1')
->th('col2', 'Column 2')
;
// Add cells in a "legend" column.
$table->colHandle('legend')
->th('row0', 'Row 0')
->th('row1', 'Row 1')
->th('row2', 'Row 2')
;| Column 0 | Column 1 | Column 2 | |
|---|---|---|---|
| Row 0 | Diag 0 | ||
| Row 1 | Diag 1 | ||
| Row 2 | Diag 2 |
Row classes can be added quite easily with addRowClass().
$table->addRowClass('row0', 'rowClass0');Row striping classes can be added to a table section with addRowStriping().
The default striping is ['odd', 'even'], but different patterns can be added with three or more stripes.
// Odd/even zebra striping.
$table->addRowStriping();
// 3-way striping.
$table->addRowStriping(['1of3', '2of3', '3of3']);The striping always applies to a table section. By default, this wil be the main tbody section.
You can use addColClass() to add a class to all cells of a column.
This can be done either for all table sections at once, or for specific table sections.
$table->addColClass('col0', 'allSectionsColumn0');
$table->tbody()->addColClass('col0', 'tbodyColumn0');Use addCellClass() to add classes to individual cells.
$table->addCellClass('row0', 'col0', 'my_class');Columns can be reordered even after the cells are already added.
// Create a table, and render it.
$table = Table::create()
->addRowNames(['row0', 'row1', 'row2'])
->addColNames(['col0', 'col1', 'col2'])
->td('row0', 'col0', 'Diag 0')
->td('row1', 'col1', 'Diag 1')
->td('row2', 'col2', 'Diag 2')
;
print $table->render();| Diag 0 | ||
| Diag 1 | ||
| Diag 2 |
// Reorder the columns, and render again.
$table->setColOrder(['col1', 'col2', 'col0']);
print $table->render();| Diag 0 | ||
| Diag 1 | ||
| Diag 2 |
You can see more examples in the unit tests.
Next steps:
- Collision detection.
- Dedicated exception classes.