PHP 讀取 CSV 檔案完整指南：fgetcsv、SplFileObject、大檔案串流與編碼陷阱

前言：CSV 看似簡單，實則暗藏坑點

RFC 4180 定義 CSV 格式，但實際檔案常見：編碼不一 (UTF-8/BIG5/GBK)、分隔符非逗號、欄位含換行/逗號/引號、BOM 頭、標題列缺失、行數百萬。本文提供生產級讀取方案。

核心工具對比

方案一：SplFileObject (推薦標準用法)

<?php
function readCsv(string $path, string $encoding = 'UTF-8', string $delimiter = ','): \Generator {
    $file = new SplFileObject($path, 'r');
    $file->setFlags(
        SplFileObject::READ_CSV |
        SplFileObject::READ_AHEAD | // 預讀下一行
        SplFileObject::SKIP_EMPTY | // 跳過空行
        SplFileObject::DROP_NEW_LINE
    );
    $file->setCsvControl($delimiter, '"', '\\'); // 分隔符、引號、跳脫

    $header = null;
    foreach ($file as $rowNum => $row) {
        // 編碼轉換 (若檔案非 UTF-8)
        if ($encoding !== 'UTF-8') {
            $row = array_map(fn($v) => mb_convert_encoding($v, 'UTF-8', $encoding), $row);
        }

        if ($header === null) {
            $header = $row; // 第一行當標題
            continue;
        }

        // 組合關聯陣列
        yield array_combine($header, $row);
    }
}

// 使用：逐行處理，記憶體恆定
foreach (readCsv('data.csv', 'BIG5') as $record) {
    // $record = ['id'=>'1', 'name'=>'張三', 'email'=>'...']
    processRecord($record);
}

方案二：League\Csv (進階功能)

composer require league/csv

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

$reader = Reader::createFromPath('big_data.csv', 'r');
$reader->setHeaderOffset(0); // 第一行為標題
$reader->setDelimiter(';');
$reader->setEncoding('ISO-8859-1'); // 內部自動轉 UTF-8

// Statement: 類 SQL 查詢 (篩選、切片、排序)
$stmt = (new Statement())
    ->where(fn($row) => $row['status'] === 'active')
    ->offset(1000)
    ->limit(500);

$records = $stmt->process($reader);
foreach ($records as $record) {
    // $record 為關聯陣列
    exportToApi($record);
}

編碼偵測與轉換最佳實務

1. 優先檢查 BOM：fopen 讀前 3 bytes，EF BB BF = UTF-8 BOM。
2. 使用 mb_detect_encoding 輔助：mb_detect_encoding($sample, ['UTF-8', 'BIG5', 'GBK', 'ISO-8859-1'], true)。
3. 強制指定：由上游系統約定編碼，避免猜測。
4. 轉換失敗策略：mb_convert_encoding($str, 'UTF-8', $from, 'UTF-8//IGNORE') 或拋出異常記錄錯誤行。

大檔案 (＞1GB) 串流處理架構

<?php
class CsvStreamProcessor {
    public function __construct(
        private string $path,
        private int $batchSize = 1000,
        private string $encoding = 'UTF-8'
    ) {}

    public function process(callable $handler): void {
        $reader = Reader::createFromPath($this->path, 'r');
        $reader->setHeaderOffset(0);
        $reader->setEncoding($this->encoding);

        $batch = [];
        foreach ($reader as $record) {
            $batch[] = $record;
            if (count($batch) >= $this->batchSize) {
                $handler($batch);
                $batch = [];
                // 可選：釋放記憶體、GC
                gc_collect_cycles();
            }
        }
        if ($batch) $handler($batch); // 餘數
    }
}

// 使用：批次寫入資料庫、推送隊列
$processor = new CsvStreamProcessor('huge.csv', batchSize: 500);
$processor->process(function(array $batch) {
    DB::table('users')->upsert($batch, 'email', ['name', 'phone']);
    // 或推送 RabbitMQ
    foreach ($batch as $record) $queue->publish($record);
});

常見錯誤對照表

完整 Library 整合 (Laravel CSV Importer、Symfony CSV Bundle) 見 GitHub。