[kemo]

This is:

• a bugfix
• a new feature
• refactoring
• additional unit tests

Checklist:

• Changes are covered by unit tests
  • Changes are covered by existing unit tests
  • New unit tests have been added
• Code style is respected
• Commit message explains why the change is made (see https://github.com/erlang/otp/wiki/Writing-good-commit-messages)
• CHANGELOG.md contains a short summary of the change and a link to the pull request if applicable
• Documentation is updated as necessary

Why this change is needed?

PhpSpreadsheet holds every cell as an object (~1KB+ each), so writing large files exhausts memory and users switch to OpenSpout for big exports. The PSR-16 cell cache reduces resident memory but keeps O(n) storage and is slow; setUseDiskCaching() only helps the writer-side XML buffers. There was no way to write a large Xlsx file with memory independent of row count.

This PR adds an append-only streaming Xlsx writer with constant memory in row count, as an additive feature:

use PhpOffice\PhpSpreadsheet\Writer\Xlsx\Streaming\StreamingWriter;

$writer = new StreamingWriter('big.xlsx');
$bold = $writer->registerStyle(['font' => ['bold' => true]]);
$sheet = $writer->startSheet('Data');
$sheet->appendRow(['Name', 'Amount', 'Date'], $bold);
$sheet->appendRow(['Widget', 12.5, new DateTimeImmutable('2026-01-01')]);
$writer->close();

How it works

• appendRow() serializes each row immediately to a php://temp/maxmemory stream via XMLWriter; strings are written as inline strings, so no shared-strings table accumulates.
• All workbook-level parts (ContentTypes, rels, docProps, theme, styles, workbook) are produced by the existing Writer\Xlsx part writers running against an internal shell Spreadsheet that carries only sheet names and registered styles — no duplicated XML logic, and no changes to any existing class.
• close() streams each finished sheet into the archive with ZipStream::addFileFromStream().

Benchmark (200,000 rows × 8 mixed columns, medians of 3 isolated processes)

ZipStream 3.1.1, Apple Silicon (Darwin 23.1.0 arm64).

PHP 8.2.27

Engine	Wall time	Peak memory	File size
Standard Spreadsheet + Writer\Xlsx	31.43 s	1,091.06 MB	9,173,721 bytes
StreamingWriter	5.09 s	42.27 MB	8,118,639 bytes
Ratio	~6.2x faster	~25.8x less memory	~1.13x smaller

PHP 8.5.10

Engine	Wall time	Peak memory	File size
Standard Spreadsheet + Writer\Xlsx	33.83 s	1,093.06 MB	9,173,722 bytes
StreamingWriter	5.28 s	42.27 MB	8,118,639 bytes
Ratio	~6.4x faster	~25.9x less memory	~1.13x smaller

Peak memory is flat past ~100k rows: 100k and 200k rows both peak at ~42 MB inside the writer (most of that is ZipStream's fixed 16 MB read block, not row data). The benchmark script is committed under tests/Benchmark/ (plain PHP, outside the phpunit test path) with the recorded results in its README, so the numbers are reproducible: php -d memory_limit=4G tests/Benchmark/bench.php <standard|streaming> [rows].

Scope

Supported: scalars, formulas (written without cached values, fullCalcOnLoad set), DateTimeInterface (default date format unless styled), per-row and per-cell styles via registerStyle()/StreamedCell, column widths, freeze pane, autofilter over the written range, multiple sequential sheets.

Not supported (documented): random access, reading back, merged cells, charts, drawings, comments, conditional formatting, hyperlinks, rich text. One caveat is documented explicitly: PhpSpreadsheet's own reader returns inline-string cells as RichText objects; Excel and other consumers read them as plain strings.

Testing

• 30 unit tests / 80 assertions: round-trips through the real Reader\Xlsx for every value type, style, and sheet feature; lifecycle guard tests (append after close, stale sheets, invalid widths, unsupported forced types, failure cleanup); a corrupted-sheet guard (a failed appendRow() poisons the sheet so close() throws instead of writing malformed XML); and a memory test asserting the peak at 200k rows does not exceed the peak at 100k rows.
• Full suite, PHPStan (level 10, no new errors), PHP-CS-Fixer, and PHPCS are clean.
• New docs page: docs/topics/streaming-writer.md.

[oleibman]

I do not see where close marks the workbook for full calculation. Please enlighten me.

[kemo]

Comment* updated 729d1b0

[oleibman]

I still don't see where that attribute is set in your code. Please explain.

More to the point, 'forceFullCalc` is a very dangerous option. Please see PR #4271 for details on its unexpected side effects, and why we would not want to make it an "automatic" choice.