萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP CSV 匯入匯出類完整實作:支援大檔案、編碼轉換、記憶體優化

前言

CSV 是資料交換最通用的格式,但 PHP 內建 fgetcsv/fputcsv 在處理大檔案、特殊編碼、欄位包含逗號換行時易出錯。本文提供一個生產級的 CSV 處理類,解決記憶體溢位、BOM、編碼轉換、自動偵測分隔符等實務問題。

類別設計目標

  • 流式處理:不將整份檔案載入記憶體,支援 GB 級大檔。
  • 編碼自動轉換:輸入 UTF-8/Big5/GBK,輸出統一 UTF-8(或指定編碼)。
  • 分隔符自動偵測:逗號、分號、Tab 自動識別。
  • 欄位對應與驗證:支援標題列對應、資料型別轉換、驗證規則。
  • 錯誤容忍:逐行處理,單行錯誤不中斷整體,收集錯誤報告。

核心類別實作

<?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 處理類解決了編碼、記憶體、分隔符、驗證等實務痛點,採用流式設計支援任意大小檔案。實際專案中可依需求擴充:欄位型別轉換、日期格式正規化、外鍵關聯查詢快取等。

copyright © 萬盛學電腦網 all rights reserved