thephpleague/csv

The League\Csv\TabularDataReader interface (introduced in version 9.6) provides a common API for handling tabular data structures, such as CSV documents, HTML tables, or RDBMS tables.

A tabular data structure consists of:

• A collection of similar, non-nested PHP array records.
• An optional header containing unique string values.

TabularDataReader implementations (like Reader) are generally immutable; methods like filter(), select(), and slice() return a new instance, leaving the original data unchanged.

Access CSV documents using one of two primary classes depending on your required mode:

• League\Csv\Reader: Use this for read-only mode.
• League\Csv\Writer: Use this for write-only mode.

Both classes extend League\Csv\AbstractCsv and share features for loading documents, setting control characters, managing BOM sequences, adding PHP stream filters, and outputting documents.

To use the Csv library, ensure your environment meets the following requirements:

• The ext-filter PHP extension must be installed.
• PHP version compatibility depends on the library version. For version 9.16.0 and above, PHP 8.1.2 or higher is required (supports up to PHP 8.x).

The League\Csv\Buffer class (available since version 9.22.0) allows you to manage and transform tabular data using basic CRUD operations.

Warning: The Buffer stores all data in-memory. It does not use PHP streams like Reader or Writer, so it cannot handle extremely large datasets. You must manually limit the size of the data loaded into it to avoid memory exhaustion.

In version 7.x, setNullHandlingMode has been removed from the Writer class. By default, null values are converted to empty strings. To replicate previous behaviors, use the following plugins:

1. To throw an exception on nulls: Use League\Csv\Plugin\ForbiddenNullValuesValidator.
2. To skip null cells: Use League\Csv\Plugin\SkipNullValuesFormatter.

use League\
Csv\\Writer;
use League\Csv\Plugin\ForbiddenNullValuesValidator;

$validator = new ForbiddenNullValuesValidator();
$writer = Writer::createFromPath('/path/to/your/csv/file.csv');
$writer->addValidator($validator, 'null_as_exception');
$writer->insertOne(['foo', null, 'bar']); // throws League\Csv\Exception\InvalidRowException

You can use the Bom class to detect Byte Order Marks (BOM) and apply PHP stream filters to the Reader to handle character encoding conversions (e.g., UTF-16 to UTF-8) during iteration.

use League\Csv\Reader;
use League\Csv\Bom;

$csv = Reader::from('/path/to/your/csv/file.csv', 'r');
$csv->setHeaderOffset(0);

if (Bom::tryFromSequence($csv)?->isUtf16() ?? false) {
    $csv->appendStreamFilterOnRead('convert.iconv.UTF-16/UTF-8');
}

foreach ($csv as $record) {
    //all fields from the record are converted from UTF-16 into UTF-8 charset
    //and the BOM sequence is removed
}

Use League\Csv\Reader to load a CSV file and League\Csv\Statement to apply filters like offsets and limits.

Note for PHP 8.4+ users: You must call $csv->setEscape('') to avoid deprecation notices.

use League\Csv\Reader;
use League\Csv\Statement;

$csv = Reader::from('/path/to/your/csv/file.csv', 'r');
$csv->setHeaderOffset(0); //set the CSV header offset
$csv->setEscape(''); //required in PHP8.4+ to avoid deprecation notices

//get 25 records starting from the 11th row
$stmt = new Statement()
    ->offset(10)
    ->limit(25)
;

$records = $stmt->process($csv);
foreach ($records as $record) {
    //do something here
}

Direct row consistency checking was removed from the Writer class in version 7.x. Use the League\Csv\Plugin\ColumnConsistencyValidator to manage column counts and consistency.

use League\Csv\Writer;
use League\Csv\Plugin\ColumnConsistencyValidator;

$validator = new ColumnConsistencyValidator();
$validator->autodetectColumnsCount();
$validator->getColumnsCount(); // returns -1

$writer = Writer::createFromPath('/path/to/your/csv/file.csv');
$writer->addValidator($validator, 'column_consistency');

$writer->insertOne(['foo', null, 'bar']);
$nb_column_count = $validator->getColumnsCount(); // returns 3