fputcsv

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

fputcsv — 将行格式化为 CSV 并写入文件指针

说明

fputcsv(
    resource $stream,
    array $fields,
    string $separator = ",",
    string $enclosure = "\"",
    string $escape = "\\",
    string $eol = "\n"
): int|false

fputcsv() 将一行（传递 fields 数组）格式化为 CSV，并将其写入（以 eol 终止）到指定的 stream。

参数

stream

文件指针必须是有效的，必须指向由 fopen() 或 fsockopen() 成功打开的文件(并还未由 fclose() 关闭)。

fields

string 数组。

separator

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

enclosure

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

escape

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

注意: 通常，在字段内，通过双倍的 enclosure 字符对其进行转义；但是可以使用 escape 字符作为替代。因此，对于默认参数值，"" 和 \" 具有相同的含义。除了允许转义 enclosure 字符外，escape 字符没有特殊含义；甚至不打算转义自身。

警告

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

eol

可选的 eol 参数设置自定义行尾序列。

警告

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

注意:

如果字段中包含 enclosure 字符，则会通过将其双倍 enclosure 来进行转义，除非该字符前面紧接着一个 escape。

返回值

返回写入字符串的长度， 或者在失败时返回 false。

错误／异常

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

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

更新日志

版本 说明
8.4.0 现在已弃用依赖 escape 的默认值。
8.1.0 新增可选的 eol 参数。
7.4.0 escape 参数现在接受空字符串来禁用专有转义机制。

示例

示例 #1 fputcsv() 示例

<?php

$list = [
['aaa', 'bbb', 'ccc', 'dddd'],
['123', '456', '789'],
['"aaa"', '"bbb"']
];

$fp = fopen('file.csv', 'w');

foreach ($list as $fields) {
fputcsv($fp, $fields, ',', '"', '');
}

fclose($fp);
?>

以上示例会写入以下的 file.csv：

aaa,bbb,ccc,dddd
123,456,789
"""aaa""","""bbb"""

参见