# str_getcsv

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

str_getcsv — 解析 CSV 字符串为一个数组

### 说明

str_getcsv(
string `$string`,
string `$separator` = ",",
string `$enclosure` = "\"",
string `$escape` = "\\"
): array

以 CSV 字段格式解析字符串输入，并返回包含读取字段的数组。

> 注意:

> 此函数会考虑区域设置。例如，如果 `LC_CTYPE` 为 `en_US.UTF-8`，可能会错误的解析某些单字节编码的数据。

### 参数

`string`

  待解析的字符串。

`separator`

  可选的 `separator` 参数，设置字段分隔符。必须是单字节字符。

`enclosure`

  可选的 `enclosure` 参数，设置字段环绕符。必须是单字节字符。

`escape`

  可选的 `escape` 参数，设置转义字符。必须是单字节字符或者空字符串。空字符串（`""`）禁用所有的转义机制。

  警告

  在输入流中，`enclosure` 字符在引号字符串内可通过重复自身进行转义，解析后结果中将只保留一个 `enclosure` 字符。而 `escape` 字符的行为有所不同：若输入中出现 `escape` 字符与 `enclosure` 字符的组合序列，这两个字符都会保留在解析结果中。因此，在默认参数下，类似 `"a""b","c\"d"` 的 CSV 行将被解析为两个字段，分别为 `a"b` 和 `c\"d`。

  警告

  从 PHP 8.4.0 开始，弃用依赖 `escape` 的默认值。需要通过位置或使用命名参数明确提供。

警告

当 `escape` 被设置为非空字符串（`""`）时， 可能导致生成的 CSV 不符合 » RFC 4180 的要求， 或者无法通过 PHP CSV 函数的往返处理。 `escape` 的默认值是 `"\\"`，因此建议显式地将其设置为空字符串。 默认值将在未来的 PHP 版本中更改，不早于 PHP 9.0。

### 返回值

返回一个包含读取到的字段的索引数组。

### 错误／异常

如果 `separator` 或者 `enclosure` 长度不是一个字节，则抛出 ValueError。

如果 `escape` 的长度不是一个字节或者为空字符串，则抛出 ValueError。

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 现在已弃用依赖 escape 的默认值。
8.4.0 | 如果 `separator`、`enclosure` 或 `escape` 无效，现在会抛出 ValueError。这模仿了 fgetcsv() 和 fputcsv() 的行为。
8.3.0 | 如果最后一个字段仅包含未终止的 enclosure，则返回空字符串，而不是带有单个 NULL 字节的字符串。
7.4.0 | `escape` 现在将空字符串视为禁用专有转义机制的信号。以前视为默认参数值。

### 示例

示例 #1 str_getcsv() 示例

`<?php
$string = 'PHP,Java,Python,Kotlin,Swift';
$data = str_getcsv($string, escape: '\\');
var_dump($data);
?>`

以上示例会输出：

    array(5) {
      [0]=>
      string(3) "PHP"
      [1]=>
      string(4) "Java"
      [2]=>
      string(6) "Python"
      [3]=>
      string(6) "Kotlin"
      [4]=>
      string(5) "Swift"
    }

示例 #2 处理空字符串的 str_getcsv() 示例

警告

对于空字符串，此函数返回值 `[null]` 从而代替空数组。

`<?php
$string = '';
$data = str_getcsv($string, escape: '\\');
var_dump($data);
?>`

以上示例会输出：

    array(1) {
      [0]=>
      NULL
    }

### 参见

- fputcsv() - 将行格式化为 CSV 并写入文件指针
- fgetcsv() - 从文件指针中读入一行并解析 CSV 字段
- SplFileObject::fgetcsv() - Gets line from file and parse as CSV fields
- SplFileObject::fputcsv() - Write a field array as a CSV line
- SplFileObject::setCsvControl() - Set the delimiter, enclosure and escape character for CSV
- SplFileObject::getCsvControl() - Get the delimiter, enclosure and escape character for CSV

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open