【PHP8.x】fputcsv関数の使い方

Copy
1<?php
2
3/**
4 * fputcsv関数を使用してCSVファイルを生成し、その内容を出力するサンプルコードです。
5 * ダブルクォーテーションやカンマを含む文字列がどのようにCSV形式に変換されるかを示します。
6 */
7function createAndDisplayCsv(): void
8{
9    // CSVデータを一時的にメモリに書き込むためのファイルリソースを開きます。
10    // 'w+'モードは読み書き両用で、ファイルポインタを先頭に設定します。
11    $handle = fopen('php://memory', 'w+');
12
13    if ($handle === false) {
14        echo "エラー: ファイルリソースのオープンに失敗しました。\n";
15        return;
16    }
17
18    // CSVのヘッダー行として使用する配列を定義します。
19    $header = ['ID', '商品名', '詳細説明'];
20
21    // CSVに書き込むデータ行の配列を定義します。
22    // 2番目のデータにはカンマとダブルクォーテーションが含まれており、
23    // fputcsvがこれらを自動的に処理（エンクロージャで囲み、内部のエンクロージャをエスケープ）することを示します。
24    $data = [
25        [1, 'りんご', '新鮮な青森県産。甘くて美味しい！'],
26        [2, 'オレンジ', '輸入柑橘類。酸味と甘みのバランスが良い、「最高品質」です。'],
27        [3, 'バナナ', '高地栽培品。朝食やおやつに最適。'],
28    ];
29
30    // ヘッダー行をCSVに書き込みます。
31    // fputcsvはデフォルトで、フィールド内にカンマやダブルクォーテーションがある場合、
32    // そのフィールドをダブルクォーテーションで囲み（エンクロージャ）、
33    // 内部のダブルクォーテーションを二重化してエスケープします。
34    if (fputcsv($handle, $header) === false) {
35        echo "エラー: ヘッダーの書き込みに失敗しました。\n";
36        fclose($handle);
37        return;
38    }
39
40    // データ行を一つずつCSVに書き込みます。
41    foreach ($data as $row) {
42        if (fputcsv($handle, $row) === false) {
43            echo "エラー: データ行の書き込みに失敗しました。\n";
44            fclose($handle);
45            return;
46        }
47    }
48
49    // ファイルポインタを先頭に戻し、メモリに書き込まれたCSV内容全体を読み込みます。
50    rewind($handle);
51    $csvContent = stream_get_contents($handle);
52
53    // ファイルリソースを閉じ、メモリを解放します。
54    fclose($handle);
55
56    // 生成されたCSV内容を出力します。
57    echo "--- 生成されたCSV内容 ---\n";
58    echo $csvContent;
59    echo "-------------------------\n";
60}
61
62// 関数を実行してCSV生成処理を開始します。
63createAndDisplayCsv();
64
65?>

fputcsv関数は、指定されたファイルリソースに配列のデータをCSV（Comma Separated Values）形式で書き込むPHPの関数です。主にCSVファイルを生成する際に利用されます。

第一引数 $stream には、データを書き込む対象のファイルリソースを指定します。第二引数 $fields には、CSVの一行として書き込むデータが格納された配列を渡します。デフォルトでは、各フィールドはカンマ (,) で区切られ、フィールド内にカンマやダブルクォーテーション (") が含まれる場合は、そのフィールド全体がダブルクォーテーションで囲まれます。また、フィールド内のダブルクォーテーションは二重化 ("") されてエスケープ処理されます。これはCSVの標準的なルールに則った挙動です。 $separator, $enclosure, $escape, $eol といった引数で、これらの区切り文字や囲み文字、エスケープ文字、行末文字をカスタマイズすることも可能です。

戻り値は、書き込んだバイト数を整数 (int) で返しますが、書き込みに失敗した場合は false を返します。

サンプルコードでは、php://memory という特殊なファイルリソースを使用して、一時的にメモリ上にCSVデータを生成しています。createAndDisplayCsv 関数内で、ヘッダーとデータ行を定義し、それぞれ fputcsv 関数で書き込んでいます。特に、商品名「輸入柑橘類。酸味と甘みのバランスが良い、「最高品質」です。」のように、カンマやダブルクォーテーションを含む文字列が指定された場合でも、fputcsv関数が自動的にそのフィールドをダブルクォーテーションで囲み、内部のダブルクォーテーションを二重化して正しくCSV形式に変換していることが確認できます。これにより、CSVファイルを読み込む際にデータが正しく解析されるようになります。最終的に、メモリに書き込まれたCSV内容を読み出して画面に出力しています。

Copy
1<?php
2
3/**
4 * fputcsv関数を使用してCSVデータを一時ファイルに書き込み、その内容を表示します。
5 * この関数は、CSVファイルへの行データの書き込み方法と、改行の挙動を実演します。
6 */
7function writeCsvAndDisplayContent(): void
8{
9    // 一時ファイル（メモリ内）を読み書きモードで開きます。
10    // 'r+' はファイルを読み書き可能で開き、ファイルポインタをファイルの先頭に置きます。
11    $stream = fopen('php://temp', 'r+');
12
13    if ($stream === false) {
14        echo "エラー: ファイルストリームを開けませんでした。\n";
15        return;
16    }
17
18    // CSVに書き込むデータを用意します。
19    $header = ['ID', '名前', '部署', '備考'];
20    $dataRows = [
21        [101, '佐藤 健', '開発部', '新規プロジェクト担当'],
22        [102, '鈴木 花子', '営業部', '東日本エリア担当, 優良顧客'], // カンマを含むデータ
23        [103, '高橋 雄一', '人事部', '採用担当'],
24    ];
25
26    // ヘッダー行をCSVに書き込みます。
27    // fputcsv関数は、引数で指定された各フィールドをデフォルトの区切り文字(カンマ)で区切り、
28    // 行末にデフォルトの改行文字("\n"、すなわちLF)を自動的に追加します。
29    // Windows環境でCRLF ("\r\n") を使用したい場合は、fputcsv($stream, $header, ',', '"', '\\', "\r\n"); のように
30    // 第6引数 (eol) で明示的に指定できます。
31    if (fputcsv($stream, $header) === false) {
32        echo "エラー: ヘッダーの書き込みに失敗しました。\n";
33        fclose($stream);
34        return;
35    }
36
37    // データ行を一つずつCSVに書き込みます。
38    foreach ($dataRows as $row) {
39        if (fputcsv($stream, $row) === false) {
40            echo "エラー: データ行の書き込みに失敗しました。\n";
41            fclose($stream);
42            return;
43        }
44    }
45
46    // ファイルポインタをストリームの先頭に戻します。
47    // これにより、書き込んだ内容を最初から読み出す準備ができます。
48    rewind($stream);
49
50    echo "--- 書き込まれたCSV内容 ---\n";
51    // ストリームの全内容を読み出し、出力します。
52    // fputcsvによって追加された改行もここで確認できます。
53    echo stream_get_contents($stream);
54    echo "--- CSV内容の終わり ---\n";
55
56    // 使用したファイルストリームを閉じます。
57    fclose($stream);
58}
59
60// 関数を実行します。
61writeCsvAndDisplayContent();

fputcsv関数は、PHPで配列のデータをCSV（Comma Separated Values）形式のファイルへ書き込むために使用されます。この関数は、データベースの内容や計算結果などを表形式で出力する際に大変役立ちます。

第一引数 $stream には、データを書き込む先のファイルリソースを指定します。これは、fopen関数などを使って開かれたファイルオブジェクトです。第二引数 $fields には、CSVの一行として書き込みたい各データ項目を要素とする配列を渡します。

fputcsvは、デフォルトでカンマ , を区切り文字、ダブルクォート " を囲み文字として使用し、配列の各要素をこれらのルールに基づいて整形して書き込みます。特に重要な挙動として、各行の書き込みが完了すると、自動的にデフォルトの改行コードであるLF (\n) を行末に追加します。これにより、複数の行を書き込んだ際に、各データ行が正しく新しい行として配置されます。もしWindows環境などでCRLF (\r\n) を使用したい場合は、第六引数 $eol で明示的に改行コードを指定することが可能です。

関数が成功すると、書き込まれたバイト数が整数値として返されます。書き込みに失敗した場合は false が返されます。

提供されたサンプルコードでは、一時ファイルを読み書きモードで開き、fputcsvを使ってヘッダー行と複数のデータ行を書き込んでいます。データ行にはカンマを含む文字列もあり、fputcsvが適切に囲み文字を適用してCSV形式を保っていることがわかります。書き込み後、rewind関数でファイルポインタを先頭に戻し、stream_get_contentsでファイルの内容全体を読み出すことで、fputcsvによって自動的に追加された改行を含んだCSVデータを確認しています。これにより、CSVファイルが意図通りに作成されているか検証することができます。