feat(csv): 增加CSV操作

Author: zxc7563598

README.md

@@ -80,6 +80,13 @@ So, I’ve compiled these simple and frequently-used methods into this toolkit.
 | FileUtils::getCommonLinesFromFiles()     | Get intersecting lines from multiple files      |
 | FileUtils::extractColumnFromCsvFiles()   | Quickly extract columns from multiple CSV files |
 
+### CSV operation
+
+| Method                | Explanation                        |
+| :-------------------- | :--------------------------------- |
+| Csv::readCsvToArray() | Read CSV file and convert to array |
+| Csv::arrayToCsv()     | Write the array to a CSV file      |
+
 ### Network Request Operations
 
 | method                        | describe                                    |

README.zh-CN.md

@@ -81,13 +81,20 @@ composer require hejunjie/utils
 | FileUtils::getCommonLinesFromFiles()     | 从多个文件中获取交集行      |
 | FileUtils::extractColumnFromCsvFiles()   | 从多个 csv 文件中快速提取列 |
 
+### CSV 操作
+
+| 方法                  | 说明                      |
+| :-------------------- | :------------------------ |
+| Csv::readCsvToArray() | 读取 CSV 文件并转换为数组 |
+| Csv::arrayToCsv()     | 将数组写入 CSV 文件       |
+
 ### 网络请求操作
 
 | 方法                          | 说明                     |
 | :---------------------------- | :----------------------- |
 | HttpClient::sendGetRequest()  | 使用 cURL 发送 GET 请求  |
 | HttpClient::sendPostRequest() | 使用 cURL 发送 POST 请求 |
-| HttpClient::downloadFile() | 下载远程文件并保存到本地 |
+| HttpClient::downloadFile()    | 下载远程文件并保存到本地 |
 
 ### 图片操作
 
@@ -133,7 +140,7 @@ composer require hejunjie/tools
 
 [hejunjie/address-parser](https://github.com/zxc7563598/php-address-parser) - 收货地址智能解析工具，支持从非结构化文本中提取姓名、手机号、身份证号、省市区、详细地址等字段，适用于电商、物流、CRM 等系统。
 
-[hejunjie/url-signer](https://github.com/zxc7563598/php-url-signer) - 用于生成带签名和加密保护的URL链接的PHP工具包，适用于需要保护资源访问的场景
+[hejunjie/url-signer](https://github.com/zxc7563598/php-url-signer) - 用于生成带签名和加密保护的 URL 链接的 PHP 工具包，适用于需要保护资源访问的场景
 
 [hejunjie/google-authenticator](https://github.com/zxc7563598/php-google-authenticator) - 一个用于生成和验证时间基础一次性密码（TOTP）的 PHP 包，支持 Google Authenticator 及类似应用。功能包括密钥生成、二维码创建和 OTP 验证。
 

src/Csv.php

@@ -0,0 +1,98 @@
+<?php
+
+namespace Hejunjie\Csv;
+
+use Exception;
+
+/**
+ * CSV处理类
+ * 
+ * @package Hejunjie\Csv
+ */
+class Csv
+{
+
+    /**
+     * 读取 CSV 文件并转换为数组
+     *
+     * @param string $csvPath CSV 文件路径
+     * @param bool   $useHeaderAsKey 是否使用第一行作为 key
+     * @param string $delimiter CSV 分隔符，默认逗号
+     * 
+     * @return array
+     * @throws Exception
+     */
+    function readCsvToArray(string $csvPath, bool $useHeaderAsKey = true, string $delimiter = ','): array
+    {
+        if (!is_readable($csvPath)) {
+            throw new \Exception("CSV 文件不可读: {$csvPath}");
+        }
+        $handle = fopen($csvPath, 'r');
+        if ($handle === false) {
+            throw new \Exception("无法打开 CSV 文件: {$csvPath}");
+        }
+        $result = [];
+        $header = [];
+        while (($row = fgetcsv($handle, 0, $delimiter)) !== false) {
+            if ($useHeaderAsKey && empty($header)) {
+                $header = $row;
+                continue;
+            }
+            if ($useHeaderAsKey) {
+                $item = [];
+                foreach ($header as $index => $key) {
+                    $item[$key] = $row[$index] ?? null;
+                }
+                $result[] = $item;
+            } else {
+                $result[] = $row;
+            }
+        }
+        fclose($handle);
+        return $result;
+    }
+
+    /**
+     * 将数组写入 CSV 文件
+     *
+     * @param array  $data 要写入的数据
+     * @param string $filePath CSV 文件保存路径
+     * @param bool   $writeHeader 是否写入表头（仅在二维关联数组时有效）
+     * @param string $delimiter CSV 分隔符，默认逗号
+     * 
+     * @return void
+     * @throws Exception
+     */
+    function arrayToCsv(array $data, string $filePath, bool $writeHeader = true, string $delimiter = ','): void
+    {
+        if (empty($data)) {
+            throw new \Exception('写入 CSV 的数据为空');
+        }
+        // 确保目录存在
+        $dir = dirname($filePath);
+        if (!is_dir($dir)) {
+            if (!mkdir($dir, 0777, true) && !is_dir($dir)) {
+                throw new \Exception("无法创建目录: {$dir}");
+            }
+        }
+        $handle = fopen($filePath, 'w');
+        if ($handle === false) {
+            throw new \Exception("无法写入 CSV 文件: {$filePath}");
+        }
+        fwrite($handle, "\xEF\xBB\xBF");
+        $firstRow = reset($data);
+        $isAssoc = array_keys($firstRow) !== range(0, count($firstRow) - 1);
+        if ($writeHeader && $isAssoc) {
+            fputcsv($handle, array_keys($firstRow), $delimiter);
+        }
+        // 写数据行
+        foreach ($data as $row) {
+            if ($isAssoc) {
+                fputcsv($handle, array_values($row), $delimiter);
+            } else {
+                fputcsv($handle, $row, $delimiter);
+            }
+        }
+        fclose($handle);
+    }
+}