CSV 是數據交換常用格式,PHP 內建 fgetcsv() 可高效逐行解析。本文封裝一個 CsvToArray 類,支援自定義分隔符、標題行映射、多維陣列輸出、編碼轉換,並利用生成器實現大文件流式處理,避免內存溢出。
class CsvToArray {
private $filePath;
private $delimiter;
private $enclosure;
private $escape;
private $encoding;
private $hasHeader;
private $headerMap = [];
public function __construct(string $filePath, array $options = []) {
$this->filePath = $filePath;
$this->delimiter = $options['delimiter'] ?? ',';
$this->enclosure = $options['enclosure'] ?? '"';
$this->escape = $options['escape'] ?? '\\';
$this->encoding = $options['encoding'] ?? 'UTF-8';
$this->hasHeader = $options['has_header'] ?? true;
}
// 返回生成器,逐行輸出關聯陣列
public function getRows(): Generator {
$handle = fopen($this->filePath, 'r');
if (!$handle) throw new RuntimeException("無法打開文件: {$this->filePath}");
// 讀取標題行
if ($this->hasHeader) {
$header = fgetcsv($handle, 0, $this->delimiter, $this->enclosure, $this->escape);
if ($header) {
$this->headerMap = array_map(function($h) {
return mb_convert_encoding(trim($h), 'UTF-8', $this->encoding);
}, $header);
}
}
while (($row = fgetcsv($handle, 0, $this->delimiter, $this->enclosure, $this->escape)) !== false) {
// 編碼轉換
$row = array_map(function($v) {
return mb_convert_encoding($v, 'UTF-8', $this->encoding);
}, $row);
if ($this->hasHeader && $this->headerMap) {
// 關聯陣列:標題 => 值
yield array_combine($this->headerMap, $row);
} else {
// 數字索引陣列
yield $row;
}
}
fclose($handle);
}
// 一次性讀取所有(小文件適用)
public function getAll(): array {
return iterator_to_array($this->getRows());
}
}
// data.csv (UTF-8)
/*
id,name,age,city
1,張三,25,北京
2,李四,30,上海
3,王五,28,廣州
*/
$csv = new CsvToArray('data.csv', [
'delimiter' => ',',
'has_header' => true,
'encoding' => 'UTF-8'
]);
// 方式 1:逐行處理(大文件推薦,內存常駐低)
foreach ($csv->getRows() as $row) {
echo "ID: {$row['id']}, 姓名: {$row['name']}, 年齡: {$row['age']}, 城市: {$row['city']}
";
}
// 方式 2:一次性獲取所有(小文件)
$all = $csv->getAll();
print_r($all);
columns => ['id','name'] 或 rename => ['old'=>'new']。cast => ['age'=>'int', 'price'=>'float'] 自動轉型。respect/validation 對每行驗證,失敗行記錄日誌並跳過。chunk(1000, fn($rows)=>...) 批量寫入數據庫。mb_detect_encoding() 自動識別 GBK/Big5/UTF-8。| 問題 | 原因 | 解決 |
|---|---|---|
| 中文亂碼 | 文件編碼非 UTF-8 | 指定 encoding 參數或預先 iconv 轉碼 |
| 字段包含分隔符/換行 | 未用雙引號包裹 | 確保 CSV 生成端符合 RFC 4180,fgetcsv 正確處理 |
| 大文件內存爆炸 | 用 getAll() 一次性讀取 | 改用 getRows() 生成器逐行處理 |
| 首行 BOM 導致鍵名異常 | UTF-8 with BOM | 讀取首行後 ltrim($header[0], "\xEF\xBB\xBF") |
| 行尾符不一致 (\r/\n/\r\n) | 跨平台生成 | fgetcsv 自動處理,無需干預 |
league/csv。new SplFileObject('file.csv'); $obj->setFlags(SplFileObject::READ_CSV); 直接迭代。CsvToArray 類輕量無依賴,適合快速集成;複雜項目建議直接使用 League\Csv 獲得企業級穩健性。