(PHP 5 >= 5.4.0, PHP 7, PHP 8)
SplFileObject::fputcsv — フィールドの配列を CSV の行として書き出す
$fields,$separator = ",",$enclosure = "\"",$escape = "\\",$eol = "\n"
fields の配列を、CSV
の行としてファイルに書き出します。
fields値の配列。
separator
フィールドの区切り文字 (シングルバイト文字 1 文字のみ)。
デフォルトはカンマ(,)、 もしくは事前に
SplFileObject::setCsvControl() を呼び出してセットされた値です。
enclosure
フィールド囲み文字 (シングルバイト文字 1 文字のみ)。
デフォルトはダブルクォート(")、もしくは事前に
SplFileObject::setCsvControl() を呼び出してセットされた値です。
escape
エスケープ文字 (シングルバイト文字 最大で1文字)。
デフォルトはバックスラッシュ(\)、 もしくは事前に
SplFileObject::setCsvControl() を呼び出してセットされた値です。
空文字列("")の場合、(RFC 4180 に準拠していない) 独自仕様のエスケープ機構が無効になります。
注意:
enclosureの文字は、フィールド内で2回出力される ことでエスケープされます。しかし、escape文字はその代替として使えます。 デフォルトのパラメータの値""と\"は同じ意味を持ちます。enclosureの文字をescape文字でエスケープすることには、 特別な意味はありません。それ自身をエスケープする意味ですらありません。
PHP 8.4.0 以降では、escape
のデフォルト値に依存することは非推奨となりました。
位置指定の引数か、名前付き引数を使用するか、
あるいは SplFileObject::setCsvControl()
を呼び出して、明示的に指定する必要があります。
eol
eol は、
カスタムの行末シーケンスを設定するオプションの引数です。
escape
が空の文字列("")以外に設定されているとき、
» RFC 4180
に準拠しない CSV が生成されたり、PHP の CSV
関数を介してラウンドトリップ(往復変換)でデータが壊れる可能性があります。
escapeのデフォルト値は"\\"
なので、明示的に空の文字列を指定することを推奨します。デフォルト値は、PHP 9.0
以降の将来のバージョンで変更予定です。
注意:
enclosureがフィールド内に含まれる場合は、同じ文字を二度続けることでエスケープします。 ただし、その直前にescapeがある場合は別です。
escape
が空の文字列("")以外に設定されているとき、
» RFC 4180
に準拠しない CSV が生成されたり、PHP の CSV
関数を介してラウンドトリップ(往復変換)でデータが壊れる可能性があります。
escapeのデフォルト値は"\\"
なので、明示的に空の文字列を指定することを推奨します。デフォルト値は、PHP 9.0
以降の将来のバージョンで変更予定です。
書き出した文字列の長さを返します。失敗した場合に false を返します。
separator または enclosure が
1 バイト長ではない場合、ValueError をスローします。
escape が 1 バイト長、または空文字列ではない場合、
ValueError をスローします。
| バージョン | 説明 |
|---|---|
| 8.4.0 |
escape のデフォルト値に依存することは、
非推奨になりました。
|
| 8.1.0 |
オプションの引数 eol が追加されました。
|
| 7.4.0 |
escape パラメータは空文字列を受け入れるようになりました。
この場合、(RFC 4180 に準拠していない) 独自仕様のエスケープ機構が無効になります。
|
例1 SplFileObject::fputcsv() の例
<?php
$list = array (
array('aaa', 'bbb', 'ccc', 'dddd'),
array('123', '456', '789'),
array('"aaa"', '"bbb"')
);
$file = new SplFileObject('file.csv', 'w');
foreach ($list as $fields) {
$file->fputcsv($fields);
}
?>上の例は、次の内容をファイル file.csv に書き出します。
aaa,bbb,ccc,dddd 123,456,789 """aaa""","""bbb"""