Manual

Console_Table provides methods to display tabular data in an ASCII terminal/shell.

Introduction to Console_Table

Console_Table helps you to display tabular data on a terminal/shell/console. It provides features similar to those of HTML tables: Header and body (data) parts, alignment of columns, cell padding, multi line cells, border "styles" and column filters.

The class be filled with data by adding rows, adding cols or even importing whole arrays.

When adding whole arrays, e.g. a database result, you might want to format the data of certain columns before displaying them. Attaching a formatting callback to a column using Console_Table::addFilter() helps you with that task.

There might be times when you have an array and just want to get it out to the user, without caring about all the small details. Console_Table::fromArray() is the single-line-of-code tool in such cases.

In combination with PEAR's Console_Color package you can format cells by using e.g. different colors for different cell values - very convenient in combination with column filters.

Console_Table examples

To get the feeling how Console_Table is used, try out the following examples.

A very simple example

Here we are following the basic steps to get some data out on the shell:

Creating a Console_Table object
Adding the header row
Adding some data rows
Rendering the table to the shell

<?php
require_once 'Console/Table.php';

$tbl = new Console_Table();
$tbl->setHeaders(
    array('Language', 'Year')
);
$tbl->addRow(array('PHP', 1994));
$tbl->addRow(array('C',   1970));
$tbl->addRow(array('C++', 1983));

echo $tbl->getTable();
?>

This examples would display as following:


+----------+------+
| Language | Year |
+----------+------+
| PHP      | 1994 |
| C        | 1970 |
| C++      | 1983 |
+----------+------+

Using column filtering with Console_Color

In this example we use Console_Table::addFilter() to colorize our table cells according to their value. Colorization is very easy using PEAR's Console_Color package. Just make sure you set the "color" parameter of Console_Color's constructor - otherwise you will see weird column widths.

After filling our table object with headers and data, we add an output filter by specifying a callback function. The first parameter to addFilter is the column number that shall be formatted, beginning with 0. Due to backwards compatibility with PHP4, addFilter requires a variable as second parameter, even if you just want to specfiy a simple function name.

We also have Console_Table align the "Profit" column right so that the commas are aligned equally.

<?php
require_once 'Console/Table.php';
require_once 'Console/Color.php';

//those could come e.g. from database
$data = array(
    array(2001, 128.23),
    array(2002, 256.42),
    array(2003, 10.21),
    array(2004, -25.79),
    array(2005, 0),
    array(2006, 982.12),
);

//prepare table
$tbl = new Console_Table(
    CONSOLE_TABLE_ALIGN_LEFT, CONSOLE_TABLE_BORDER_ASCII,
    1, null,
    true//this is important when using Console_Color
);
$tbl->setHeaders(
    array('Year', 'Profit')
);
$tbl->addData($data);

//add filter callback to colorize our profit column values
$callback = 'colorize';
$tbl->addFilter(1, $callback);

//Values should be aligned right
$tbl->setAlign(1, CONSOLE_TABLE_ALIGN_RIGHT);


echo $tbl->getTable();


/**
* Wraps Console color codes around $value,
* depending if its larger or smaller 0.
*
* @param float $value Value (column 1)
*
* @return string Colorful value
*/
function colorize($value)
{
    $str = number_format($value, 2, ',', '');
    if ($value < 0) {
        return Console_Color::convert('%r' . $str . '%n');
    } else if ($value == 0) {
        return $str;
    } else {
        return Console_Color::convert('%g' . $str . '%n');
    }
}
?>

The code above creates the following output, except that "Profit" values larger than 0 are colored in green, while the ones smaller zero are in red.


+------+--------+
| Year | Profit |
+------+--------+
| 2001 | 128,23 |
| 2002 | 256,42 |
| 2003 |  10,21 |
| 2004 | -25,79 |
| 2005 |   0,00 |
| 2006 | 982,12 |
+------+--------+

Console_Table::Console_Table

Console_Table::Console_Table – Console_Table constructor

Synopsis

require_once 'Console/Table.php';

Console_Table Console_Table::Console_Table ( string $align = CONSOLE_TABLE_ALIGN_LEFT , string $border = CONSOLE_TABLE_BORDER_ASCII , integer $padding = 1 , string $charset = null , boolean $color = false )

Description

Constructor

Console_Table::addCol

Console_Table::addCol() – Adds a column to the table

Synopsis

require_once 'Console/Table.php';

void Console_Table::addCol ( array $col_data , integer $col_id , integer $row_id )

Description

Adds a column to the table

Parameter

array $col_data: The data of the column. Can be numeric or associative array

integer $col_id: The column index to populate

integer $row_id: If starting row is not zero, specify it here

Throws

No exceptions thrown.

Note

This function can not be called statically.

Console_Table::addData

Console_Table::addData() – Adds data to the table.

Synopsis

require_once 'Console/Table.php';

void Console_Table::addData ( array $data , integer $col_id , integer $row_id )

Description

Adds data to the table. Argument should be a two dimensional array containing the data to be added.

Parameter

array $data: The data to add to the table

integer $col_id: Optional starting column ID

integer $row_id: Optional starting row ID

Throws

No exceptions thrown.

Note

This function can not be called statically.

Console_Table::addRow

Console_Table::addRow() – Adds a row to the table

Synopsis

require_once 'Console/Table.php';

void Console_Table::addRow ( array $row , array $append = true )

Description

Adds a row to the table

Parameter

array $row: The row data to add

array $append: Whether to append or prepend the row

Throws

No exceptions thrown.

Note

This function can not be called statically.

Console_Table::getTable

Console_Table::getTable() – Returns the table in wonderful ASCII art

Synopsis

require_once 'Console/Table.php';

void Console_Table::getTable ( )

Description

Returns the table in wonderful ASCII art

Throws

No exceptions thrown.

Note

This function can not be called statically.

Console_Table::insertRow

Console_Table::insertRow() – Inserts a row after a given row number in the table.

Synopsis

require_once 'Console/Table.php';

void Console_Table::insertRow ( array $row , integer $row_id )

Description

Inserts a row after a given row number in the table. If $row_id is not given it will prepend the row.

Parameter

array $row: The data to insert

integer $row_id: Row number to insert before

Throws

No exceptions thrown.

Note

This function can not be called statically.

Console_Table::setHeaders

Console_Table::setHeaders() – Sets the headers for the columns

Synopsis

require_once 'Console/Table.php';

void Console_Table::setHeaders ( array $headers )

Description

Sets the headers for the columns

Parameter

array $headers: The column headers

Throws

No exceptions thrown.

Note

This function can not be called statically.