CSV 是資料交換最通用的格式,但 PHP 內建 fgetcsv/fputcsv 在處理大檔案、特殊編碼、欄位包含逗號換行時易出錯。本文提供一個生產級的 CSV 處理類,解決記憶體溢位、BOM、編碼轉換、自動偵測分隔符等實務問題。
<?php
class CsvProcessor {
private $handle;
private $encoding = 'UTF-8';
private $delimiter = ',';
private $enclosure = '"';
private $escape = '\\';
private $headerMap = [];
private $validators = [];
private $errors = [];
public function __construct(string $filePath, string $mode = 'r') {
$this->handle = fopen($filePath, $mode);
if (!$this->handle) throw new RuntimeException("無法開啟檔案:$filePath");
}
// 匯入相關
public function setEncoding(string $encoding): self {
$this->encoding = $encoding;
return $this;
}
public function autoDetectDelimiter(int $sampleLines = 5): self {
$pos = ftell($this->handle);
$delimiters = [',', ';', "\t", '|'];
$maxCount = 0;
for ($i = 0; $i < $sampleLines && !feof($this->handle); $i++) {
$line = fgets($this->handle);
foreach ($delimiters as $d) {
$count = substr_count($line, $d);
if ($count > $maxCount) {
$maxCount = $count;
$this->delimiter = $d;
}
}
}
fseek($this->handle, $pos);
return $this;
}
public function setHeaderMap(array $map): self {
$this->headerMap = $map; // ['csv欄位名' => '內部欄位名']
return $this;
}
public function addValidator(string $field, callable $validator): self {
$this->validators[$field] = $validator;
return $this;
}
public function import(callable $rowHandler): array {
$header = null;
$rowNum = 0;
while (($row = fgetcsv($this->handle, 0, $this->delimiter, $this->enclosure, $this->escape)) !== false) {
$rowNum++;
if ($header === null) {
$header = $row;
if ($this->headerMap) {
$header = array_map(fn($h) => $this->headerMap[$h] ?? $h, $header);
}
continue;
}
$data = array_combine($header, $row);
$data = $this->convertEncoding($data);
// 驗證
$rowErrors = [];
foreach ($this->validators as $field => $validator) {
try {
$validator($data[$field] ?? null, $data);
} catch (Throwable $e) {
$rowErrors[] = "$field: " . $e->getMessage();
}
}
if ($rowErrors) {
$this->errors[] = ['row' => $rowNum, 'errors' => $rowErrors, 'data' => $data];
continue;
}
$rowHandler($data, $rowNum);
}
return ['imported' => $rowNum - 1, 'errors' => $this->errors];
}
// 匯出相關
public function export(iterable $data, array $headers, string $outputPath): int {
$out = fopen($outputPath, 'w');
// 寫入 UTF-8 BOM 讓 Excel 正確識別中文
fwrite($out, "\xEF\xBB\xBF");
fputcsv($out, $headers, $this->delimiter, $this->enclosure, $this->escape);
$count = 0;
foreach ($data as $row) {
$line = [];
foreach ($headers as $h) {
$line[] = $this->convertEncoding([$h => $row[$h] ?? ''])[$h] ?? '';
}
fputcsv($out, $line, $this->delimiter, $this->enclosure, $this->escape);
$count++;
if ($count % 1000 === 0) {
fflush($out); // 定期刷新緩衝區
}
}
fclose($out);
return $count;
}
private function convertEncoding(array $data): array {
if ($this->encoding === 'UTF-8') return $data;
return array_map(function($v) {
return is_string($v) ? mb_convert_encoding($v, 'UTF-8', $this->encoding) : $v;
}, $data);
}
public function __destruct() {
if ($this->handle) fclose($this->handle);
}
}
$processor = new CsvProcessor('members.csv')
->setEncoding('Big5') // 來源編碼
->autoDetectDelimiter() // 自動偵測分隔符
->setHeaderMap(['姓名'=>'name', '信箱'=>'email', '電話'=>'phone'])
->addValidator('email', fn($v) => filter_var($v, FILTER_VALIDATE_EMAIL) ?: throw new Exception('Email 格式錯誤'))
->addValidator('phone', fn($v) => preg_match('/^09\d{8}$/', $v) ?: throw new Exception('手機格式錯誤'));
$result = $processor->import(function($data, $rowNum) {
// 寫入資料庫、發送歡迎信等
Member::create($data);
});
echo "匯入 {$result['imported']} 筆,錯誤 " . count($result['errors']) . " 筆";
$orders = Order::where('created_at', '>=', '2024-01-01')->cursor(); // 游標避免載入所有記憶體
$processor = new CsvProcessor('orders_export.csv', 'w');
$count = $processor->export($orders, [
'order_no' => '訂單編號',
'user_name' => '會員姓名',
'total' => '金額',
'created_at' => '下單時間',
], 'orders_export.csv');
echo "匯出 $count 筆完成";
fgetcsv($handle, 0, ...) 移除長度限制(PHP 8.0+)。cursor() / Generator 逐行處理資料庫查詢結果。fflush() 避免輸出緩衝區過大。這個 CSV 處理類解決了編碼、記憶體、分隔符、驗證等實務痛點,採用流式設計支援任意大小檔案。實際專案中可依需求擴充:欄位型別轉換、日期格式正規化、外鍵關聯查詢快取等。