Readers Overview

Overview

PhpSpreadsheet provides a comprehensive set of readers for loading various spreadsheet file formats. All readers implement the IReader interface and extend the BaseReader class, providing a consistent API for loading spreadsheet data.

Supported Formats

PhpSpreadsheet includes readers for the following formats:

Xlsx - Excel 2007+ (.xlsx) files
Xls - Excel 97-2003 (.xls) files
Ods - OpenDocument Spreadsheet (.ods) files
Csv - Comma-separated values (.csv) files
Html - HTML table files
Slk - SYLK (Symbolic Link) files
Gnumeric - Gnumeric spreadsheet files
Xml - Excel 2003 XML files

IReader Interface

All readers implement the IReader interface located at PhpOffice\PhpSpreadsheet\Reader\IReader.

Core Methods

load()

Loads a spreadsheet from a file.

public function load(string $filename, int $flags = 0): Spreadsheet;

filename

string

required

The path to the file to load

flags

int

default:"0"

Optional flags to control loading behavior:

IReader::LOAD_WITH_CHARTS - Load any charts defined in the file
IReader::READ_DATA_ONLY - Read only data, not formatting
IReader::IGNORE_EMPTY_CELLS - Don’t read empty cells
IReader::IGNORE_ROWS_WITH_NO_CELLS - Don’t load rows with no cells
IReader::ALLOW_EXTERNAL_IMAGES - Allow loading external images (use with caution)
IReader::DONT_ALLOW_EXTERNAL_IMAGES - Prevent loading external images
IReader::CREATE_BLANK_SHEET_IF_NONE_READ - Create blank sheet if no sheets are read

canRead()

Checks if the reader can read a specific file.

public function canRead(string $filename): bool;

filename

string

required

The path to the file to check

Configuration Methods

setReadDataOnly()

Configures the reader to read only cell data values, ignoring formatting.

public function setReadDataOnly(bool $readDataOnly): self;

readDataOnly

bool

required

Set to true to read only data values, false (default) to read data and formatting

setReadEmptyCells()

Configures whether to read empty cells.

public function setReadEmptyCells(bool $readEmptyCells): self;

readEmptyCells

bool

required

Set to true (default) to read all cells, false to ignore empty cells

setIncludeCharts()

Configures whether to load charts from the file.

public function setIncludeCharts(bool $includeCharts): self;

includeCharts

bool

required

Set to true to load charts, false (default) to ignore charts

setLoadSheetsOnly()

Specifies which worksheets to load.

public function setLoadSheetsOnly(string|array|null $value): self;

value

string|array|null

required

Array of worksheet names to load, a single worksheet name string, or null to load all worksheets

setReadFilter()

Sets a read filter to selectively load cells.

public function setReadFilter(IReadFilter $readFilter): self;

readFilter

IReadFilter

required

An object implementing the IReadFilter interface

BaseReader Class

The BaseReader abstract class (PhpOffice\PhpSpreadsheet\Reader\BaseReader) provides the common implementation for all readers.

Additional Methods

listWorksheetInfo()

Returns information about worksheets without loading the entire file.

public function listWorksheetInfo(string $filename): array;

Returns an array with worksheet information including:

worksheetName - Name of the worksheet
lastColumnLetter - Last column letter
lastColumnIndex - Last column index
totalRows - Total number of rows
totalColumns - Total number of columns
sheetState - Sheet visibility state

listWorksheetNames()

Returns worksheet names without loading the entire file.

public function listWorksheetNames(string $filename): array;

setValueBinder()

Sets a custom value binder for cell values.

public function setValueBinder(?IValueBinder $valueBinder): self;

IReadFilter Interface

The IReadFilter interface allows you to selectively load cells from a spreadsheet, which is useful for reading large files efficiently.

namespace PhpOffice\PhpSpreadsheet\Reader;

interface IReadFilter
{
    public function readCell(string $columnAddress, int $row, string $worksheetName = ''): bool;
}

Example: Custom Read Filter

use PhpOffice\PhpSpreadsheet\Reader\IReadFilter;
use PhpOffice\PhpSpreadsheet\Reader\Xlsx;

class MyReadFilter implements IReadFilter
{
    public function readCell(string $columnAddress, int $row, string $worksheetName = ''): bool
    {
        // Read rows 1 to 10 and columns A to E only
        if ($row >= 1 && $row <= 10) {
            if (in_array($columnAddress, range('A', 'E'))) {
                return true;
            }
        }
        return false;
    }
}

$reader = new Xlsx();
$reader->setReadFilter(new MyReadFilter());
$spreadsheet = $reader->load('data.xlsx');

Common Usage Patterns

Basic File Loading

use PhpOffice\PhpSpreadsheet\Reader\Xlsx;

$reader = new Xlsx();
$spreadsheet = $reader->load('data.xlsx');

Using IOFactory

The IOFactory can automatically detect the file format:

use PhpOffice\PhpSpreadsheet\IOFactory;

// Automatically detect format
$spreadsheet = IOFactory::load('data.xlsx');

// Or create a specific reader
$reader = IOFactory::createReader('Xlsx');
$spreadsheet = $reader->load('data.xlsx');

Reading Data Only (No Formatting)

use PhpOffice\PhpSpreadsheet\Reader\Xlsx;

$reader = new Xlsx();
$reader->setReadDataOnly(true);
$spreadsheet = $reader->load('data.xlsx');

Loading Specific Worksheets

use PhpOffice\PhpSpreadsheet\Reader\Xlsx;

$reader = new Xlsx();
$reader->setLoadSheetsOnly(['Sheet1', 'Sheet3']);
$spreadsheet = $reader->load('data.xlsx');

Using Flags

use PhpOffice\PhpSpreadsheet\Reader\Xlsx;
use PhpOffice\PhpSpreadsheet\Reader\IReader;

$reader = new Xlsx();
$spreadsheet = $reader->load(
    'data.xlsx',
    IReader::READ_DATA_ONLY | IReader::IGNORE_EMPTY_CELLS
);

Getting Worksheet Information

use PhpOffice\PhpSpreadsheet\Reader\Xlsx;

$reader = new Xlsx();

// Get worksheet names only
$worksheetNames = $reader->listWorksheetNames('data.xlsx');

// Get detailed worksheet information
$worksheetInfo = $reader->listWorksheetInfo('data.xlsx');
foreach ($worksheetInfo as $info) {
    echo "Sheet: {$info['worksheetName']}\n";
    echo "Rows: {$info['totalRows']}, Columns: {$info['totalColumns']}\n";
}

Using Read Filters for Large Files

use PhpOffice\PhpSpreadsheet\Reader\IReadFilter;
use PhpOffice\PhpSpreadsheet\Reader\Xlsx;

class ChunkReadFilter implements IReadFilter
{
    private int $startRow;
    private int $endRow;

    public function __construct(int $startRow, int $chunkSize)
    {
        $this->startRow = $startRow;
        $this->endRow = $startRow + $chunkSize - 1;
    }

    public function readCell(string $columnAddress, int $row, string $worksheetName = ''): bool
    {
        return $row >= $this->startRow && $row <= $this->endRow;
    }
}

$reader = new Xlsx();
$reader->setReadDataOnly(true);

// Read file in chunks of 100 rows
for ($startRow = 1; $startRow <= 1000; $startRow += 100) {
    $chunkFilter = new ChunkReadFilter($startRow, 100);
    $reader->setReadFilter($chunkFilter);
    $spreadsheet = $reader->load('large_file.xlsx');
    
    // Process this chunk
    // ...
}

Security Considerations

External Images

Be cautious when using ALLOW_EXTERNAL_IMAGES flag or setAllowExternalImages(true), as this can expose your application to security risks if the spreadsheet contains malicious URLs.

XML Security

All XML-based readers (Xlsx, Ods, Xml, Html) use the XmlScanner security scanner to protect against XML External Entity (XXE) attacks.

Performance Tips

Use setReadDataOnly(true) if you don’t need formatting information
Use setReadEmptyCells(false) or IGNORE_EMPTY_CELLS flag to skip empty cells
Use read filters to load only the data you need from large files
Use setLoadSheetsOnly() to load specific worksheets
Consider chunked reading for very large files using read filters

Error Handling

use PhpOffice\PhpSpreadsheet\Reader\Exception as ReaderException;
use PhpOffice\PhpSpreadsheet\Reader\Xlsx;

$reader = new Xlsx();

try {
    if (!$reader->canRead('data.xlsx')) {
        throw new Exception('File is not a valid XLSX file');
    }
    
    $spreadsheet = $reader->load('data.xlsx');
} catch (ReaderException $e) {
    echo 'Error loading file: ' . $e->getMessage();
}

Core Classes

Readers

Writers

Calculation

Styling

Charts & Graphics

Overview

Supported Formats

IReader Interface

Core Methods

load()

canRead()

Configuration Methods

setReadDataOnly()

setReadEmptyCells()

setIncludeCharts()

setLoadSheetsOnly()

setReadFilter()

BaseReader Class

Additional Methods

listWorksheetInfo()

listWorksheetNames()

setValueBinder()

IReadFilter Interface

Example: Custom Read Filter

Common Usage Patterns

Basic File Loading

Using IOFactory

Reading Data Only (No Formatting)

Loading Specific Worksheets

Using Flags

Getting Worksheet Information

Using Read Filters for Large Files

Security Considerations

External Images

XML Security

Performance Tips

Error Handling

Build docs developers (and LLMs) love

Core Classes

Readers

Writers

Calculation

Styling

Charts & Graphics

​Overview

​Supported Formats

​IReader Interface

​Core Methods

​load()

​canRead()

​Configuration Methods

​setReadDataOnly()

​setReadEmptyCells()

​setIncludeCharts()

​setLoadSheetsOnly()

​setReadFilter()

​BaseReader Class

​Additional Methods

​listWorksheetInfo()

​listWorksheetNames()

​setValueBinder()

​IReadFilter Interface

​Example: Custom Read Filter

​Common Usage Patterns

​Basic File Loading

​Using IOFactory

​Reading Data Only (No Formatting)

​Loading Specific Worksheets

​Using Flags

​Getting Worksheet Information

​Using Read Filters for Large Files

​Security Considerations

​External Images

​XML Security

​Performance Tips

​Error Handling

​Related Documentation

Build docs developers (and LLMs) love

Overview

Supported Formats

IReader Interface

Core Methods

load()

canRead()

Configuration Methods

setReadDataOnly()

setReadEmptyCells()

setIncludeCharts()

setLoadSheetsOnly()

setReadFilter()

BaseReader Class

Additional Methods

listWorksheetInfo()

listWorksheetNames()

setValueBinder()

IReadFilter Interface

Example: Custom Read Filter

Common Usage Patterns

Basic File Loading

Using IOFactory

Reading Data Only (No Formatting)

Loading Specific Worksheets

Using Flags

Getting Worksheet Information

Using Read Filters for Large Files

Security Considerations

External Images

XML Security

Performance Tips

Error Handling

Related Documentation