README

HTML table builder library for PHP 7.4+ and PHP 8 with:

Fluent, chainable interface
Full control over table structure (headers, body, footer)
Column formatters with access to row data
Column grouping with sections
Fine-grained attribute control (table, row, cell, column level)
Column-specific styling

Installation

composer require alison4kk/table-builder

For local development:

composer install

Quick start

<?php

require __DIR__ . '/vendor/autoload.php';

use TableBuilder\TableBuilder;

$table = new TableBuilder();

// Set header (automatically defines columns)
$table->setHeader([
    'id' => 'ID',
    'name' => 'Name',
    'email' => 'Email',
    'status' => 'Status'
]);

// Add multiple rows
$table->addRows([
    ['id' => 1, 'name' => 'Alice', 'email' => 'alice@example.com', 'status' => 'Active'],
    ['id' => 2, 'name' => 'Bob', 'email' => 'bob@example.com', 'status' => 'Inactive'],
    ['id' => 3, 'name' => 'Charlie', 'email' => 'charlie@example.com', 'status' => 'Active'],
]);

// Add column formatters
$table->addColumnFormatter('id', function($value) {
    return '#' . $value;
});

$table->addColumnFormatter('status', function($value, $rowData) {
    $class = $value === 'Active' ? 'success' : 'danger';
    return sprintf('<span class="badge badge-%s">%s</span>', $class, $value);
});

// Apply table attributes
$table->setTableAttributes(['class' => 'table table-striped']);

// Generate HTML
echo $table->html();

API Reference

Core Methods

`setHeader(array $headerData): TableBuilder`

Set header and automatically define columns. Accepts associative array where:

Simple string: 'name' => 'Name'
Array with attributes: 'name' => ['Name', 'style' => 'text-align: left;', 'class' => 'header-col']

$table->setHeader([
    'id' => 'ID',
    'name' => ['Name', 'class' => 'name-column'],
]);

`addColumn(string $columnName): TableBuilder`

Define a single column.

$table->addColumn('id')->addColumn('name');

`addColumns(array $columnNames): TableBuilder`

Define multiple columns at once.

$table->addColumns(['id', 'name', 'email']);

`addRow(array $rowData, array $rowAttributes = []): TableBuilder`

Add a single data row. Cell values can be strings or arrays [value, attributes].

$table->addRow([
    'id' => 1,
    'name' => ['Alice', 'style' => 'font-weight: bold;'],
    'email' => 'alice@example.com'
]);

// With row attributes
$table->addRow(['id' => 2, 'name' => 'Bob'], ['class' => 'active-row']);

`addRows(array $rows): TableBuilder`

Add multiple rows at once.

$table->addRows([
    ['id' => 1, 'name' => 'Alice'],
    ['id' => 2, 'name' => 'Bob'],
    ['id' => 3, 'name' => 'Charlie']
]);

`addColumnFormatter(string $columnName, callable $formatter): TableBuilder`

Add a formatter callback for a column. The callback receives the cell value and the entire row data.

// Simple formatter
$table->addColumnFormatter('id', function($value) {
    return '#' . $value;
});

// Formatter with row data access
$table->addColumnFormatter('status', function($value, $rowData) {
    $class = $rowData['active'] ? 'success' : 'danger';
    return sprintf('<span class="badge badge-%s">%s</span>', $class, $value);
});

Note: Formatters are only applied to <tbody> cells, not headers or footers.

Header & Footer Methods

`addHeaderRow(array $headerRowData): TableBuilder`

Add an additional header row.

$table->setHeader(['name' => 'Full Name', 'email' => 'Email Address']);
$table->addHeaderRow(['name' => 'First & Last', 'email' => 'Contact']);

`addFooterRow(array $footerRowData): TableBuilder`

Add a footer row.

$table->addFooterRow(['name' => 'Total', 'email' => '2 records']);

Styling Methods

`setTableAttributes(array $attributes): TableBuilder`

Set HTML attributes for the <table> tag.

$table->setTableAttributes([
    'class' => 'table table-striped table-hover',
    'border' => '1',
    'data-sortable' => 'true'
]);

`setColumnAttributes(string $columnName, array $attributes): TableBuilder`

Set attributes for specific column cells in tbody.

$table->setColumnAttributes('email', ['style' => 'color: blue;']);

`setColumnStyle(string $columnName, string|array $style): TableBuilder`

Apply CSS styles to a column.

// String style
$table->setColumnStyle('id', 'text-align: center;');

// Array style (will be joined with semicolons)
$table->setColumnStyle('name', [
    'text-align' => 'left',
    'font-weight' => 'bold'
]);

Output Method

`html(): string`

Generate the final HTML table.

$html = $table->html();
echo $html;

Sections (Column Grouping)

Organize columns into logical sections with colspan:

$table->setHeader(['id' => 'ID']);
$table->addSection('$all', ['id']); // "$all" = all columns
$table->addRow(['id' => 1]);

Complete Example

<?php

require __DIR__ . '/vendor/autoload.php';

use TableBuilder\TableBuilder;

$users = [
    ['id' => 1, 'name' => 'Alice Johnson', 'email' => 'alice@company.com', 'department' => 'Engineering', 'active' => true],
    ['id' => 2, 'name' => 'Bob Smith', 'email' => 'bob@company.com', 'department' => 'Sales', 'active' => false],
    ['id' => 3, 'name' => 'Charlie Brown', 'email' => 'charlie@company.com', 'department' => 'Engineering', 'active' => true],
];

$table = new TableBuilder();

$table
    ->setTableAttributes(['class' => 'table table-striped table-hover'])
    ->setHeader([
        'id' => 'ID',
        'name' => 'Name',
        'email' => 'Email',
        'department' => 'Department',
        'active' => 'Status'
    ])
    ->addColumnFormatter('id', function($value) {
        return '#' . str_pad($value, 3, '0', STR_PAD_LEFT);
    })
    ->addColumnFormatter('active', function($value, $rowData) {
        $label = $value ? 'Active' : 'Inactive';
        $class = $value ? 'success' : 'secondary';
        return sprintf('<span class="badge badge-%s">%s</span>', $class, $label);
    })
    ->setColumnStyle('id', 'text-align: center; font-weight: bold;')
    ->setColumnStyle('active', 'text-align: center;')
    ->addRows($users)
    ->addFooterRow([
        'id' => '',
        'name' => 'Total',
        'email' => count($users) . ' users',
        'department' => '',
        'active' => ''
    ]);

?>
<!DOCTYPE html>
<html>
<head>
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
</head>
<body class="p-5">
    <h1>Users Directory</h1>
    <?php echo $table->html(); ?>
</body>
</html>

Testing

composer test

All tests validate header setup, bulk row insertion, column formatters, styling, and HTML structure.

Features

✅ Automatic column definition from header
✅ Bulk row insertion (addRows)
✅ Column value formatters with row context
✅ Multiple header rows
✅ Footer rows
✅ Fine-grained attribute control (table, row, cell, column)
✅ CSS styling at column level
✅ Column grouping with sections
✅ Fluent, chainable interface
✅ Full PHP 7.4+ and PHP 8.x support

PHP Version

Requires PHP 7.4+ with full PHP 8.x support.

License

MIT

alison4kk / table-builder

Maintainers

Package info

Statistics

Security