PHP マニュアル: フィールドの配列を CSV の行として書き出す

説明

public intfalse SplFileObject::fputcsv(
    array $fields,
    string $separator = ",",
    string $enclosure = "\"",
    string $escape = "\\",
    string $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"""

参考

SplFileObject::fgetcsv
SplFileObject::setCsvControl
SplFileObject::getCsvControl
fputcsv
fgetcsv
str_getcsv