fputcsv
行を CSV 形式にフォーマットし、ファイルポインタに書き込む
説明
intfalse fputcsv(
resource $stream
,
array $fields
,
string $separator
= ",",
string $enclosure
= "\"",
string $escape
= "\\",
string $eol
= "\n"
)
パラメータ
-
stream
-
ファイルポインタは、有効なファイルポインタである必要があり、
fopen または fsockopen で正常にオープンされた
(そしてまだ fclose でクローズされていない)
ファイルを指している必要があります。
-
fields
-
文字列の配列。
-
separator
-
separator
パラメータで、フィールドのデリミタを設定します。
シングルバイト文字 1 文字のみでなければなりません。
-
enclosure
-
オプションの enclosure
パラメータで、フィールド囲いこみ文字を設定します。
シングルバイト文字 1 文字のみでなければなりません。
-
escape
-
オプションの escape
パラメータで、エスケープ文字を設定します。
シングルバイト文字 1 文字のみ、または空文字列でなければなりません。
空文字列(""
) を指定すると、(RFC 4180 に準拠していない) 独自仕様のエスケープ機構が無効になります。
注意:
enclosure
の文字は、フィールド内で2回出力される
ことでエスケープされます。しかし、
escape
文字はその代替として使えます。
デフォルトのパラメータの値
""
と \"
は同じ意味を持ちます。
enclosure
の文字を
escape
文字でエスケープすることには、
特別な意味はありません。それ自身をエスケープする意味ですらありません。
警告
PHP 8.4.0 以降では、escape
のデフォルト値に依存することは非推奨となりました。
位置指定の引数か、名前付き引数
を使用して明示的に指定する必要があります。
-
eol
-
eol
は、
カスタムの行末シーケンスを設定するオプションの引数です。
警告
escape
が空の文字列(""
)以外に設定されているとき、
» RFC 4180
に準拠しない CSV が生成されたり、PHP の CSV
関数を介してラウンドトリップ(往復変換)でデータが壊れる可能性があります。
escape
のデフォルト値は"\\"
なので、明示的に空の文字列を指定することを推奨します。デフォルト値は、PHP 9.0
以降の将来のバージョンで変更予定です。
注意:
enclosure
がフィールド内に含まれる場合は、同じ文字を二度続けることでエスケープします。
ただし、その直前に escape
がある場合は別です。
戻り値
書き込んだ文字列の長さを返します。失敗した場合に false
を返します。
エラー / 例外
separator
または enclosure
が
1 バイト長ではない場合、ValueError をスローします。
escape
が 1 バイト長、または空文字列ではない場合、
ValueError をスローします。
例
例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"""
参考
- fgetcsv
- str_getcsv
- SplFileObject::fgetcsv
- SplFileObject::fputcsv
- SplFileObject::setCsvControl
- SplFileObject::getCsvControl