Download the PHP package kolay/xlsx-stream without Composer

Kolay XLSX Stream

High-performance XLSX streaming writer for Laravel with zero disk I/O and direct S3 support. Perfect for exporting millions of rows without memory issues.

Why This Package?

The Problem with Existing Solutions

Most PHP Excel libraries (PHPSpreadsheet, Spout, Laravel Excel) have critical limitations:

• Memory Issues: Load entire documents in RAM (unusable for large files)
• Disk I/O: Write temporary files then upload to S3 (2x I/O, slow)
• No True Streaming: Can't stream directly to S3

Our Solution

• Zero Disk I/O: Direct streaming to S3 using multipart upload
• Constant Memory: O(1) memory usage - only 32MB buffer regardless of file size
• Blazing Fast: 2-3x faster than alternatives
• Production Tested: Successfully exported 4.65 million rows (500MB+ files)

Performance Comparison

Latest Benchmark — v2.2.2 (May 2026)

Re-measured on an Apple Silicon laptop with PHP 8.2.28 and AWS SDK 3.379 against the same xlsx-test-package bucket in us-east-2. The workload is identical to the v1.x baseline below (8 columns, mixed types, compression level 1).

What changed since v1.x

• Local throughput is now ~15–25% faster than the v1.x baseline (1M rows: 210K rows/s vs 183K). The v2.0+ per-cell type detection added a small overhead at first (v2.0 was about 5% slower than v1.x), but v2.2.2 fixed a long-standing bug in the XML escape fast path — the strpbrk needle was a single-quoted literal so \xNN escapes were embedded as the characters \, x, 0..9, A..F instead of as actual control bytes. The fix shrank the needle from 129 to 36 chars and per-cell sanitization got ~3.5× cheaper as a side effect.
• S3 throughput is up 2.5–3× over v1.x for any workload above 50K rows (1M: 107K rows/s vs 43K, 4.5M: 130K rows/s vs 46K). Drivers: AWS SDK 3.379+, faster measurement-machine network, and a smaller share from the per-row hot-path improvement.
• Memory is unchanged — local stays at 0–2 MB constant, S3 keeps the same sawtooth pattern as the buffer fills and flushes per part.

Original Benchmark — v1.x (September 2025)

Kept here for historical context. Different machine and PHP version, so direct cell-by-cell deltas reflect environment variance as well as code changes.

Note: Tests with 1M+ rows automatically create multiple sheets (Excel limit: 1,048,576 rows per sheet)
Note: ± values in S3 Memory column indicate memory fluctuation during streaming due to periodic part uploads

Understanding Memory Behavior

Local File System

• True O(1) Memory: Constant memory usage regardless of file size
• No Growth: Memory stays at 0-2MB even for millions of rows
• Speed: 180,000+ rows/second consistently

S3 Streaming Memory Fluctuation

The ± values in S3 memory represent normal memory fluctuation during streaming:

1. Buffer Accumulation Phase (↑ Memory Growth)

   • Data is compressed and buffered until reaching 32MB
   • Memory grows gradually as buffer fills

2. Part Upload Phase (↓ Memory Drop)

   • When buffer reaches 32MB, it's uploaded to S3
   • After upload, memory drops back to baseline
   • This creates the characteristic sawtooth pattern
3. Example: 1M Rows Test
   • Average memory: 40MB
   • Fluctuation: ±38MB
   • Pattern: Memory oscillates between ~2MB (after upload) and ~78MB (before upload)
   • This is completely normal and expected behavior

Performance Highlights (v2.2.2, May 2026)

• Local File System: ~190,000–215,000 rows/second with true O(1) memory
• S3 Streaming: 105,000–130,000 rows/second above 1M rows (2.5–3× the v1.x baseline)
• Memory Efficiency: Local uses <2 MB, S3 averages 40 MB per million rows
• Multi-sheet Support: Automatic sheet creation at Excel's 1,048,576 row limit
• Production Ready: Successfully tested with 4.5 million rows

Comparison with Other Libraries

Requirements

• PHP 8.1+
• Laravel 10, 11, 12 or 13
• AWS SDK (only if using S3 streaming)

Upgrading from v1.x? See UPGRADE.md for the v2.0 migration guide.

Installation

Publish Configuration (Optional)

Quick Start

Basic Usage - Local File

Direct S3 Streaming (Zero Disk I/O)

Laravel Job Example

Advanced Features

Laravel Storage Disk Integration (v2.1+)

Skip the manual S3Client setup — forDisk() reads everything from config('filesystems.disks.{$disk}'):

Streaming from Eloquent with lazy() (v2.1+)

writeRows() accepts any iterable — pass an Eloquent lazy() cursor for constant-memory streaming over millions of rows:

Generators work too:

Progress Reporting for Queue Jobs (v2.1+)

Register a callback that fires every N rows with (rows, bytes). Zero overhead when not used:

Note on $bytes — the byte counter only advances when zlib emits compressed output. With small datasets (or when setBufferFlushInterval() is large relative to setProgressInterval()), several events in a row may report the same byte count between flushes. The row counter is always exact; if you need accurate streamed-byte progress on small files, lower setBufferFlushInterval() below your progress interval.

Supported Cell Data Types

The writer infers the right Excel cell type from each PHP value:

Header & Column Styling (v2.2+)

A small set of opt-in styling APIs that costs ~2-3% throughput and adds ~3% to the file size. Skip them and the writer takes the v1.x-equivalent hot path.

Available format presets: date, datetime, datetime_iso, time, integer, decimal, percent, currency_try, currency_usd, currency_eur, currency_gbp. Pass any other string to use a raw Excel format code (e.g. 0.000, #,##0.00 "kg").

setAutoColumnWidth() derives a width from the header text length but also respects a per-format minimum so a currency_try column with the header Salary won't render as ####. Override per column with setColumnWidths([1 => 8, 2 => 30]) when you want exact control.

Manual Multi-Sheet Workbooks (v2.2+)

newSheet($name, $headers = null) carves a workbook into named domain sheets — orthogonal to the auto-split fallback at 1,048,576 rows.

clearColumnFormats() is the convenient way to drop the previous sheet's per-column registrations before starting a new one with a different column layout.

Multi-Sheet Support (Automatic)

The writer automatically creates new sheets when reaching Excel's row limit (1,048,576 rows):

Performance Tuning

Custom S3 Parameters

Error Handling

Configuration

Published configuration file (config/xlsx-stream.php):

How It Works

The Architecture

The Magic Behind Zero Disk I/O

1. Binary XLSX Generation

   • XLSX files are ZIP archives containing XML files
   • We generate ZIP structure directly in memory
   • No intermediate files or DOM tree building

2. Streaming Compression

   • Data is compressed using PHP's deflate_add() in chunks
   • Each row is immediately compressed and streamed
   • No need to store uncompressed data

3. Smart Buffering

   • Configurable row buffer (default 10,000 rows)
   • Flushes periodically to maintain streaming
   • Prevents memory accumulation
4. S3 Multipart Upload
   • Direct streaming to S3 using multipart upload
   • 32MB parts uploaded as they're ready
   • No local file required at any point

Memory Efficiency Explained

Local Files: True O(1) Memory

S3 Streaming: Near O(1) with Controlled Growth

Why Memory Fluctuates in S3

The sawtooth memory pattern in S3 streaming is by design:

Each peak represents a full 32MB buffer ready for upload. After upload, memory drops as the buffer is cleared. This is optimal for streaming large files.

Real-World Performance

Production Test Results (4.5 Million Rows)

Our production systems successfully export massive datasets daily:

Key Performance Metrics

Speed

• Local Files: 180,000+ rows/second sustained
• S3 Streaming: 30,000-50,000 rows/second
• Network Impact: S3 speed varies with network latency and bandwidth

Memory Usage

• Local Files: True O(1) - constant 0-2MB regardless of size
• S3 Streaming: Averages 40MB per million rows
• Fluctuation: Normal sawtooth pattern during S3 uploads

Scalability

• ✅ 100 rows: Instant (< 0.01s local, ~1s S3)
• ✅ 1 Million rows: 5.5 seconds local, 23 seconds S3
• ✅ 4.5 Million rows: 97 seconds S3 with automatic multi-sheet
• ✅ Memory stable: No memory leaks, predictable usage
• ✅ Production proven: Running in production since 2025

Use Cases

Perfect for:

• Large data exports (millions of rows)
• Memory-constrained environments
• Kubernetes/Docker with small pods
• AWS Lambda functions
• Real-time streaming exports
• Multi-tenant SaaS applications

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Testing

License

The MIT License (MIT). Please see License File for more information.

Credits

• Turgut Ahmet

Support

For issues and questions, please use the GitHub issue tracker.