gbhorwood / tabletown
A table output formatting utility for arrays
Requires
- php: ^8.1
Requires (Dev)
- illuminate/database: ^10.37
- php-mock/php-mock-phpunit: ^2.7
- phpstan/phpstan: 1.10
- phpunit/phpunit: ^10.2
This package is auto-updated.
Last update: 2024-10-27 21:51:25 UTC
README
Tabletown is a php package for converting data, such as arrays, into nice ascii/ansi tables, similar to MySql's standard output.
Tabletown can accept input from arrays, PDO statements, and eloquent collections. It properly handles multibyte characters, including emojis, as well as unprintable ansi character sequences and tabs. It allows setting per-column alignment and offers a number of border style options.
Tabletown was developed as an internal-use tool for fruitbat studios/cloverhitch technologies/kludgetastic implementations.
Install
Tabletown is installed via composer:
composer require gbhorwood/tabletown
Features
Tabletown's basic features are:
- Multiple input types: Input can be arrays,
PDOStatement
objects or Eloquent collections. - Border styling: Broders can be set as either solid lined, double solid lined or standard, MySql-style.
- Per-column alignment: Individual columns can be aligned left, right, or centre.
- Multi-line rows Line breaks in data are preseved and presented as multi-line rows.
- Unicode-safe: Multi-byte characters are handled.
- Tab-safe: Tab characters are handled with proper tab stops.
- (mostly) ANSI-safe: Most ansi escape codes, including backspace, are handled.
Quickstart
Tabletown has one static method get()
. The fastest way to create and print a table is to provide the get()
method with two arguments: an array of headers, and an array of data for table rows.
<?php require __DIR__ . "/vendor/autoload.php"; use Gbhorwood\Tabletown\Table; // array of column headers $headers = ['Artist', 'Title', 'Year']; // array of arrays, one for each row in the table $rows = [ ['Bratmobile', 'Pottymouth', 1993], ['Coltrane, John', 'Giant Steps', 1959], ]; // get and output the table $myTable = Table::get($headers, $rows); print $myTable;
The above example will output the table:
+----------------+-------------+------+
| Artist | Title | Year |
+----------------+-------------+------+
| Bratmobile | Pottymouth | 1993 |
| Coltrane, John | Giant Steps | 1959 |
+----------------+-------------+------+
Building tables from arrays
Tables can be built from arrays in one of two ways: either with two separate arrays for the headers and rows, or with one associative array.
Using separate arrays for headers and rows
// array of column headers $headers = ['Artist', 'Title', 'Year']; // array of arrays, one for each row in the table $rows = [ ['Bratmobile', 'Pottymouth', 1993], ['Coltrane, John', 'Giant Steps', 1959], ]; $myTable = Table::get($headers, $rows);
Using one associative array
$data = [ [ 'Artist' => 'Bratmobile', 'Title' => 'Pottymouth', 'Year' => 1993 ], [ 'Artist' => 'Coltrane, John', 'Title' => 'Giant Steps', 'Year' => 1959 ], ]; $myTable = Table::get($data);
Note: Tabletown will throw an exception if the column counts do not match for all rows.
Building tables from PDO statements
Tabletown can build tables from a PDOStatement
object returned from the PDO query()
method:
$dsn = "mysql:host=<hostname>;dbname=<dbname>;charset=UTF8"; $pdo = new PDO($dsn, "<username>", "<password>"); $stmt = $pdo->query("SELECT * FROM albums"); $myTable = Table::get($stmt);
Building tables from Eloquent collections
Eloquent collection objects can be used to build tables:
$albums = Album::all(); $myTable = Table::get($albums);
Styling borders
Tabletown has three different types of borders that can be set by passing one of the border constants as an argument. The border style constants are:
TABLE_BORDER_STANDARD
The default MySql-style border. If no border style is supplied, the standard border is used.TABLE_BORDER_SOLID
A border made of solid lines.TABLE_BORDER_DOUBLE
A border made of double solid lines.
The usage and output of the border styles is:
TABLE_BORDER_STANDARD
print Table::get($headers, $rows, TABLE_BORDER_STANDARD); // or print Table::get($dataArray, TABLE_BORDER_STANDARD); // or print Table::get($pdoStatement, TABLE_BORDER_STANDARD); // or print Table::get($eloquentCollection, TABLE_BORDER_STANDARD);
+----------------+-------------+------+
| Artist | Title | Year |
+----------------+-------------+------+
| Bratmobile | Pottymouth | 1993 |
| Coltrane, John | Giant Steps | 1959 |
+----------------+-------------+------+
TABLE_BORDER_SOLID
print Table::get($headers, $rows, TABLE_BORDER_SOLID); // or print Table::get($dataArray, TABLE_BORDER_SOLID); // or print Table::get($pdoStatement, TABLE_BORDER_SOLID); // or print Table::get($eloquentCollection, TABLE_BORDER_SOLID);
┌────────────────┬─────────────┬──────┐
│ Artist │ Title │ Year │
├────────────────┼─────────────┼──────┤
│ Bratmobile │ Pottymouth │ 1993 │
│ Coltrane, John │ Giant Steps │ 1959 │
└────────────────┴─────────────┴──────┘
TABLE_BORDER_DOUBLE
print Table::get($headers, $rows, TABLE_BORDER_DOUBLE); // or print Table::get($dataArray, TABLE_BORDER_DOUBLE); // or print Table::get($pdoStatement, TABLE_BORDER_DOUBLE); // or print Table::get($eloquentCollection, TABLE_BORDER_DOUBLE);
╔════════════════╦═════════════╦══════╗
║ Artist ║ Title ║ Year ║
╠════════════════╬═════════════╬══════╣
║ Bratmobile ║ Pottymouth ║ 1993 ║
║ Coltrane, John ║ Giant Steps ║ 1959 ║
╚════════════════╩═════════════╩══════╝
Aligning columns
Columns in tables are left-aligned by default. Aligments can be changed by passing an array of alignment constants after the border style constant argument.
The valid alignment constants are:
LEFT
RIGHT
CENTRE
CENTER
Note that null values are considered LEFT
.
$headers = ['Artist', 'Title', 'Year']; $rows = [ ['Bratmobile', 'Pottymouth', 1993], ['Coltrane, John', 'Giant Steps', 1959], ]; print Table::get($headers, $rows, TABLE_BORDER_STANDARD, [RIGHT, LEFT, CENTRE]);
The above example will output:
+----------------+-------------+------+
| Artist | Title | Year |
+----------------+-------------+------+
| Bratmobile | Pottymouth | 1993 |
| Coltrane, John | Giant Steps | 1959 |
+----------------+-------------+------+
Multiple line handling
Tabletown perserves new lines in the input data, creating multi-line rows in the table.
For instance, this example creates rows with pretty-printed json
$headers = ['id', 'some_json']; $rows = [ [1, json_encode(['artist' => 'Bratmobile', 'title' => 'Pottymouth'], JSON_PRETTY_PRINT)], [2, json_encode(['artist' => 'Coltrane, John', 'title' => 'Giant Steps'], JSON_PRETTY_PRINT)], ]; $myTable = Table::get($headers, $rows); print $myTable;
and outputs:
+----+---------------------------------+
| id | some_json |
+----+---------------------------------+
| 1 | { |
| | "artist": "Bratmobile", |
| | "title": "Pottymouth" |
| | } |
| 2 | { |
| | "artist": "Coltrane, John", |
| | "title": "Giant Steps" |
| | } |
+----+---------------------------------+
Note: The linebreak characters used are those for the platform running Tabletown as defined by the PHP_EOL
constant.
Tab handling
Tabs are handled in Tabletown as tab stops on eight spaces on a per-line basis. This allows vertically aligning text on tab stops across multiple lines. For example:
$pottyMouth =<<<TXT Pottymouth label:\tKRS yr:\t1993 rating:\t4.5 TXT; $giantSteps =<<<TXT Giant Steps label:\tAtlantic yr:\t1959 rating:\t5 TXT; $headers = ['Artist', 'Title']; $rows = [ ['Bratmobile', $pottyMouth], ['Coltrane, John', $giantSteps], ]; $myTable = Table::get($headers, $rows); print $myTable;
Will output:
+----------------+------------------+
| Artist | Title |
+----------------+------------------+
| Bratmobile | Pottymouth |
| | label: KRS |
| | yr: 1993 |
| | rating: 4.5 |
| Coltrane, John | Giant Steps |
| | label: Atlantic |
| | yr: 1959 |
| | rating: 5 |
+----------------+------------------+