Csv Reader - PhpSpreadsheet

Overview

The Csv reader class loads comma-separated values (.csv) files. CSV is a simple text format for tabular data, widely supported by spreadsheet applications and databases.

Class Information

Namespace: PhpOffice\PhpSpreadsheet\Reader\Csv Extends: BaseReader Implements: IReader Source: src/PhpSpreadsheet/Reader/Csv.php:15

Basic Usage

Simple File Loading

use PhpOffice\PhpSpreadsheet\Reader\Csv;

$reader = new Csv();
$spreadsheet = $reader->load('data.csv');

// Access worksheet data
$sheet = $spreadsheet->getActiveSheet();
$data = $sheet->toArray();

Using IOFactory

use PhpOffice\PhpSpreadsheet\IOFactory;

// Auto-detect and load
$spreadsheet = IOFactory::load('data.csv');

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

Key Methods

__construct()

Creates a new Csv reader instance.

public function __construct();

Example:

$reader = new Csv();

canRead()

Checks if the file can be read by this reader.

public function canRead(string $filename): bool;

filename

string

required

Path to the file to check

Returns: bool - True if the file can be read Example:

$reader = new Csv();
if ($reader->canRead('data.csv')) {
    $spreadsheet = $reader->load('data.csv');
}

load()

Loads a spreadsheet from a CSV file.

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

filename

string

required

Path to the CSV file to load

flags

int

default:"0"

Optional flags (limited support for CSV format)

Returns: Spreadsheet object with a single worksheet Example:

$reader = new Csv();
$spreadsheet = $reader->load('data.csv');

loadIntoExisting()

Loads a CSV file into an existing spreadsheet as a new worksheet.

public function loadIntoExisting(string $filename, Spreadsheet $spreadsheet): Spreadsheet;

filename

string

required

Path to the CSV file to load

spreadsheet

Spreadsheet

required

Existing spreadsheet object to load into

Returns: The modified Spreadsheet object Example:

use PhpOffice\PhpSpreadsheet\Reader\Csv;

$reader = new Csv();

// Load first CSV file
$spreadsheet = $reader->load('data1.csv');
$spreadsheet->getActiveSheet()->setTitle('Data1');

// Load second CSV file into new sheet
$reader->setSheetIndex(1);
$reader->loadIntoExisting('data2.csv', $spreadsheet);
$spreadsheet->getActiveSheet()->setTitle('Data2');

// Now spreadsheet has 2 worksheets

CSV-Specific Configuration

setDelimiter()

Sets the delimiter character for separating fields.

public function setDelimiter(string $delimiter): self;

delimiter

string

required

The delimiter character (default: auto-detected, typically ,)

Example:

// Tab-separated values
$reader = new Csv();
$reader->setDelimiter("\t");
$spreadsheet = $reader->load('data.tsv');

// Semicolon-separated values
$reader->setDelimiter(';');
$spreadsheet = $reader->load('data.csv');

// Pipe-separated values
$reader->setDelimiter('|');
$spreadsheet = $reader->load('data.txt');

setEnclosure()

Sets the enclosure character for field values.

public function setEnclosure(string $enclosure): self;

enclosure

string

required

The enclosure character (default: ")

Example:

$reader = new Csv();
$reader->setEnclosure("'");
$spreadsheet = $reader->load('data.csv');

setInputEncoding()

Sets the input character encoding.

public function setInputEncoding(string $encoding): self;

encoding

string

required

Character encoding (e.g., ‘UTF-8’, ‘CP1252’, ‘ISO-8859-1’, or ‘guess’)

Example:

// Specific encoding
$reader = new Csv();
$reader->setInputEncoding('CP1252');
$spreadsheet = $reader->load('data.csv');

// Auto-detect encoding
$reader->setInputEncoding(Csv::GUESS_ENCODING);
$spreadsheet = $reader->load('data.csv');

setSheetIndex()

Sets the index for the worksheet when loading into existing spreadsheet.

public function setSheetIndex(int $sheetIndex): self;

sheetIndex

int

required

The 0-based worksheet index

Example:

$reader = new Csv();
$spreadsheet = $reader->load('data1.csv');

// Load into sheet index 1 (second sheet)
$reader->setSheetIndex(1);
$reader->loadIntoExisting('data2.csv', $spreadsheet);

setContiguous()

Sets whether to load rows contiguously.

public function setContiguous(bool $contiguous): self;

contiguous

bool

required

True to load rows contiguously, false otherwise

Example:

$reader = new Csv();
$reader->setContiguous(true);
$spreadsheet = $reader->load('data.csv');

Encoding Support

The CSV reader includes robust encoding detection and conversion:

Supported Encodings

UTF-8 (with or without BOM)
UTF-16 (BE/LE with BOM)
UTF-32 (BE/LE with BOM)
CP1252 (Windows-1252)
ISO-8859-1 (Latin-1)
Other encodings supported by iconv

Automatic Encoding Detection

use PhpOffice\PhpSpreadsheet\Reader\Csv;

$reader = new Csv();
$reader->setInputEncoding(Csv::GUESS_ENCODING);
$spreadsheet = $reader->load('data.csv');

Fallback Encoding

If encoding detection fails, set a fallback encoding:

$reader = new Csv();
$reader->setInputEncoding(Csv::GUESS_ENCODING);
$reader->setFallbackEncoding('CP1252');
$spreadsheet = $reader->load('data.csv');

Delimiter Auto-Detection

If no delimiter is specified, the CSV reader automatically detects the most appropriate delimiter:

$reader = new Csv();
// Delimiter is automatically detected
$spreadsheet = $reader->load('data.csv');

// Common delimiters checked: , ; \t | :

The delimiter detection uses the Csv\Delimiter class which analyzes the file structure.

Working with Different CSV Formats

Standard CSV (Comma-separated)

$reader = new Csv();
$spreadsheet = $reader->load('data.csv');

Tab-separated Values (TSV)

$reader = new Csv();
$reader->setDelimiter("\t");
$spreadsheet = $reader->load('data.tsv');

Semicolon-separated (European format)

$reader = new Csv();
$reader->setDelimiter(';');
$spreadsheet = $reader->load('data.csv');

Custom Delimiter and Enclosure

$reader = new Csv();
$reader->setDelimiter('|');
$reader->setEnclosure("'");
$spreadsheet = $reader->load('data.txt');

Loading Multiple CSV Files

use PhpOffice\PhpSpreadsheet\Reader\Csv;

$files = ['data1.csv', 'data2.csv', 'data3.csv'];

$reader = new Csv();

// Load first file
$spreadsheet = $reader->load($files[0]);
$spreadsheet->getActiveSheet()->setTitle(basename($files[0], '.csv'));

// Load remaining files into separate sheets
for ($i = 1; $i < count($files); $i++) {
    $reader->setSheetIndex($i);
    $reader->loadIntoExisting($files[$i], $spreadsheet);
    $spreadsheet->getActiveSheet()->setTitle(basename($files[$i], '.csv'));
}

echo "Loaded {$spreadsheet->getSheetCount()} worksheets\n";

Value Binding

Control how CSV values are interpreted:

use PhpOffice\PhpSpreadsheet\Cell\StringValueBinder;
use PhpOffice\PhpSpreadsheet\Reader\Csv;

$reader = new Csv();

// Use string value binder to keep all values as strings
$reader->setValueBinder(new StringValueBinder());

$spreadsheet = $reader->load('data.csv');

CSV-Specific Options

setEscapeCharacter()

Sets the escape character (deprecated in PHP 8.4).

public function setEscapeCharacter(?string $escapeCharacter): self;

escapeCharacter

string|null

required

The escape character (default: null)

This method is deprecated and will be removed in a future version as PHP is removing escape character support.

Boolean Value Conversion

$reader = new Csv();
$reader->setGetTrue('YES');
$reader->setGetFalse('NO');
$spreadsheet = $reader->load('data.csv');

Number Formatting

$reader = new Csv();
$reader->setThousandsSeparator(',');
$reader->setDecimalSeparator('.');
$reader->setCastFormattedNumberToNumeric(true);
$spreadsheet = $reader->load('data.csv');

Performance Considerations

CSV files are read sequentially and are generally memory-efficient:

use PhpOffice\PhpSpreadsheet\Reader\Csv;
use PhpOffice\PhpSpreadsheet\Reader\IReader;

$reader = new Csv();
$reader->setInputEncoding('UTF-8');

// Use read filter for large files
$reader->setReadFilter(new ChunkFilter(1, 1000));

$spreadsheet = $reader->load('large_file.csv');

Error Handling

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

$reader = new Csv();

try {
    if (!$reader->canRead('data.csv')) {
        throw new Exception('Cannot read file');
    }
    
    $reader->setInputEncoding(Csv::GUESS_ENCODING);
    $reader->setFallbackEncoding('CP1252');
    
    $spreadsheet = $reader->load('data.csv');
    
} catch (ReaderException $e) {
    echo 'Error loading CSV file: ' . $e->getMessage();
} catch (\Exception $e) {
    echo 'General error: ' . $e->getMessage();
}

Complete Example

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

// Create and configure reader
$reader = new Csv();
$reader->setDelimiter(',');
$reader->setEnclosure('"');
$reader->setInputEncoding(Csv::GUESS_ENCODING);
$reader->setFallbackEncoding('CP1252');

try {
    // Load file
    $spreadsheet = $reader->load('report.csv');
    
    // Access data
    $sheet = $spreadsheet->getActiveSheet();
    $highestRow = $sheet->getHighestRow();
    $highestColumn = $sheet->getHighestColumn();
    
    echo "Loaded {$highestRow} rows and {$highestColumn} columns\n";
    
    // Process data
    foreach ($sheet->getRowIterator() as $row) {
        $cellIterator = $row->getCellIterator();
        $cellIterator->setIterateOnlyExistingCells(false);
        
        foreach ($cellIterator as $cell) {
            $value = $cell->getValue();
            // Process value
        }
    }
    
} catch (ReaderException $e) {
    echo 'Reader error: ' . $e->getMessage();
}

Constructor Callback

Set default options for all CSV reader instances:

use PhpOffice\PhpSpreadsheet\Reader\Csv;

Csv::setConstructorCallback(function(Csv $reader) {
    $reader->setDelimiter(',');
    $reader->setEnclosure('"');
    $reader->setInputEncoding(Csv::GUESS_ENCODING);
});

// All new readers will use these defaults
$reader = new Csv();

Limitations

CSV files contain no formatting information (fonts, colors, etc.)
Only supports a single worksheet per file (use loadIntoExisting for multiple files)
No support for formulas (formulas are read as text values)
No support for charts or images
No support for merged cells

Core Classes

Readers

Writers

Calculation

Styling

Charts & Graphics

​Overview

​Class Information

​Basic Usage

​Simple File Loading

​Using IOFactory

​Key Methods

​__construct()

​canRead()

​load()

​loadIntoExisting()

​CSV-Specific Configuration

​setDelimiter()

​setEnclosure()

​setInputEncoding()

​setSheetIndex()

​setContiguous()

​Encoding Support

​Supported Encodings

​Automatic Encoding Detection

​Fallback Encoding

​Delimiter Auto-Detection

​Working with Different CSV Formats

​Standard CSV (Comma-separated)

​Tab-separated Values (TSV)

​Semicolon-separated (European format)

​Custom Delimiter and Enclosure

​Loading Multiple CSV Files

​Value Binding

​CSV-Specific Options

​setEscapeCharacter()

​Boolean Value Conversion

​Number Formatting

​Performance Considerations

​Error Handling

​Complete Example

​Constructor Callback

​Limitations

​Related Documentation

Build docs developers (and LLMs) love

Overview

Class Information

Basic Usage

Simple File Loading

Using IOFactory

Key Methods

__construct()

canRead()

load()

loadIntoExisting()

CSV-Specific Configuration

setDelimiter()

setEnclosure()

setInputEncoding()

setSheetIndex()

setContiguous()

Encoding Support

Supported Encodings

Automatic Encoding Detection

Fallback Encoding

Delimiter Auto-Detection

Working with Different CSV Formats

Standard CSV (Comma-separated)

Tab-separated Values (TSV)

Semicolon-separated (European format)

Custom Delimiter and Enclosure

Loading Multiple CSV Files

Value Binding

CSV-Specific Options

setEscapeCharacter()

Boolean Value Conversion

Number Formatting

Performance Considerations

Error Handling

Complete Example

Constructor Callback

Limitations

Related Documentation