README

Overview

XLSXWriter is a small PHP library built on top of PhpSpreadsheet. It provides a simple, chainable API for generating .xlsx files with headers, rows, offsets, and optional styling.

Requirement: PHP 8.5+.

Features

• Clean API for building spreadsheets and saving them to disk.
• Header and row styling with PhpSpreadsheet-style arrays.
• Offset support to position tables anywhere on the sheet.
• Minimal surface area: setHeaders, addRow, applyStyleToRange, write.

Installation

composer require xlsxwriter/excel

Quick Start

require 'vendor/autoload.php';

use XLSXWriter\ExcelWriter;

$writer = new ExcelWriter();

$writer->setHeaders(['Name', 'Age', 'Email'])
       ->addRow(['John Doe', 30, 'john@example.com'])
       ->addRow(['Jane Doe', 25, 'jane@example.com']);

if ($writer->write('output.xlsx')) {
    echo "Excel file created successfully.";
} else {
    echo "Error creating Excel file.";
}

Header Styling

setHeaders() accepts a style array compatible with PhpSpreadsheet. You can also disable borders by passing ['borders' => false].

use XLSXWriter\ExcelWriter;

$writer = new ExcelWriter();

$headerStyle = [
    'font' => [
        'size' => 16,
        'name' => 'Calibri',
        'bold' => true,
        'color' => ['argb' => 'FF003366'],
    ],
    'fill' => [
        'fillType' => \PhpOffice\PhpSpreadsheet\Style\Fill::FILL_SOLID,
        'startColor' => ['argb' => 'FFF2F2F2'],
    ],
];

$writer->setHeaders(['Product', 'Qty', 'Price'], $headerStyle)
       ->addRow(['Keyboard', 2, 49.90])
       ->addRow(['Mouse', 1, 19.90])
       ->write('styled_headers.xlsx');

Row Styling

addRow() also accepts a style array. This applies only to the row you are adding.

use XLSXWriter\ExcelWriter;

$writer = new ExcelWriter();

$writer->setHeaders(['Date', 'Total']);

$writer->addRow(['2024-01-01', 1000], [
    'fill' => [
        'fillType' => \PhpOffice\PhpSpreadsheet\Style\Fill::FILL_SOLID,
        'startColor' => ['argb' => 'FFEAF7FF'],
    ],
]);

$writer->addRow(['2024-01-02', 1500], [
    'borders' => false,
]);

$writer->write('row_styles.xlsx');

Offsets (Positioning)

Use setOffset($columnIndex, $rowIndex) to start the table at a specific cell.

use XLSXWriter\ExcelWriter;

$writer = new ExcelWriter();

// Start at D4 (column 4, row 4)
$writer->setOffset(4, 4)
       ->setHeaders(['City', 'Population'])
       ->addRow(['Madrid', 3223000])
       ->addRow(['Barcelona', 1620000])
       ->write('offset_example.xlsx');

Custom Range Styling

You can style any range after building your table:

use XLSXWriter\ExcelWriter;

$writer = new ExcelWriter();

$writer->setHeaders(['A', 'B', 'C'])
       ->addRow([1, 2, 3])
       ->applyStyleToRange('A1:C2', [
           'font' => [
               'name' => 'Calibri',
               'size' => 11,
           ],
       ])
       ->write('range_style.xlsx');

Advanced Formatting (Dates, Currency, Alignment)

PhpSpreadsheet lets you apply number formats and alignment. Use applyStyleToRange() after writing the data.

use XLSXWriter\ExcelWriter;

$writer = new ExcelWriter();

$writer->setHeaders(['Date', 'Amount', 'Status'])
       ->addRow(['2024-01-01', 1234.5, 'Paid'])
       ->addRow(['2024-01-02', 987.65, 'Pending']);

$writer->applyStyleToRange('A2:A3', [
    'numberFormat' => ['formatCode' => 'yyyy-mm-dd'],
]);

$writer->applyStyleToRange('B2:B3', [
    'numberFormat' => ['formatCode' => '"$"#,##0.00'],
    'alignment' => ['horizontal' => \PhpOffice\PhpSpreadsheet\Style\Alignment::HORIZONTAL_RIGHT],
]);

$writer->applyStyleToRange('C2:C3', [
    'alignment' => ['horizontal' => \PhpOffice\PhpSpreadsheet\Style\Alignment::HORIZONTAL_CENTER],
]);

$writer->write('formatted.xlsx');

Laravel Example

namespace App\Http\Controllers;

use XLSXWriter\ExcelWriter;

class ReportController extends Controller
{
    public function download()
    {
        $writer = new ExcelWriter();

        $writer->setHeaders(['Name', 'Score'])
               ->addRow(['Alice', 95])
               ->addRow(['Bob', 88]);

        $path = storage_path('app/reports/report.xlsx');

        if ($writer->write($path)) {
            return response()->download($path)->deleteFileAfterSend(true);
        }

        return response('Error creating Excel file.', 500);
    }
}

API Summary

ExcelWriter::setOffset(int $columns, int $rows): self
ExcelWriter::setHeaders(array $headers, array $customStyle = []): self
ExcelWriter::addRow(array $row, array $customStyle = []): self
ExcelWriter::applyStyleToRange(string $range, array $styleArray): self
ExcelWriter::write(string $filePath): bool

Error Handling

• write() returns true on success and false on failure.
• If you need error details, wrap the call or update FileSaver to log exceptions.

Limitations and Performance Notes

• This library writes in memory through PhpSpreadsheet; very large datasets will use significant RAM.
• Auto-sizing columns (if you enable it) can be slow on large sheets.
• Streaming writers are not included here; if you need huge exports, consider a streaming approach in PhpSpreadsheet.

Compatibility

• PHP 8.5+
• PhpSpreadsheet ^5.4

Testing

composer install
composer test

Roadmap

• Multi-sheet support.
• Optional streaming writer for large exports.
• Helper methods for common formats (dates, currency, percentages).

Contributing

Issues and PRs are welcome. Keep changes small and focused, and include a short description and tests when applicable.

Changelog

See composer.json for the current version.

Notes

• setHeaders() accepts both indexed arrays (['Name', 'Email']) and associative arrays (['Name' => 'string']).
• write() returns true on success and false on failure.
• Styling arrays follow the PhpSpreadsheet format. See their docs for full options.