HTML conversion

The HTMLConverter converts a CSV records collection into an HTML Table using PHP’s DOMDocument class.

Settings

Prior to converting your records collection into an HTML table, you may wish to configure optional information to improve your table rendering.

Before version 9.22 the class was using the XMLConverter internally. This is no longer the case to take advantage of PHP8.4 new functionalities. If an error occurs while validating the submitted values, a DOMException exception will be thrown.

HTMLConverter::table

public HTMLConverter::table(string $class_name, string $id_value = ''): self

This method sets the optional table class and id attribute values.

The default class attribute value is table-csv-data.

The default id attribute value is an empty string.

HTMLConverter::tr

public HTMLConverter::tr(string $record_offset_attribute_name): self

This method sets the optional attribute name for the record offset on the HTML tr tag.

If none is used or an empty string is given, the record offset information won't be exported to the HTML table.

HTMLConverter::td

public HTMLConverter::td(string $fieldname_attribute_name): self

This method sets the optional attribute name for the field name on the HTML td tag.

If none is used or an empty string is given, the field name information won't be exported to the HTML table.

HTMLConverter::formatter

New feature introduced in version 9.20.0

public HTMLConverter::formatter(?callable $formatter): self

This method allows to apply a callback prior to converting your collection individual item. This callback allows you to specify how each item will be converted. The formatter should return an associative array suitable for conversion.

The Formatter callback does not affect the footer and/or header conversion.

HTMLConverter::when

New feature introduced in version 9.22.0

This method allows to conditionally create your converter depending on the success or failure of a condition.

use League\Csv\HTMLConverter;

$converter = (new HTMLConverter());
if ($condition) {
    $converter = $converter->td('data-field');
} else {
    $converter = $converter->td('');
}

becomes

$converter = (new HTMLConverter())
    ->when(
        $condition,
        fn (HTMLConverter $c) => $c->td('data-field'),
        fn (HTMLConverter $c) => $c->td(''),
    );
)

The else expression is not required but if present in MUST BE a callable which only accepts the HTMLConverter instance and returns null or a HTMLConverter instance.

The only requirements are:

• that the condition is a boolean or a callable that returns a boolean.
• the callback returns a HTMLConverter instance or null.

Conversion

Since version 9.3.0 this method accepts optional header and footer records to display them in the exported HTML table.

public HTMLConverter::convert(iterable $records, array $header_record = [], array $footer_record = []): string

The HTMLConverter::convert accepts an iterable which represents the records collection and returns a string. It optionally accepts:

• an array of strings representing the tabular header;
• an array of strings representing the tabular footer;

If any of these arrays are present and non-empty, the tabular data will be contained in a tbody tag as per HTML specification.

use League\Csv\HTMLConverter;

//we fetch the info from a DB using a PDO object
$sth = $dbh->prepare("SELECT firstname, lastname, email FROM users LIMIT 2");
$sth->setFetchMode(PDO::FETCH_ASSOC);
$sth->execute();

$converter = new HTMLConverter()
    ->table('table-csv-data', 'users')
    ->tr('data-record-offset')
    ->td('title')
;

// The PDOStatement Object implements the Traversable Interface
// that's why Converter::convert can directly insert
// the data into the HTML Table
$html = $converter->convert($sth);

echo $html;

// <table class="table-csv-data" id="users">
// <tr data-record-offset="0">
// <td title="firstname">john</td>
// <td title="lastname">doe</td>
// <td title="email">john.doe@example.com</td>
// </tr>
// <tr data-record-offset="1">
// <td title="firstname">jane</td>
// <td title="lastname">doe</td>
// <td title="email">jane.doe@example.com</td>
// </tr>
// </table>


$html = $converter->convert($sth, ['First Name', 'Last Name', 'E-mail']);

echo $html;

// <table class="table-csv-data" id="users">
// <thead>
// <tr>
// <th scope="col">First Name</th>
// <th scope="col">Last Name</th>
// <th scope="col">E-mail</th>
// </tr>
// </thead>
// <tbody>
// <tr data-record-offset="0">
// <td title="firstname">john</td>
// <td title="lastname">doe</td>
// <td title="email">john.doe@example.com</td>
// </tr>
// <tr data-record-offset="1">
// <td title="firstname">jane</td>
// <td title="lastname">doe</td>
// <td title="email">jane.doe@example.com</td>
// </tr>
// </tbody>
// </table>

If needed you can use the CharsetConverter object to correctly encode your CSV records before conversion.