README

Memory-efficient CSV reader and writer with header mapping and type casting.

Requirements

• PHP 8.2+

Installation

composer require philiprehberger/php-csv

Usage

Reading a CSV file

use PhilipRehberger\Csv\Csv;

// Read from file with headers
$rows = Csv::read('data.csv')->toArray();
// [['name' => 'Alice', 'age' => '30'], ...]

// Read from string
$rows = Csv::readString($csvContent)->toArray();

Generator-based iteration

The reader uses PHP generators for memory-efficient processing of large files:

foreach (Csv::read('large-file.csv') as $row) {
    // Process one row at a time — constant memory usage
}

Type casting

Automatically detect and cast value types:

$rows = Csv::read('data.csv')
    ->castTypes(true)
    ->toArray();
// "42" -> int, "3.14" -> float, "true"/"false" -> bool, "" -> null

Filtering and mapping

$rows = Csv::read('data.csv')
    ->castTypes(true)
    ->filter(fn (array $row) => $row['age'] >= 18)
    ->map(fn (array $row) => [...$row, 'label' => strtoupper($row['name'])])
    ->toArray();

Row Validation

Validate each row during reading. Invalid rows are skipped and errors are collected:

$reader = Csv::read('data.csv')
    ->validate(fn (array $row) => isset($row['email']) && str_contains($row['email'], '@'));

$rows = $reader->toArray();

// Inspect which rows failed validation
foreach ($reader->getValidationErrors() as $error) {
    echo "Row {$error['row']}: {$error['error']}\n";
}

The validator can also throw an exception to provide a specific error message:

$reader = Csv::read('data.csv')
    ->validate(function (array $row) {
        if (empty($row['name'])) {
            throw new \InvalidArgumentException('Name is required');
        }
        return true;
    });

Progress Tracking

Monitor processing progress with a callback invoked after each row:

Csv::read('large-file.csv')
    ->withProgress(function (int $rowNumber) {
        if ($rowNumber % 1000 === 0) {
            echo "Processed {$rowNumber} rows...\n";
        }
    })
    ->each(fn (array $row) => processRow($row));

First and last rows

Quickly access the first or last data row without loading everything into an array:

$first = Csv::read('data.csv')->firstRow();
// ['name' => 'Alice', 'age' => '30', ...]

$last = Csv::read('data.csv')->lastRow();
// ['name' => 'Zoe', 'age' => '28', ...]

Both methods return null if the CSV has no data rows.

Grouping rows

Group rows by a column value into an associative array:

$groups = Csv::read('data.csv')->groupBy('city');
// ['Berlin' => [['name' => 'Alice', ...], ...], 'Vienna' => [...]]

Column transformation

Apply per-column transformations during reading:

$rows = Csv::read('data.csv')
    ->transformColumn('name', fn (string $value) => strtoupper($value))
    ->transformColumn('age', fn (string $value) => (int) $value)
    ->toArray();

Duplicate detection

Find duplicate rows based on specific columns:

$duplicates = Csv::read('data.csv')->detectDuplicates(['email']);
// [2, 5] — 0-based indices of duplicate rows

Custom delimiters

$rows = Csv::readString($tsv)
    ->delimiter("\t")
    ->toArray();

TSV and PSV convenience methods

// Tab-separated values
$rows = Csv::readTsv('data.tsv')->toArray();
$tsv = Csv::writeTsv()->headers(['name', 'age'])->rows($data)->toString();

// Pipe-separated values
$rows = Csv::readPsv('data.psv')->toArray();
$psv = Csv::writePsv()->headers(['name', 'age'])->rows($data)->toString();

Writing CSV

use PhilipRehberger\Csv\Csv;

Csv::write('output.csv')
    ->headers(['name', 'age', 'city'])
    ->row(['name' => 'Alice', 'age' => 30, 'city' => 'Berlin'])
    ->row(['name' => 'Bob', 'age' => 25, 'city' => 'Vienna'])
    ->save();

// Or get as string
$csv = Csv::write('')
    ->headers(['name', 'age'])
    ->rows($data)
    ->toString();

Streaming Writer

Write rows directly to disk without buffering, ideal for very large files:

use PhilipRehberger\Csv\Csv;

$writer = Csv::streamWrite('large-output.csv');
$writer->writeHeader(['id', 'name', 'value']);

foreach ($dataSource as $record) {
    $writer->writeRow([$record->id, $record->name, $record->value]);
}

$writer->close();

Appending to an existing file

Append rows to an existing CSV without writing headers again:

Csv::write('output.csv')
    ->headers(['name', 'age'])
    ->row(['name' => 'Charlie', 'age' => 35])
    ->appendToFile('output.csv');

BOM for Excel

Prepend a UTF-8 BOM for Excel compatibility:

Csv::write('output.csv')
    ->headers(['name', 'age'])
    ->rows($data)
    ->bom(true)
    ->save();

API

Csv (static entry)

CsvReader

CsvWriter

StreamingWriter

Development

composer install
vendor/bin/phpunit
vendor/bin/pint --test
vendor/bin/phpstan analyse

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT