Download the PHP package lekoala/baresheet without Composer

Baresheet

Fast, lightweight CSV, XLSX, and ODS reader/writer for PHP with no runtime Composer dependencies.

Requirements

• PHP 8.1.2+
• ext-mbstring (required for all formats)

Format-specific (XLSX/ODS)

• ext-zip
• ext-zlib
• ext-xmlreader, ext-simplexml, ext-libxml (standard XML extensions, usually bundled together)

Optional

• ext-iconv (required only for CSV BOM transcoding)

Installation

Quick Start

That's it. The Baresheet facade always creates a fresh reader/writer, applies the options, and reads/writes once.

Why Baresheet?

• Streaming by default — reads and writes (including browser output()) are streamed, so PHP memory stays flat regardless of file size.
• Low memory — ~0.15 MB for CSV, ~0.7 MB peak reading or ~1.3 MB writing 50,000 XLSX rows (see Performance).
• No runtime Composer dependencies — only PHP core extensions; XLSX/ODS packaging uses an internal ZIP writer.
• Pragmatic headers — required columns, selection, aliases, injected and hierarchical headers, header discovery, normalization, and strict mode (docs/headers.md).
• Native values — in XLSX/ODS, numbers, booleans, and dates come back as real PHP types, not strings; CSV is textual by nature (Native values).

Core API

Baresheet facade

Format is detected from the extension (or from the content when a string is passed):

Direct readers/writers

Concrete classes allow setting properties directly or passing an Options object to the constructor:

Options

Readers and writers are configured objects: you set their options once, then read/write as many times as you like with that same configuration. Use named arguments when constructing Options — the parameter list is large and its order is not part of the API contract.

readFile(), readString(), writeFile(), etc. take no Options argument — they read/write using whatever configuration the reader/writer instance currently holds. This avoids ambiguity about whether a per-call option leaks into subsequent calls: the instance's configuration is its state. The Baresheet facade keeps the convenient one-shot form, since it always creates a fresh reader/writer internally, applies the options to it, then reads/writes once.

Options

Per-column geometry and formats (XLSX)

columnWidths and columnFormats are keyed by 0-based column index or Excel letter (A, C…, up to XFD). Explicit widths override autoWidth for their column.

The format applies to every cell of the column regardless of its PHP type. '@' is special: it writes the cell as text even when inferNumericStrings would otherwise make it numeric, which is what preserves a leading + or 0 (a number format alone would not). boldHeaders combines with the column format, so a header stays bold while adopting the column's format.

To store every non-empty value as spreadsheet text, use new Options(forceText: true). This applies to numbers, booleans, dates, times, and durations in XLSX and ODS output; null and '' remain empty cells. It is useful for identifier-heavy exports where spreadsheet type inference is not desirable. CSV output is already textual and therefore ignores this option.

Exceptions

Errors originating from a document or a Baresheet read/write operation are thrown as a LeKoala\Baresheet\Exception\BaresheetException (a RuntimeException), so catching that one type covers everything below. Bad API usage (invalid arguments, wrong call order) is left as native InvalidArgumentException/LogicException instead.

InvalidRowException exposes $row and $column when available, and MissingColumnException exposes the missing $columns list, for building precise error messages.

Native Values

Baresheet preserves the fundamental spreadsheet value kinds where PHP has a natural representation. In native mode (stringifyValues: false), the readers return:

The writers map PHP values to spreadsheet cells:

TimeValue and DurationValue are optional writer markers: a caller who never uses them never sees them. The readers never inject Baresheet objects into ordinary rows — DateTimeImmutable is standard PHP. See docs/value-types.md for timezone semantics, precision, and 32-bit notes.

CSV specifics

CSV has no native value types. Baresheet therefore uses conventional textual representations: booleans as 1/0 and null as an empty cell. Type distinctions that CSV cannot represent, such as false vs numeric 0 or null vs an empty string, are intentionally not preserved.

To make export output deterministic across PHP configurations, the CSV writer serializes scalars explicitly: bool as 1/0, finite floats with up to 17 significant digits (enough to round-trip a PHP float exactly, independent of the precision ini setting and of LC_NUMERIC), and null as an empty cell. This keeps false (0) distinct from null (empty). Non-finite floats (INF/NAN) are rejected with a WriteException, consistently with the XLSX/ODS writers.

With escapeFormulas, formula protection applies to strings and Stringable objects; numeric cells are never mistaken for formulas, so a negative float keeps its leading -.

When outputEncoding targets a non-UTF-8 encoding, the whole CSV stream — including separators and end-of-line bytes — is transcoded, also when a raw string BOM is provided (ext-iconv is required and bundled with PHP by default). Cells that are not valid UTF-8 or cannot be represented in the target encoding raise a WriteException instead of being silently substituted.

Advanced Usage

• Headers and column mapping — required columns, column selection, injected and hierarchical headers, aliases, header discovery, normalization, strict mode
• Streaming — output modes, failure semantics, ZIP64 and non-seekable output, PSR-7 / Symfony / Laravel responses
• Value types — timezone-free civil dates, microsecond precision, 32-bit PHP
• Security — CSV formula injection, XLSX sheet protection

Also in the package:

• Transform — generator-based pipelines for trimming, casting, filtering, and chunking without loading data into memory
• Spread::getSheetNames() — inspect the sheets of a workbook before choosing which to import

Performance

Indicative benchmarks — These numbers are intended to catch large performance regressions and highlight architectural differences. Absolute results vary by PHP version, hardware, filesystem and workload. Run php bin/bench-read.php / bin/bench-write.php / bin/bench-write-memory.php / bin/bench-xlsx-stream.php / bin/bench-ods-stream.php locally for results relevant to your environment.

Environment: PHP 8.3.6, 64-bit, 50,000 rows × 4 columns, median of 5 runs. Libraries are compared end-to-end through their public APIs; this is not a compressor-only comparison.

Reading 50,000 Rows

Writing 50,000 Rows

Memory is measured in an isolated subprocess via memory_get_peak_usage(), covering PHP-managed allocations only (not native allocations inside zlib or libzip). Baresheet's stream-based XMLReader never loads the entire worksheet document into PHP memory. See docs/streaming.md for write-memory details.

Security

CSV formula escaping is opt-in via escapeFormulas. See docs/security.md.

License

MIT