PHP CSV Handling (fgetcsv / str_getcsv)

Also Known As

TL;DR

Explanation

CSV parsing looks simple — split on commas — until you encounter quoted fields that contain commas, newlines inside quotes, or escaped quote characters. PHP's fgetcsv() reads one CSV row from an open file handle, correctly parsing all RFC 4180 quoting rules. str_getcsv() does the same for an in-memory string. For writing, fputcsv() formats an array as a CSV row with correct quoting. Key parameters: the delimiter (default comma), enclosure character (default double-quote), and escape character. In PHP 8.4, the escape parameter default changed — set it explicitly to avoid version-dependent behaviour. For large files, fgetcsv() in a loop with a generator avoids loading the entire file into memory.

Common Misconception

Why It Matters

Common Mistakes

• Not specifying escape: '' in PHP 8.4+ — the default escape character changed; explicitly set it to avoid version-dependent parsing differences.
• Using file() + array_map('str_getcsv') on files with quoted newlines — file() splits on newlines, breaking multi-line quoted fields; only fgetcsv() handles embedded newlines correctly.
• Forgetting to handle BOM (Byte Order Mark) on Windows-generated CSV files — strip the BOM from the first field: ltrim($firstField, "\xEF\xBB\xBF").
• Not validating the number of fields per row — fgetcsv() returns arrays of varying length if rows have different field counts; always check count($row) === $expectedColumns.

Code Examples

<?php
// ❌ Naïve CSV parsing — breaks on quoted fields
$lines = file('data.csv');
foreach ($lines as $line) {
    $fields = explode(',', trim($line)); // Breaks on: "Smith, John",30,"New York, NY"
    processRow($fields);
}

// Also broken — loading entire large file into memory
$content = file_get_contents('huge_export.csv'); // 500MB in memory
$lines = explode("\n", $content);

<?php
// ✅ fgetcsv() — correct parsing, memory-efficient for large files
function readCsv(string $path): Generator
{
    $handle = fopen($path, 'r');
    if ($handle === false) throw new RuntimeException("Cannot open $path");

    $header = fgetcsv($handle); // First row is headers
    while (($row = fgetcsv($handle, escape: '')) !== false) {
        yield array_combine($header, $row);
    }
    fclose($handle);
}

foreach (readCsv('export.csv') as $row) {
    processRow($row); // One row in memory at a time
}

// Writing CSV
$handle = fopen('output.csv', 'w');
fputcsv($handle, ['name', 'email', 'city']); // Header
fputcsv($handle, ['Smith, John', 'john@example.com', 'New York, NY']);
fclose($handle);

References

• ↗ https://www.php.net/fgetcsv
• ↗ https://www.php.net/str_getcsv
• ↗ https://www.php.net/fputcsv

Tags

Related Terms