Working with CSV Files

A CSV (Comma-Separated Values) file is a plain text format where each line represents a data record and fields are separated by a delimiter (usually a comma). It is the most common format for data exchange between applications — databases, spreadsheets (Excel, Google Sheets), reporting tools, and data pipelines all support CSV.

How PHP works with CSV: PHP's built-in file I/O functions handle CSV reading and writing without external libraries:

• fopen() — opens the file
• fgetcsv() — reads and parses one line as an array
• fputcsv() — formats an array as a CSV line and writes it
• fclose() — closes the file handle

Reading a CSV:

$handle = fopen('data.csv', 'r');
$headers = fgetcsv($handle); // first row as column names
while (($row = fgetcsv($handle)) !== false) {
    $record = array_combine($headers, $row);
    // ['name' => 'Alice', 'email' => '[email protected]', ...]
}
fclose($handle);

Writing a CSV:

$handle = fopen('output.csv', 'w');
fputcsv($handle, ['name', 'email', 'age']); // header row
fputcsv($handle, ['Alice', '[email protected]', 30]);
fclose($handle);

Common use cases in PHP:

• Exporting database reports for download
• Importing bulk user data, product catalogs, or financial records
• Feeding data pipelines between services

For large files (millions of rows), memory-efficient streaming (reading line-by-line) is essential — loading the entire file into memory with file() or SplFileObject + fetchAll will exhaust the PHP memory limit.

To open a CSV file in PHP, use fopen() with the appropriate mode, then pass the file handle to fgetcsv():

$handle = fopen('data.csv', 'r'); // 'r' = read-only

if ($handle === false) {
    throw new RuntimeException('Cannot open CSV file: data.csv');
}

// Read and parse each row
while (($row = fgetcsv($handle, 0, ',')) !== false) {
    print_r($row); // $row is an array of field values
}

fclose($handle);

Common fopen modes for CSV:

• 'r' — read only, file must exist
• 'w' — write only, truncates existing file or creates new
• 'a' — append, creates if not exists
• 'r+' — read and write, file must exist

Handling encoding: CSV files from Windows programs often use UTF-8 with BOM or Windows-1252 encoding. If you encounter garbled characters:

// Skip UTF-8 BOM if present
rewind($handle);
$bom = fread($handle, 3);
if ($bom !== "\xEF\xBB\xBF") {
    rewind($handle); // not a BOM file, rewind
}

SplFileObject alternative (OOP approach):

$file = new SplFileObject('data.csv', 'r');
$file->setFlags(SplFileObject::READ_CSV);
foreach ($file as $row) {
    if ($row !== [null]) { // skip empty lines
        print_r($row);
    }
}

fgetcsv() reads one line from an open file handle, parses it according to CSV formatting rules, and returns the fields as a numerically indexed array.

Signature:

fgetcsv(
    resource $stream,
    int      $length = 0,     // max line length; 0 = unlimited (PHP 5.1+)
    string   $separator = ',', // field delimiter
    string   $enclosure = '"', // field enclosure character
    string   $escape = '\\'   // escape character
): array|false

Example:

$handle = fopen('products.csv', 'r');
$headers = fgetcsv($handle); // ['id', 'name', 'price', 'category']

while (($row = fgetcsv($handle)) !== false) {
    $product = array_combine($headers, $row);
    echo $product['name'] . ': $' . $product['price'] . "\n";
}
fclose($handle);

Return value:

• An array of strings (one per field) when a line is read successfully
• false at end of file or on error

Handling quoted fields and commas within values: fgetcsv() correctly handles the CSV spec — fields can contain commas if enclosed in quotes: "Smith, John" is parsed as a single field.

Handling different delimiters: For TSV (tab-separated) or semicolon-delimited files (common in European Excel exports):

$row = fgetcsv($handle, 0, "\t");  // tab-separated
$row = fgetcsv($handle, 0, ";");   // semicolon-separated

Memory note: fgetcsv() reads one line at a time — it is inherently memory-efficient for large files, as it does not load the entire file into memory.

fputcsv() formats an array as a CSV line and writes it to an open file handle. It handles all necessary quoting and escaping automatically.

Signature:

fputcsv(
    resource $stream,
    array    $fields,
    string   $separator = ',',
    string   $enclosure = '"',
    string   $escape = '\\',
    string   $eol = "\n"   // PHP 8.1+ added this parameter
): int|false

Basic usage:

$handle = fopen('report.csv', 'w');

// Write header row
fputcsv($handle, ['ID', 'Name', 'Email', 'Amount']);

// Write data rows
$rows = [
    [1, 'Alice Smith', '[email protected]', 1500.50],
    [2, 'Bob O\'Brien', '[email protected]',  750.00],
    [3, 'Carol "CJ" Jones', '[email protected]', 2200.75],
];

foreach ($rows as $row) {
    fputcsv($handle, $row);
}

fclose($handle);

fputcsv() automatically:

• Wraps fields containing the delimiter, enclosure character, or newlines in quotes
• Escapes embedded quote characters
• Returns the number of bytes written, or false on failure

Serving CSV as a download (common pattern):

header('Content-Type: text/csv');
header('Content-Disposition: attachment; filename="export.csv"');

$output = fopen('php://output', 'w');
fputcsv($output, ['Name', 'Email']);
foreach ($users as $user) {
    fputcsv($output, [$user['name'], $user['email']]);
}
fclose($output);
exit;

Using php://output streams directly to the HTTP response without buffering the entire CSV in memory.

Error handling when working with CSV files requires checking return values and using PHP's error handling mechanisms appropriately.

Check file open success:

$handle = @fopen('data.csv', 'r'); // suppress warning with @
if ($handle === false) {
    throw new RuntimeException("Cannot open file: data.csv — " . error_get_last()['message']);
}

Or without @, use set_error_handler() to convert file errors to exceptions.

Check fgetcsv() return value:

while (($row = fgetcsv($handle)) !== false) {
    if ($row === [null]) {
        continue; // skip blank lines
    }
    // process $row
}

if (!feof($handle)) {
    throw new RuntimeException('Unexpected read error before end of file');
}
fclose($handle);

Validate CSV structure:

$expectedColumns = 4;
$lineNumber = 0;
while (($row = fgetcsv($handle)) !== false) {
    $lineNumber++;
    if (count($row) !== $expectedColumns) {
        throw new RuntimeException("Invalid CSV: expected $expectedColumns columns on line $lineNumber, got " . count($row));
    }
}

Common issues to guard against:

• Wrong encoding (UTF-8 BOM, Windows-1252) — detect and convert with mb_convert_encoding()
• Line ending differences (\r\n on Windows, \n on Unix) — fgetcsv() handles this automatically
• Empty lines — check for [null] return
• Malformed quoting — fgetcsv() may return false mid-file; check feof() to distinguish EOF from error

Large file handling: For CSV files with millions of rows, process in batches (e.g., 500 rows) and use transactions for database inserts.