spydr97/php-cli-table

A simple library to create clean table outputs in PHP CLI scripts

1.0.1 2023-12-26 14:31 UTC

Requires

• php: ^8.1

Requires (Dev)

• spydr97/phpcs: ^1.0.1

MIT

README

This project's functionality was inspired by clitable and was created because I wanted some additional functionality. The code has undergone a full re-write with a bunch of changes to behaviour and functionality

Features

• Print table from data array without defining additional config
• Define custom table columns
• Create formatters for fields using closures
• Colorize headers, columns, rows and individual cells conditionally using closures
• [Not well tested] Colorize text within a table cell

Requirements

• PHP 8.1 or higher
• Composer set up in the desired project
• A CLI environment to run PHP scripts

Installation

composer require spydr97/php-cli-table

Usage

Basic Usage

For detailed examples and more complex usage please see the scripts in the example folder The bare minimum required to render a table is the following.

use Spydr97\PhpCliTable\CliTableBuilder;

$data = [
    [
        'id' => 1,
        'name' => 'Hello',
    ],
    [
        'id' => 2,
        'text' => 'World',
    ],
];

(new CliTableBuilder())
    ->setData($data)
    ->build();

Builder Methods

In the absence of proper documentation, (I haven't decided how I want to do that just yet) here are the methods exposed by the CliTableBuilder that can be used to manipulate the resultant table.

• setData(array $data) - sets the data array to populate the table
• setFields(array $fields) - sets the fields array to define table columns
• setBorderColor(TextColorEnum $color) - sets the color of the table border
• setHeaderColor(TextColorEnum $color) - sets the default color of each table heading (superseded by the FIELD_HEADER_COLOR property in a field definition)
• setCellColor(TextColorEnum $color) - sets the default color of each table cell (superseded by the FIELD_COLUMN_COLOR property in a field definition or DATA_COLOR property in a data item)
• setEmptyCellPlaceholder(string $empty_cell_placeholder) - sets the text to show when the particular data item value does not exist
• setShowHeader(bool $show_header) - sets whether to show or hide table headings
• build() - validates data and prints the table to the console

Colors

Colors are defined in the \Spydr97\PhpCliTable\TextColorEnum class. The following colors are available

• TextColorEnum::BLACK
• TextColorEnum::WHITE
• TextColorEnum::DARK_RED
• TextColorEnum::RED
• TextColorEnum::DARK_GREEN
• TextColorEnum::GREEN
• TextColorEnum::DARK_YELLOW
• TextColorEnum::YELLOW
• TextColorEnum::DARK_BLUE
• TextColorEnum::BLUE
• TextColorEnum::DARK_CYAN
• TextColorEnum::CYAN
• TextColorEnum::LIGHT_GREY
• TextColorEnum::DARK_GREY
• TextColorEnum::RESET

Data

In addition to data fields, each row can have a _color (DataConstants::DATA_COLOR) property which defines the color of the particular row. This can either be of type TextColorEnum or Closure. If a TextColorEnum is used then the color is applied on the whole row. If a Closure is used the color can either be applied to the whole row or to specific fields.

A DataConstants::DATA_COLOR closure is provided two params, $datum and $field which correspond to the current data row item and column field definition respectively. The return type of this closure must be either a TextColorEnum or null.

e.g. This closure sets the color of every column for the particular row to BLUE except the text column which is left as the configured default (i.e. not overridden).

use \Spydr97\PhpCliTable\Constants\DataConstants;
...
$data = [
   ...
   DataConstants::DATA_COLOR => function (array $datum, array $field): ?TextColorEnum {
            if ($field[FieldConstants::FIELD_KEY] == 'text') {
                return null;
            }
            return TextColorEnum::BLUE;
        }
]

Fields

Fields can have the following properties defined.

Property Name	Type	Closure Return Type	Required	FieldConstant
Key	String	---	true	FIELD_KEY
Name	String	---	false	FIELD_NAME
Column Color	TextColorEnum Closure	TextColorEnum null	false	FIELD_COLUMN_COLOR
Header Color	TextColorEnum Closure	TextColorEnum null	false	FIELD_HEADER_COLOR
Formatter	Closure	String	false	FIELD_FORMATTER

The closure definitions for the above Closures are as follows:

use Spydr97\PhpCliTable\Constants\FieldConstants;
...
$fields = [
    ...
    [
        ...
        FieldConstants::FIELD_HEADER_COLOR => function (array $field): ?TextColorEnum {
            return TextColorEnum::DARK_RED;
        },
       
        FieldConstants::FIELD_COLUMN_COLOR => function (array $datum, array $field): ?TextColorEnum {
            return TextColorEnum::DARK_RED;
        },
       
        FieldConstants::FIELD_FORMATTER => function (array $datum, array $field): string {
            return strtoupper($datum[$field[FieldConstants::FIELD_KEY]]);
        },
        ...
    ]
]

Please note that the FieldConstants::FIELD_HEADER_COLOR closure only has a single parameter $field.