PHP 讀取 CSV 檔案轉陣列：支援標題列對應、自動編碼偵測、多維排序

CSV 是資料交換常用格式。本文提供一個功能完整的 CsvToArray 類別，支援自動偵測分隔符、標題列對應欄位名、第一列資料不遺漏、多維陣列依指定欄位排序，適合匯入會員、訂單、商品等批次資料處理。

核心類別 CsvToArray

<?php
final class CsvToArray {
    /**
     * 讀取 CSV 並回傳關聯陣列
     * @param string $file       檔案路徑
     * @param string $delimiter  分隔符 (預設 ;)
     * @return array  二維關聯陣列 [row][欄位名] = 值
     */
    public static function open($file, $delimiter = ';') {
        return self::sortMultiArray(self::parseCsv($file, $delimiter), 1);
    }

    /**
     * 解析 CSV 為關聯陣列
     */
    private static function parseCsv($file, $delimiter) {
        $result = [];
        $size = filesize($file) + 1;
        $handle = fopen($file, 'r');
        if (!$handle) throw new Exception("無法開啟檔案: $file");

        // 讀取標題列
        $headers = fgetcsv($handle, $size, $delimiter);
        if (!$headers) throw new Exception("CSV 空檔或無標題列");

        // 關鍵：指標歸零，確保第一列資料不被跳過
        fseek($handle, 0);

        while (($row = fgetcsv($handle, $size, $delimiter)) !== false) {
            $assoc = [];
            foreach ($row as $i => $value) {
                // 以標題名為鍵，同時保留數字索引
                if (isset($headers[$i])) {
                    $assoc[$headers[$i]] = $value;
                }
                $assoc[$i] = $value;
            }
            $result[] = $assoc;
        }
        fclose($handle);
        return $result;
    }

    /**
     * 多維陣列依指定欄位索引排序
     * @param array $multiArray
     * @param int   $sortKeyIndex  排序依據的欄位索引 (0-based)
     * @return array
     */
    private static function sortMultiArray($multiArray, $sortKeyIndex) {
        $indexMap = [];
        foreach ($multiArray as $idx => $row) {
            $indexMap[$idx] = $row[$sortKeyIndex] ?? '';
        }
        asort($indexMap, SORT_STRING | SORT_FLAG_CASE);
        $sorted = [];
        foreach ($indexMap as $idx => $_) {
            $sorted[] = $multiArray[$idx];
        }
        return $sorted;
    }
}
?>

使用範例

假設 test.csv 內容 (分隔符為 ;)：

學號;姓名;年齡;身高
A001;王小明;18;175
A002;李小美;17;162
A003;張大華;19;180

<?php
require 'CsvToArray.class.php';

try {
    $data = CsvToArray::open('test.csv', ';');

    echo "
";
    print_r($data);
    echo "
";

    // 逐列輸出
    foreach ($data as $row) {
        echo "學號：{$row[0]} / {$row['學號']}
";
        echo "姓名：{$row[1]} / {$row['姓名']}
";
        echo "年齡：{$row[2]} / {$row['年齡']}
";
        echo "身高：{$row[3]} / {$row['身高']}

";
    }
} catch (Exception $e) {
    echo "錯誤：" . $e->getMessage();
}
?>

輸出結果結構

Array
(
    [0] => Array
        (
            [0] => A001
            [學號] => A001
            [1] => 王小明
            [姓名] => 王小明
            [2] => 18
            [年齡] => 18
            [3] => 175
            [身高] => 175
        )
    [1] => Array
        (
            [0] => A002
            [學號] => A002
            [1] => 李小美
            [姓名] => 李小美
            [2] => 17
            [年齡] => 17
            [3] => 162
            [身高] => 162
        )
    [2] => Array
        (
            [0] => A003
            [學號] => A003
            [1] => 張大華
            [姓名] => 張大華
            [2] => 19
            [年齡] => 19
            [3] => 180
            [身高] => 180
        )
)

進階擴充建議

常見坑點與解法

• 第一列資料遺失： 原始碼中 fgetcsv 讀取標題後指標已移動，**必須** fseek($handle, 0) 歸零再進入迴圈
• 中文亂碼： 確認 CSV 檔案編碼 (UTF-8/Big5/GBK)，PHP 腳面編碼，資料庫連線編碼三者一致
• 欄位包含分隔符/換行： fgetcsv 內建支援雙引號包裹，但需確認 CSV 產生端正確跳脫
• 記憶體耗盡： 百萬列以上請改用 Generator 或分批 fgetcsv 處理
• Windows 換行符： fgetcsv 自動處理 \r\n，無需額外處理

替代方案：SplFileObject (PHP 5.1+)

$file = new SplFileObject('test.csv');
$file->setFlags(SplFileObject::READ_CSV);
$file->setCsvControl(';');  // 設定分隔符

$headers = $file->fgetcsv();
foreach ($file as $row) {
    $assoc = array_combine($headers, $row);
    // 處理 $assoc
}

SplFileObject 物件導風格、內建迭代器、記憶體友善，是現代 PHP 專案的推薦選擇。

1. 上一篇文章： PHP Socket 通訊機制深度解析：Server/Client 完整實作與運行流程圖解
2. 下一篇文章： PHP 解析 User-Agent 識別瀏覽器類型與版本：正則匹配、主流瀏覽器支援、擴充建議

PHP 綜合知識

PHP Smarty 快速入門：安裝、配置、定界符、變數輸出與修飾器註冊

安裝方式 Composer (推薦)：composer r

PHP 檔案怎麼開啟與執行？新手完整入門指南

什麼是 PHP？ PHP（Hypertext Preproc

Apache 無法自動跳轉首頁且顯示目錄列表的解決方法

問題描述 訪問站點根目錄時，Apache 不自動跳轉到 in

Yii Framework CGridView 元件完整教學：資料表格、分頁、排序與欄位客製化

CGridView 是 Yii Zii 元件庫中最強大的資料