PHP CSV Handling (fgetcsv / str_getcsv)
debt(d7/e3/b3/t7)
Closest to 'only careful code review or runtime testing' (d7). The detection_hints.tools field is empty/unspecified, and no standard linter or SAST tool reliably flags incorrect CSV parsing patterns (e.g., using explode instead of fgetcsv, or misusing str_getcsv on multi-line files). Bugs typically surface only when real-world CSV data with quoted commas or embedded newlines is processed, making this a runtime/review-level detection issue.
Closest to 'simple parameterised fix' (e3). The quick_fix indicates replacing explode(',', $line) with str_getcsv($line) for single lines, and replacing file-reading loops with fgetcsv($handle) for multi-file scenarios. This is slightly more than a one-liner because the escape parameter must also be set explicitly for PHP 8.4+ compatibility, and BOM handling may need to be added — touching the parsing logic but staying within one component.
Closest to 'localised tax' (b3). CSV handling applies to specific data-processing contexts (web, cli) and the choice is typically isolated to import/export routines. It doesn't propagate across the whole codebase — it's a tax paid by the component doing file parsing, not by every maintainer or feature.
Closest to 'serious trap' (t7). The canonical misconception (explicitly documented) is that str_getcsv() can parse an entire multi-line CSV file when it actually only parses a single record. This contradicts the intuitive reading of the function name ('get CSV') and how similar parsing utilities in other languages (Python's csv.reader, Ruby's CSV.parse) work on full strings or streams. Additionally, the escape default change in PHP 8.4+ and the embedded-newline breakage with file() + array_map are serious undocumented gotchas that contradict reasonable developer expectations.
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);