Download the PHP package lekoala/baresheet without Composer

Baresheet

Fast, zero-dependency CSV, XLSX, and ODS reader/writer for PHP.

Requirements

• PHP 8.1+
• ext-mbstring (Required for all formats)

Format Specific (Required for XLSX/ODS)

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

Optional

• ext-iconv (Required only for CSV BOM transcoding)
• maennchen/zipstream-php (Required only for streaming XLSX/ODS output)

Installation

Quick Start

Direct Reader/Writer Usage

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

Features

CSV

• Auto delimiter detection — analyzes a sample to pick the best separator (default: auto)
• BOM handling — detects and natively transcodes UTF-8/16/32 BOM sequences on the fly via stream filters
• Formula injection protection — escapeFormulas: true (opt-in security flag, see Security section)
• RFC 4180 compliant — handles enclosures, double-quote escaping, and CRLF (\r\n) line endings by default for maximum interoperability.
• Column Selection — Efficiently select, reorder, and alias columns during read.
• Stream reading — readStream() for reading from any PHP resource

XLSX

• Blazing fast reading — optimized XMLReader with direct zip:// streaming (2x faster than SimpleXLSX)
• Data offset & Empty line skipping — safely skip arbitrary leading rows or completely empty lines
• Extreme memory efficiency — unified 0.63MB footprint regardless of file size
• Column Selection — Skip XML parsing for unselected cells for massive performance gains.
• Shared string table — opt-in de-duplication for smaller files (default: false for speed)
• Auto column widths — opt-in automatic column sizing (default: false for speed)
• DateTime support — pass DateTimeInterface objects directly, seamlessly handles 1900/1904 calendar systems
• Freeze Pane & Autofilter — simple options for improved sheet usability
• Document properties — set creator, title, subject, keywords, etc. via meta

ODS

• Streaming reader — handles large files with minimal 0.63MB memory usage
• Data offset & Empty line skipping — safely skip arbitrary leading rows or completely empty lines
• Column Selection — Skip XML parsing for unselected cells for significant performance gains.
• Zero-dependency — uses native ZipArchive + XMLReader
• DateTime support — dates stored accurately in ISO 8601
• Document properties — set creator and title via meta
• Sheet selection — read specific sheets by name or index

Options

There are two ways to pass options:

1. Directly on instances:

2. Options object (works on any method, including the Baresheet facade). The constructor provides full IDE autocomplete:

Required Columns Validation

Validate that input files contain expected columns before processing. This catches malformed files early, avoiding wasted cycles parsing invalid data.

The validation occurs immediately after reading the header row and throws a descriptive exception listing the missing columns:

Works with all reader formats (CSV, XLSX, ODS) and the Baresheet facade.

Column Selection

Select and reorder specific columns when reading. This is useful for wide files where you only need a subset of columns, or when you need columns in a specific order. Selected columns must exist in the file headers (they are implicitly required).

Reordering Columns

Column selection also allows reordering:

Plain Mode with Column Selection

When using assoc: false, provide explicit headers and receive values in plain arrays:

Working with Headerless Files

When reading files without header rows, you can inject column names using the headers option. This enables column selection and associative output even for plain data files:

This works with all reader formats (CSV, XLSX, ODS) and is useful when:

• Processing legacy data exports without headers
• Working with fixed-format data feeds
• Converting plain arrays to structured data

Column selection provides dramatic performance improvements for XLSX and ODS files by skipping XML parsing for unselected cells. For CSV, it provides a zero-overhead "direct indexing" fast path that avoids intermediate array allocations.

[!TIP] The CSV "Practical Ceiling": While CSV reading cannot skip bytes (as fgetcsv must tokenize every field to track quotes/delimiters), Baresheet uses a direct numeric indexing map. This avoids creating a full associative array for the entire row before subsetting, effectively reaching the maximum performance possible for column selection in PHP.

Error Handling

Missing columns throw immediately:

Data Transformation

Baresheet preserves raw cell values by design. For cleaning, casting, or filtering, use the Transform class — generator-based pipelines that compose with readers and writers without loading data into memory.

Streaming Output

For large files, streaming avoids writing a temporary file to disk. Baresheet streams output() by default.

However, keep in mind that streaming changes how data is sent to the browser. Because the total file size is unknown before the transfer starts, the server cannot send a Content-Length header. This means the browser download will not display a progress bar or an estimated time of completion.

To bypass streaming and force buffering, use stream: false with output(). Baresheet will buffer the file (either in memory for CSV, or via a temporary zip file for XLSX/ODS) to precisely calculate and send the Content-Length header along with it.

Note on XLSX/ODS: Streaming requires an optional dependency. Install it with:

If the zipstream-php dependency is missing, Baresheet will seamlessly and automatically fall back to buffered output.

PSR-7 / Response Objects (Symfony, Laravel)

To avoid breaking the flow of your application or sending explicit header() calls directly, you should create a Response object when applicable in your framework.

Use the writeStream() method to generate the spreadsheet as a memory-capped php://temp stream resource, and feed it into your Response class:

Symfony / Laravel (StreamedResponse)

PSR-7 (Guzzle, Nyholm, etc.)

Performance

Baresheet is explicitly engineered to minimize server resource footprint.

The XLSX and ODS readers use an optimized XMLReader approach that opens zip:// streams directly. This avoids any temporary file extraction, cutting I/O overhead by 50% compared to standard zip extraction methods.

Here are the results extracting/writing 50,000 rows (4 columns) locally against other common industry standard libraries:

Reading (Parsing) 50,000 Rows

Reading CSV

Reading XLSX

Reading ODS

Writing 50,000 Rows

Writing CSV

Writing XLSX

Note: By default, Baresheet uses the fastest mode (shared strings and auto column width disabled). You can re-enable them via Options.

Writing ODS

Security Considerations

CSV Formula Injection

When writing CSV files, any cell beginning with =, +, -, or @ could be interpreted as a formula if the file is opened in spreadsheet software like Microsoft Excel. A maliciously crafted input could lead to execution of arbitrary functions or system commands on the user's local machine.

By default, Baresheet prioritizes data round-trip integrity. Attempting to automatically prefix formulas with a single quote (') to disable formula execution corrupts otherwise valid user inputs.

If you are exporting data to be consumed by clients opening the file in Excel, you must opt-in to the protection logic:

Selective Formula Escaping

For advanced use cases, escapeFormulas also accepts a callable that receives the cell value and column index, allowing you to selectively escape only specific columns:

Important: Heuristic detection of "malicious" formulas is fundamentally unreliable. Attackers can use CHAR() functions to build strings character-by-character, and new attack vectors emerge constantly. The library takes a conservative approach: blanket escaping by default when enabled, or user-controlled selective escaping via callback. For maximum security with user-generated content, prefer XLSX format, which has explicit cell type metadata and is immune to formula injection.

License

MIT