Download the PHP package wilsonglasser/spout without Composer

SpoutX

SpoutX is a fast, low-memory PHP library to read and write XLSX spreadsheet files.

It is a modernized, XLSX-only fork of the (discontinued) Spout library, rebuilt for PHP 8.4+. Unlike Spout and its successor OpenSpout, SpoutX keeps a mutable API on purpose — the reason this fork exists is to let you build up cells, rows and styles imperatively — while adding first-class support for merged cells, comments, formulas with precomputed values, column dimensions/auto-size, auto filters, row heights and custom number formats.

• XLSX only — CSV and ODS support has been removed to keep the library small and focused.
• PHP 8.4+ — declare(strict_types=1) everywhere, backed enums, typed properties, constructor promotion.
• Mutable by design — entities (Cell, Row, Style, …) are built and mutated in place; no readonly/withX ceremony.
• Streaming & scalable — rows are written to disk as you go, so very large files stay within a small memory footprint.

Requirements

• PHP >= 8.4
• Extensions: ext-dom, ext-mbstring, ext-xmlreader, ext-zip

Installation

Root namespace is SpoutX\ (no vendor prefix).

Quick start — writing

Quick start — reading

Reader options (call before open()):

Cells and types

A Cell wraps a value; its type is detected automatically and exposed as the CellType enum.

CellType cases: Numeric, String, Formula, Empty, Boolean, Date, Error.

Supported values: string, int, float, bool, \DateTime/\DateInterval, ''/null (empty), and formula strings starting with =.

Styling

Build styles with StyleBuilder and apply them per row (via the row/factory) or per cell.

StyleBuilder methods: setFontBold(), setFontItalic(), setFontUnderline(), setFontStrikethrough(), setFontSize(int), setFontName(string), setFontColor(string), setBackgroundColor(string), setShouldWrapText(bool = true), setShrinkToFit(bool = false), setHorizontalAlign(CellAlignment), setVerticalAlign(CellVerticalAlignment), setBorder(Border), setFormat(string), setNumberFormat(NumberFormat), setRowHeight(float).

Alignment enums

• CellAlignment (horizontal): Left, Right, Center, General
• CellVerticalAlignment: Top, Center, Bottom

Colors

Named constants (Color::BLACK, WHITE, RED, DARK_RED, ORANGE, YELLOW, LIGHT_GREEN, GREEN, LIGHT_BLUE, BLUE, DARK_BLUE, PURPLE) or build your own:

Borders

• BorderWidth: Thin, Medium, Thick
• BorderStyle: None, Solid, Dashed, Dotted, Double
• Sides: setBorderTop(), setBorderRight(), setBorderBottom(), setBorderLeft()

Row height

Number format

Extra features (why this fork exists)

These are only available in the XLSX writer. Get the current sheet with $writer->getCurrentSheet().

Merge cells

Auto filter

Column dimensions (width / auto-size / visibility)

Comments

Comment also exposes setWidth(), setHeight(), setMarginLeft(), setMarginTop(), setVisible() and setStyle().

Formulas with a precomputed value

SpoutX does not evaluate formulas — you supply the value Excel should display until it recalculates.

Sheets

Default row style & writer options

Page setup, views, hyperlinks & data validation

These XLSX features were ported from OpenSpout v5 and adapted to SpoutX's mutable, per-sheet model. They are configured on the sheet ($writer->getCurrentSheet()).

Print page setup

Freeze panes / sheet views

Hyperlinks

Data validation (dropdowns and constraints)

Protection, visibility, properties & rich text

Sheet & workbook protection (locks editing, optionally password-guarded)

Tab visibility (independent of protection). lockStructure above is what keeps a hidden tab hidden.

Document properties

Macros (.xlsm): embed the xl/vbaProject.bin of an .xlsm saved by Excel (it is a zip). The VBA project's workbook module must match the workbook code name (ThisWorkbook by default; a pt-BR Excel names it EstaPastaDeTrabalho) and its sheet modules the sheets' code names (SheetN by default). Save with .xlsm.

Rich text (multiple formats in one cell)

Reading merge cells

Migrating from Box\Spout / Spout

• Namespace changed from Box\Spout\… to SpoutX\….
• Package is wilsonglasser/spoutx; minimum PHP is 8.4.
• CSV and ODS are gone — use Type::XLSX only.
• Several constant sets are now backed enums (breaking, but type-safe):
  • Style::ALIGN_* → CellAlignment (horizontal) and CellVerticalAlignment (vertical).
  • Border name/style/width strings → BorderName / BorderStyle / BorderWidth.
  • Cell type ints → CellType.
  • So setHorizontalAlign(Style::ALIGN_RIGHT) becomes setHorizontalAlign(CellAlignment::Right), and setBorderTop($color, 'thin', 'solid') becomes setBorderTop($color, BorderWidth::Thin, BorderStyle::Solid).
• The API is still mutable — new Cell(...), ->setValue(), ->setStyle(), builder setters returning $this, etc., all behave as before.

Development

The dev environment runs in Docker (PHP 8.4 + ext-zip). Common tasks are wrapped in the Makefile:

The test suite includes a golden-file characterization test (tests/SpoutX/CharacterizationTest.php) that locks the exact XLSX XML output, plus a write→read roundtrip and a feature test covering the extras above.

License

Licensed under the Apache License, Version 2.0. Originally Copyright Box, Inc.; fork maintained by Wilson Glasser.