Gets line from file and parse as CSV fields

# SplFileObject::fgetcsv

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

SplFileObject::fgetcsv — Gets line from file and parse as CSV fields

### 说明

public function SplFileObject::fgetcsv(string `$separator` = ",", string `$enclosure` = "\"", string `$escape` = "\\"): array|false

Gets a line from the file which is in CSV format and returns an array containing the fields read.

> 注意:

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

### 参数

`separator`

  The field delimiter (one single-byte character only). By default `,` or the value set by a prior call to SplFileObject::setCsvControl().

`enclosure`

  The field enclosure character (one single-byte character only). By default `"` or the value set by a prior call to SplFileObject::setCsvControl().

`escape`

  The escape character (at most one single-byte character). By default `\` or the value set by a prior call to SplFileObject::setCsvControl(). An empty string (`""`) disables the proprietary escape mechanism.

  警告

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

  警告

  As of PHP 8.4.0, depending on the default value of `escape` is deprecated. It needs to be provided explicitly either positionally or by the use of Named Arguments, or by a call to SplFileObject::setCsvControl().

警告

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

### 返回值

Returns an indexed array containing the fields read, or `false` on error.

> 注意:

> A blank line in a CSV file will be returned as an array comprising a single `null` field unless using `SplFileObject::SKIP_EMPTY | SplFileObject::DROP_NEW_LINE`, in which case empty lines are skipped.

### 错误／异常

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

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

### 更新日志

版本 | 说明
--- | ---
8.4.0 | 现在已弃用依赖 escape 的默认值。
7.4.0 | The `escape` parameter now also accepts an empty string to disable the proprietary escape mechanism.

### 示例

示例 #1 SplFileObject::fgetcsv() example

    <?php
    $file = new SplFileObject("data.csv");
    while (!$file->eof()) {
        var_dump($file->fgetcsv());
    }
    ?>

示例 #2 `SplFileObject::READ_CSV` example

    <?php
    $file = new SplFileObject("animals.csv");
    $file->setFlags(SplFileObject::READ_CSV);
    foreach ($file as $row) {
        list($animal, $class, $legs) = $row;
        printf("A %s is a %s with %d legs\n", $animal, $class, $legs);
    }
    ?>

Contents of animals.csv

    crocodile,reptile,4
    dolphin,mammal,0
    duck,bird,2
    koala,mammal,4
    salmon,fish,0

以上示例的输出类似于：

    A crocodile is a reptile with 4 legs
    A dolphin is a mammal with 0 legs
    A duck is a bird with 2 legs
    A koala is a mammal with 4 legs
    A salmon is a fish with 0 legs

### 参见

- 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
- SplFileObject::setFlags() - Sets flags for the SplFileObject
- `SplFileObject::READ_CSV`
- SplFileObject::current() - Retrieve current line of file
- fputcsv() - 将行格式化为 CSV 并写入文件指针
- fgetcsv() - 从文件指针中读入一行并解析 CSV 字段
- str_getcsv() - 解析 CSV 字符串为一个数组

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