shuchkin/simplexlsx for Reading Excel XLSx Files in PHP

SimpleXLSX use cases and supported workbook scope

SimpleXLSX addresses a specific PHP integration problem: retrieving data and metadata from Excel 2007 XLSx workbooks. It is for applications that receive a workbook and need its contents as PHP arrays, generators, HTML, CSV, or detailed cell records. It is not presented as an Excel editor, formula calculation engine, or workbook generator.

The package supports PHP 5.5 and later. According to the README, no additional PHP extensions are required because the class uses internal unzip functionality and the standard SimpleXML parser. That makes it relevant to applications that need an XLSx reader without adopting a broader spreadsheet suite.

The basic API returns worksheet values as a two-dimensional array. Extended methods return cell metadata that includes values, formulas, links, styles, generated CSS, dimensions, hidden state, and comments. A simple data importer can use `rows()`, while a reporting or preview feature can use `rowsEx()` when formatting or workbook structure matters.

Its scope remains narrow. The repository describes a reader, not a complete spreadsheet platform. The README separately points to SimpleXLSXGen for writing XLSx files and to SimpleXLS for reading the older Microsoft Excel 97 format. Applications needing those capabilities should not assume this reader provides them.

SimpleXLSX parsing and worksheet data flow

The documented parsing entry points are `SimpleXLSX::parse()`, `SimpleXLSX::parseFile()`, and `SimpleXLSX::parseData()`. Each returns a `SimpleXLSX` instance or `false`. An application therefore needs to check the result before requesting worksheet rows. The documented failure path uses `SimpleXLSX::parseError()` to retrieve the parse error.

Worksheet numbering begins at zero. `rows($worksheetIndex = 0, $limit = 0)` returns plain values, while `rowsEx($worksheetIndex = 0, $limit = 0)` provides richer cell information. The optional index chooses a worksheet, and the optional limit restricts the number of returned rows.

Workbook structure has separate access methods. `sheetsCount()` returns the number of worksheets, `sheetNames()` returns their names, and `sheetName($worksheetIndex)` returns a selected name. `sheetMeta($worksheetIndex = null)` returns worksheet metadata, with `null` requesting all sheets. The library also provides `isHiddenSheet($worksheetIndex)` and `dimension($worksheetIndex)`, which returns `[num_cols, num_rows]`.

For large workbooks, `readRows()` and `readRowsEx()` return generators. The README describes these methods as helpers for reading huge XLSx files. This differs from `rows()`, which materializes the result as an array. However, the documentation does not state a maximum workbook size, memory consumption, or ZIP-level streaming guarantee, so those details cannot be inferred from the generator return type.

Installing SimpleXLSX and reading book.xlsx

The README recommends Composer for installing the latest supported version. This command installs `shuchkin/simplexlsx` as a project dependency.

$ composer require shuchkin/simplexlsx

Without Composer, the README links to `src/SimpleXLSX.php` and describes it as a PHP 5.5+ class. It does not document a separate autoloader configuration for manual installation, so the application must load the class through its existing PHP setup.

The repository contains `examples/books.xlsx` and `examples/01-basic_usage.php`, while the README uses `book.xlsx` in its basic example. This code parses the workbook and prints its rows. If parsing fails, it prints the error instead.

use Shuchkin\SimpleXLSX;

if ( $xlsx = SimpleXLSX::parse('book.xlsx') ) {
    print_r( $xlsx->rows() );
} else {
    echo SimpleXLSX::parseError();
}

The documented output starts with column headings including `ISBN`, `title`, `author`, `publisher`, and `ctry`. A following row contains values for *The Hobbit*. This example is small, but it establishes the required control flow: parse the file, confirm that the returned object exists, and only then call `rows()`.

Selecting worksheets and inspecting cell metadata

Worksheet indexes begin at zero, so index `1` selects the second worksheet. The README shows this selection pattern:

$xlsx = SimpleXLSX::parse('book.xlsx');
// Sheet numeration started 0, we select second worksheet
foreach( $xlsx->rows(1) as $r) {
// ...
}

Sheet names and the active worksheet are also accessible. In this example, `sheetNames()` returns all worksheet names, while `sheetName($xlsx->activeSheet)` returns the selected active sheet name.

// Sheet numeration started 0

if ( $xlsx = SimpleXLSX::parse( 'xlsx/books.xlsx' ) ) {
    print_r( $xlsx->sheetNames() );
    print_r( $xlsx->sheetName( $xlsx->activeSheet ) );
}

`rowsEx()` retains more information than `rows()`. Its documented fields include `type`, `name`, `value`, `href`, `f`, `format`, `s`, `css`, `r`, `hidden`, `width`, `height`, and `comment`. The name identifies a cell such as `A1`, the formula appears in `f`, and links appear in `href`. The `s` field is a style index that can be looked up through `$xlsx->cellFormats[ $index ]`.

This richer representation is useful when visible values alone are insufficient. It also means an application may retain or inspect substantially more metadata than a conventional import requires. Projects with wide or highly formatted sheets should avoid requesting extended cell data when only row values are needed.

Large XLSx files, CSV conversion, and HTML output

The README documents `readRows()` as a generator for converting a large workbook to CSV. This example opens the destination, writes each row, closes the file, and prints the parse error if the workbook cannot be read.

if ( $xlsx = SimpleXLSX::parse( 'xlsx/books.xlsx' ) ) {
    $f = fopen('book.csv', 'wb');
    // fwrite($f, chr(0xEF) . chr(0xBB) . chr(0xBF)); // UTF-8 BOM
    foreach ( $xlsx->readRows() as $r ) {
        fputcsv($f, $r); // fputcsv($f, $r, ';', '"', "\\", "\r\n");
    }
    fclose($f);
} else {
    echo SimpleXLSX::parseError();
}

The optional BOM line can be uncommented for Excel-compatible CSV handling. The alternative `fputcsv()` arguments shown in the comment also demonstrate PHP-level control over the delimiter, enclosure, escape character, and line ending. These are not SimpleXLSX configuration settings.

For HTML output, `toHTML()` generates a basic table, while `toHTMLEx()` is intended for styled workbooks.

if ( $xlsx = SimpleXLSX::parse('book_styled.xlsx') ) {
    echo $xlsx->toHTMLEx();
}

The README does not document a configuration option for HTML escaping. Its manual table example inserts row values directly into `<td>` elements. Applications displaying uploaded workbooks should therefore inspect the installed implementation before sending `toHTML()` output directly to a page. The parser should not be treated as a general-purpose output-encoding layer.

SimpleXLSX limitations, alternatives, and maintenance

The main limitation is scope. SimpleXLSX reads existing XLSx workbooks, but the README points to separate projects for adjacent work. SimpleXLSXGen writes XLSx files, while SimpleXLS reads old Microsoft Excel 97 files. This distinction is important because a reader for XLSx does not imply support for XLS, workbook generation, formula calculation, or in-place editing.

The documented methods do not provide APIs for creating cells, modifying formulas, saving a changed workbook, or evaluating formulas. `rowsEx()` exposes a formula in the `f` field, but that is data extraction, not a documented calculation service. Applications that preserve workbook behavior after editing need a spreadsheet library built around that workflow.

The repository is not archived, and its last push was on 2026-09-10. There are no GitHub releases listed. That means there is recent repository activity, but no documented release cadence in the release record. Composer is described as installing the latest supported version. Direct users are instead directed to `src/SimpleXLSX.php` on the `master` branch, and the README does not describe a manual versioning or rollback procedure.

SimpleXLSX uses the MIT license. The repository contains `license.md`, and distribution or use must follow that file's terms. The practical upgrade path is Composer for versioned dependency management. Manual users have fewer documented controls because the README does not explain how to select historical `master` revisions.

Editorial conclusion

shuchkin/simplexlsx suits PHP applications that need to read existing Excel XLSx workbooks without additional PHP extensions, especially when worksheet selection, cell metadata, or generator-based iteration matters. It does not fit code that must write spreadsheets, process legacy XLS files, calculate formulas, or retain a full Excel editing model. Before adoption, verify how your installed version handles the workbook structures you use, confirm the PHP 5.5+ requirement, and inspect whether `toHTML()` escapes cell content before displaying uploaded files.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. shuchkin/simplexlsx on GitHub