Download the PHP package gbhorwood/tabletown without Composer

Tabletown

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:

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.

The above example will output the table:

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

Using one associative array

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:

Building tables from Eloquent collections

Eloquent collection objects can be used to build tables:

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

TABLE_BORDER_SOLID

TABLE_BORDER_DOUBLE

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.

The above example will output:

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

and outputs:

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:

Will output: