Download the PHP package eznio/tabler without Composer

ASCII-table formatter and renderer

Overview

Simple (in the beginning) helper which can format and render ASCII tables for CLI tools.

Basic usage:

which produces

Basic classes and interfaces

Classes:

• Tabler - facade class for the whole package. Holds some shortcut calls for setting table data, generating, styling and rendering
• Composer - scans headers and data arrays, gathers maximum lengths, composes column structure and tries to get column names if missing
• LayoutBuilder - gets Composer with parsed table data and generates TableLayout structure(-s) (see below)
• Styler - helper to set styles (bg color, fg color, some text styles) for the line of text
• Element - basic class of TableLayout structure

Interfaces:

• Renderer - interface to be implemented by rendering classes

Table elements

What and what for

TableLayout is a metastructure representing the whole table and its elements - rows and cells.

This one is useful mostly for styling purposes. For example, if we want to display 2nd column in red color:

Schema

Overall elements layout and nesting:

Short element reference

• TableLayout - the whole table. Border colors are set here
• HeaderLine - first row with column headers
• HeaderCell - single heading row's cell.
• DataGrid - overall data part
• DataRow - single data row
• DataCell - single data cell

Getting/setting child elements

1. Getting TableLayout:

2. Getting top elements:

3. Getting HeaderLine cells

4. Getting data rows and cells

Facade public API reference

Main part:

• Sets table data 2-level nested array:

  • Top-level array elements are treated as rows and should be arrays too
  • Row elements are considered cells. Their array keys are column IDs

• Sets table headers array. Its elements are counted as column headers, and their array keys are column IDs.

• Returns TableLayout structure. If no one is built - builds it before returning.

• Sets rendering class to render table

• Setting $guessHeaderNames to true means using columnd IDs as header titles if no titles are provided

  If $guessHeaderNames is set to false - column names without provided titles are rendered as empty strings

• Renders current (if no TableLayout is passed), or given TableLayout component into table string representation and returns it

Styling shortcuts:

Descriptions are available in source code if needed

Styling

Style arrays

Styles can be set as single value:

or array:

If more that one array element is set from the bg or fg colors - last one is being used. Text styles are free to use in cojunction.

Style reference classes

• references\ForegroundColors
• references\BackgroundColors
• references\TextStyles

Styling elements

• TableLayout - set border bg and fg colors
• HeaderLine - set bg/fg/text styles for the whole headers, can be override at HeaderCell level
• HeaderCell - set bg/fg/text styles, minimum length, text alignment and paddings for single header cell, overrides HeaderLine-level settings
• DataRow - set bg/fg/text styles and text alignment for single data row, can be override in DataCell
• DataCell - set bg/fg/text styles, minimum length, text alignment and paddings for single data cell, overrides DataRow-level settings

Renderers

Table data

In examples in this part the following Tabler setup will be used:

MySQL-style renderer

MC-style renderer

"Clear" styled renderer

"Single line" styled renderer

More radical example