PHP 鏈式操作導出 CSV/Excel 實戰：優雅的流式輸出與記憶體優化

為什麼選擇鏈式 API 導出資料？

傳統陣列組裝再一次性輸出，面對大量資料易導致記憶體耗盡。鏈式操作配合 流式輸出，可逐行發送給瀏覽器，記憶體佔用恆定，且語法如 $exporter->title(...)->body(...)->multiBody(...) 閱讀性極佳。本文實作一個生產級 CsvExporter 類，支援標題、單行、多行、分批寫入、編碼轉換、大檔案分片下載。

核心類實作：CsvExporter

<?php

class CsvExporter
{
    private $handle;
    private $filename;
    private $encoding = 'UTF-8';
    private $delimiter = ',';
    private $enclosure = '"';
    private $bomWritten = false;
    private $rowCount = 0;

    public function __construct(string $filename, string $encoding = 'UTF-8')
    {
        $this->filename = $filename;
        $this->encoding = $encoding;
        
        // 開啟 PHP 輸出流，直接寫入瀏覽器
        $this->handle = fopen('php://output', 'w');
        
        // 發送 HTTP 下載頭
        header('Content-Type: text/csv; charset=' . $encoding);
        header('Content-Disposition: attachment; filename="' . rawurlencode($filename) . '.csv"');
        header('Cache-Control: must-revalidate, post-check=0, pre-check=0');
        header('Pragma: public');
        header('Expires: 0');
        
        // 寫入 BOM（Excel 正確識別 UTF-8）
        if ($encoding === 'UTF-8') {
            fwrite($this->handle, "\xEF\xBB\xBF");
            $this->bomWritten = true;
        }
        
        return $this; // 支援鏈式
    }

    /** 設定分隔符（預設逗號，可改 \t 產生 TSV） */
    public function delimiter(string $char): self
    {
        $this->delimiter = $char;
        return $this;
    }

    /** 寫入標題列 */
    public function title(array $columns): self
    {
        $this->writeRow($columns);
        return $this;
    }

    /** 寫入單行資料 */
    public function body(array $row): self
    {
        $this->writeRow($row);
        return $this;
    }

    /** 批次寫入多行資料（支援 Generator 節省記憶體） */
    public function multiBody(iterable $rows): self
    {
        foreach ($rows as $row) {
            if (is_array($row)) {
                $this->writeRow($row);
            }
        }
        return $this;
    }

    /** 分批寫入：配合資料庫游標/Generator 使用，每 N 行 flush 一次 */
    public function chunk(iterable $source, int $size = 1000, callable $transform = null): self
    {
        $buffer = [];
        foreach ($source as $item) {
            $row = $transform ? $transform($item) : $item;
            if (is_array($row)) {
                $buffer[] = $row;
                if (count($buffer) >= $size) {
                    $this->flushBuffer($buffer);
                    $buffer = [];
                }
            }
        }
        if ($buffer) $this->flushBuffer($buffer);
        return $this;
    }

    /** 關閉流並結束腳本 */
    public function output(): void
    {
        fclose($this->handle);
        exit;
    }

    private function writeRow(array $row): void
    {
        // 編碼轉換：內部 UTF-8 → 目標編碼（如 BIG5 給舊版 Excel）
        if ($this->encoding !== 'UTF-8') {
            $row = array_map(fn($v) => mb_convert_encoding($v, $this->encoding, 'UTF-8'), $row);
        }
        fputcsv($this->handle, $row, $this->delimiter, $this->enclosure);
        $this->rowCount++;
        
        // 定期 flush 避免緩衝區過大
        if ($this->rowCount % 500 === 0) {
            fflush($this->handle);
        }
    }

    private function flushBuffer(array &$buffer): void
    {
        foreach ($buffer as $row) {
            $this->writeRow($row);
        }
        fflush($this->handle);
    }

    public function getRowCount(): int
    {
        return $this->rowCount;
    }
}

使用範例：從資料庫分批導出 10 萬筆會員

<?php
require 'CsvExporter.php';
require 'db.php'; // PDO 連線

// 1. 建立導出器
$exporter = new CsvExporter('members_export_' . date('Ymd_His'));

// 2. 寫入標題
$exporter->title(['ID', '帳號', '姓名', 'Email', '註冊時間', '狀態']);

// 3. 使用 PDO 游標分批讀取，配合 chunk() 流式寫入
$stmt = $pdo->query('SELECT id, username, real_name, email, created_at, status FROM members ORDER BY id');
$stmt->setFetchMode(PDO::FETCH_ASSOC);

$exporter->chunk($stmt, 1000, function($row) {
    return [
        $row['id'],
        $row['username'],
        $row['real_name'],
        $row['email'],
        date('Y-m-d H:i:s', $row['created_at']),
        $row['status'] ? '啟用' : '停用'
    ];
});

// 4. 輸出完成
$exporter->output();
// 腳本不會執行到這裡

進階功能擴充

1. 支援多工作表 Excel (XLSX) —— 結合 PhpSpreadsheet

class XlsxExporter extends CsvExporter {
    private $spreadsheet;
    private $sheet;
    
    public function __construct(string $filename) {
        $this->spreadsheet = new \PhpOffice\PhpSpreadsheet\Spreadsheet();
        $this->sheet = $this->spreadsheet->getActiveSheet();
        parent::__construct($filename); // 覆寫輸出邏輯
    }
    
    protected function writeRow(array $row): void {
        $this->sheet->fromArray($row, null, 'A' . ($this->rowCount + 1));
        $this->rowCount++;
    }
    
    public function output(): void {
        $writer = new \PhpOffice\PhpSpreadsheet\Writer\Xlsx($this->spreadsheet);
        header('Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet');
        header('Content-Disposition: attachment; filename="' . $this->filename . '.xlsx"');
        $writer->save('php://output');
        exit;
    }
}

2. 大檔案分片下載（斷點續傳支援）

對於超大檔案（>100MB），建議：

1. 後端生成暫存檔（tempnam(sys_get_temp_dir(), 'export_')）
2. 記錄檔案大小、ETag、分片資訊到 Redis/資料庫
3. 前端使用 Range 請求分片下載，合併 Blob
4. 提供「生成中」輪詢 API，完成後返回下載連結

效能對比實測（10 萬筆 × 6 欄位）

常見坑點避雷指南

• Excel 開啟 CSV 亂碼：務必寫入 UTF-8 BOM（\xEF\xBB\xBF），或轉 BIG5/GBK
• 欄位包含逗號/換行/雙引號：fputcsv() 會自動加雙引號包裹並轉義內部雙引號
• 長數字科學計數法：在欄位前加 \t 或 ='1234567890123' 強制文本格式
• 輸出前有空白/換行：確保 前無輸出，或用 ob_clean() 清理
• Nginx proxy_buffering 截斷：proxy_buffering off; 或 X-Accel-Buffering: no