README

PHP library to generate Excel, CSV and PDF reports (plus ready-to-embed HTML) from plain tabular data. It is a thin, opinionated layer on top of PhpSpreadsheet and mPDF: you describe the columns once and hand over an array of rows, and the library takes care of headers, number/date formatting, column sizing and summary totals.

• Spanish version: README.es.md
• AI consumption spec: AI_USAGE.md · AI_USAGE.es.md

Features

• One definition, four outputs: on-screen HTML table, .xlsx, .csv, .pdf.
• Per-column formats: text, number, decimal, money, date, datetime.
• Optional summary row per column (SUM for numeric, COUNTIF for text/date).
• Automatic date conversion, column auto-sizing and word-wrap for long values.
• No database required — it works with any array of rows, wherever they come from.

Requirements

• PHP ^8.2
• ext-zip (required by PhpSpreadsheet to write .xlsx)
• ext-gd and ext-mbstring (required by mPDF to write .pdf)

Installation

composer require hstanleycrow/easyphpreports

Quick start

The library only needs two things: a columns definition and an array of rows. Each row is an associative array whose values are read in order — the keys are up to you, but the value order must match the columns definition.

<?php

require 'vendor/autoload.php';

use hstanleycrow\EasyPHPReports\PHPReport;
use hstanleycrow\EasyPHPReports\CellFormat;

// 1. Describe the columns.
$columns = [
    ['header' => 'No',     'format' => CellFormat::NUMBER, 'calculate' => false],
    ['header' => 'Date',   'format' => CellFormat::DATE,   'calculate' => false],
    ['header' => 'Branch', 'format' => CellFormat::TEXT,   'calculate' => false],
    ['header' => 'Sales',  'format' => CellFormat::MONEY,  'calculate' => true],
];

// 2. Provide the rows (values in the same order as the columns above).
$rows = [
    ['no' => 1, 'date' => '2023-12-08', 'branch' => 'Downtown', 'amount' => 24.40],
    ['no' => 2, 'date' => '2023-12-08', 'branch' => 'Uptown',   'amount' => 17.25],
    ['no' => 3, 'date' => '2023-12-08', 'branch' => 'Airport',  'amount' => 29.50],
];

// 3. Register the built-in report types once.
PHPReport::initialize();

// 4. Render an on-screen HTML table.
$report = new PHPReport(PHPReport::SCREEN, $columns, $rows);
echo $report->generate();

The sample data above is hardcoded for illustration only. In a real application the rows would come from a database, an API, or any other source. The library does not depend on any specific data source.

Generating downloadable files

For EXCEL, CSV and PDF you must pass a file path (without extension — it is added automatically). Make sure the target directory exists and is writable.

<?php

use hstanleycrow\EasyPHPReports\PHPReport;

PHPReport::initialize();

$path = 'exportedReports/sales-' . date('YmdHis'); // no extension needed

$report = new PHPReport(PHPReport::EXCEL, $columns, $rows, $path);
$file   = $report->generate(); // e.g. "exportedReports/sales-20231208101500.xlsx"

if ($report->isDownloadable()) {
    // serve $file for download, store it, e-mail it, etc.
    header('Content-Disposition: attachment; filename="' . basename($file) . '"');
    readfile($file);
}

Swap PHPReport::EXCEL for PHPReport::CSV or PHPReport::PDF to get the other formats — everything else stays the same.

Column definition

Each entry in the columns array is an associative array with three keys:

CellFormat constants

An invalid DATE/DATETIME value throws InvalidArgumentException.

Public API

Report types

Notes and limitations

• Value order matters. Each row is consumed positionally; the Nth value maps to the Nth column regardless of its array key. Keep the same order in every row.
• SCREEN returns an HTML <table> styled with Bootstrap-friendly classes (table table-bordered table-responsive); it is meant to be embedded in your own page.
• EXCEL/CSV/PDF require a writable target directory; the extension is appended for you.
• The MONEY format is fixed to USD ($).
• Summary rows use spreadsheet formulas; spreadsheet apps (Excel, LibreOffice) recompute them on open.

License

MIT © Harold Rivas (Harold Crow)