easy-excel

A PHP spreadsheet extension written in Go for FrankenPHP, exposing a PhpSpreadsheet-compatible API while doing all heavy lifting (XML generation, ZIP compression, parsing, formulas) in compiled Go via excelize.

Target: PhpSpreadsheet's ergonomics at OpenSpout-class (constant) memory and a multiple of both libraries' throughput. Design rationale, bottleneck analysis and measured claims live in PLAN.md; API coverage in COMPAT.md; formula coverage in FORMULAS.md; the raw extension API (no composer package needed) in NATIVE.md; known gaps in MISSING.md.

How it works

PhpOffice\PhpSpreadsheet\* (aliases)        ← your existing code, unchanged
        │
EasyExcel\Compat\* PHP shim                 ← tiny objects, write-behind row buffer
        │  flat easy_excel_*() calls, batched rows (1 CGO call / 512 rows)
Go extension: handle registry → excelize    ← StreamWriter, style interner,
                                              admission control, path policy

Key properties:

• Dual write path — sequential writes stream at constant memory; an out-of-order write triggers a one-time documented fallback to random access.
• Load control — heavy operations pass a weighted semaphore + memory budget; overload surfaces as EasyExcel\Exception\Overloaded (map it to HTTP 429 or your queue) instead of OOM-killing the worker.
• Security defaults — unzip-bomb limits, path allowlist (EASY_EXCEL_ALLOWED_PATHS), capability-style random handles, opt-in CSV injection guard.

Quick start (Docker)

# run the test suites
make test                 # = docker build --target=go-test / --target=php-test

# build FrankenPHP with the extension baked in
make build                # produces the frankenphp-easy-excel image

# or pull the published image
docker pull ghcr.io/xiidea/frankenphp8.5-easy-excel:latest

Use the shim in your app (the image ships it at /opt/easy-excel/php):

{
    "repositories": [{ "type": "path", "url": "/opt/easy-excel/php" }],
    "require": { "easy-excel/polyfill": "*" }
}

use PhpOffice\PhpSpreadsheet\Spreadsheet;          // resolved to EasyExcel\Compat\*
use PhpOffice\PhpSpreadsheet\IOFactory;

$spreadsheet = new Spreadsheet();
$sheet = $spreadsheet->getActiveSheet();
$sheet->fromArray($hugeDataset);                    // batched straight into Go
$sheet->setCellValue('A1', 'Hello');                // buffered, flushed in row batches
IOFactory::createWriter($spreadsheet, 'Xlsx')->save('report.xlsx');
$spreadsheet->disconnectWorksheets();               // frees the native workbook

The aliases stay dormant when the real phpoffice/phpspreadsheet is installed or the extension is missing, so adoption can be incremental.

The shim is optional: the extension's flat easy_excel_*() ABI is usable straight from PHP with no composer dependency — see NATIVE.md.

Configuration

Env var	Default	Meaning
EASY_EXCEL_MAX_CONCURRENT	max(2, NumCPU)	heavy ops (open/save/scan) in flight
EASY_EXCEL_ACQUIRE_TIMEOUT_MS	30000	wait before Overloaded is raised
EASY_EXCEL_MEMORY_BUDGET_MB	512	estimated live-workbook bytes circuit breaker
EASY_EXCEL_ALLOWED_PATHS	unset (any local path)	colon-separated base dirs for load/save

Repository layout

extension/   Go module: registry, limits, exio, compat, core + easy_excel.go (bridge)
php/         Composer package: EasyExcel\Compat shim + alias bootstrap + tests
bench/       Phase-0 rig: identical workloads across 5 libraries
Dockerfile   go-test | php-test | generate | build | runner stages

Development

make test            # Docker: Go (race) + PHP suites
make host-test       # local toolchains, faster iteration
make bench           # baseline all libraries (results.csv)

Notes:

• extension/easy_excel.go is excluded from gofmt: gofmt mangles //export_php: directives (underscores aren't recognized as directive names). make fmt formats only the pure packages.
• The bridge compiles only inside the generate/build Docker stages (needs PHP ZTS headers); the five pure-Go packages build and test anywhere.
• CI publishes ghcr.io/<owner>/frankenphp-easy-excel on main pushes and semver tags (see .github/workflows/publish.yml).

Measured performance

Write N rows × 10 mixed columns, one process per run (Docker, PHP 8.5, Apple Silicon; bench/baseline-2026-07-09-php8.5.csv). "Workload memory" is the whole-process peak RSS (VmHWM) minus the idle runtime baseline, so for easy-excel it includes the Go-side buffers that PHP's own peak-memory counter cannot see:

Library	100k rows	1M rows	Workload memory (1M)
PhpSpreadsheet 5.8	23.64s	out of memory (6GB cap)	~647MB at 100k
rap2hpoutre/fast-excel	6.58s	64.49s	~3MB
OpenSpout 4.x	5.85s	60.07s	~3MB
fast-excel-writer 6.x	4.29s	45.73s	~3MB
easy-excel (PhpSpreadsheet API)	1.37s	11.91s	~189MB
easy-excel (native API)	1.28s	11.35s	~186MB

The two easy-excel lanes produce byte-identical files; the Compat shim costs about 5% over raw EasyExcel\Native calls. PHP-side peak memory stays at 4MB in both lanes — the ~186MB lives in the Go extension (excelize stream buffers), which still writes 1M rows in a fraction of the memory PhpSpreadsheet needs for 100k. (The 2026-06-11 baseline ran ~1.4× faster across all lanes — sessions vary, compare ratios, not absolute times.)

Styled report (same data + styled header, two column number formats, widths, freeze pane, auto-filter; write-styled workload, bench/baseline-2026-06-12-php8.5-phase3.csv; that session's unstyled 1M control was 11.9s, matching the table above, so its times are directly comparable):

Library	100k rows	1M rows	Peak PHP memory
PhpSpreadsheet 5.8	26.79s	—	670MB at 100k
easy-excel	1.93s (13.9×)	18.5s	4MB

Styles stream inline, and since Phase 3 the auto-filter no longer degrades either: the <autoFilter> element is injected into the saved container directly (COMPAT.md §16). In Phase 2 the same styled 1M lane took 121s; the streaming filter and the batch-uniform style resolver cut it to ~1.6× the unstyled write.

Status

Phase 3 (advanced compat) complete, on top of Phase 2's full style graph and worksheet structure:

• Formulas: getCalculatedValue() and bulk toArray(calculateFormulas: true) via excelize's engine — 466/529 PhpSpreadsheet functions, per- function table in FORMULAS.md.
• Data validation, conditional formatting, images, sheet protection with the PhpSpreadsheet APIs; charts via a native declarative API (addNativeChart).
• Streaming auto-filter: filtered million-row exports no longer degrade — the filter is injected into the saved container.

Styles applied before their rows are written are inlined into the stream, so the usual "style header → bulk write" report keeps constant memory and full write speed. See COMPAT.md for the precise matrix and documented divergences. Reproduce the numbers with make bench.