【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 *
6 * この関数は、fputcsv の $enclosure 引数を空文字列''に設定することで、
7 * CSVフィールドをダブルクォーテーションで囲まないようにします。
8 *
9 * 注意点:
10 * - この設定では、フィールド内に区切り文字（デフォルトはカンマ）が含まれる場合、
11 *   CSVの構造が崩れ、異なる列として解釈される可能性があります。
12 *   例: '商品B, Cに関する情報' は '商品B' と ' Cに関する情報' のように分割される可能性があります。
13 * - また、データ内に本来のダブルクォーテーションが含まれていても、エスケープされずにそのまま出力されます。
14 *   これらの影響を理解した上で使用してください。
15 *
16 * @param array $data 書き込むデータの配列。各要素は行を表す配列である必要があります。
17 * @param array $headers (オプション) CSVのヘッダー行。指定しない場合は出力されません。
18 * @param string $separator (オプション) フィールドの区切り文字。デフォルトはカンマです。
19 * @return string 生成されたCSVデータ。
20 * @throws RuntimeException メモリファイルハンドルのオープンに失敗した場合にスローされます。
21 */
22function generateCsvWithoutEnclosure(
23    array $data,
24    array $headers = [],
25    string $separator = ','
26): string {
27    // メモリ上の読み書き可能なファイルハンドルを作成します。
28    // これにより、実際のファイルを作成せずにCSVデータをメモリ上で操作できます。
29    $handle = fopen('php://memory', 'r+');
30
31    if ($handle === false) {
32        // php://memory のオープン失敗は稀ですが、エラー処理を追加します。
33        throw new RuntimeException("メモリファイルハンドルのオープンに失敗しました。");
34    }
35
36    // ヘッダーが指定されている場合、最初に書き込みます。
37    if (!empty($headers)) {
38        // fputcsvの第4引数($enclosure)を空文字列''に設定することで、
39        // フィールドをダブルクォーテーションで囲まないようにします。
40        fputcsv($handle, $headers, $separator, '');
41    }
42
43    // データを行ごとに書き込みます。
44    foreach ($data as $row) {
45        // 各行もダブルクォーテーションで囲まない設定で書き込みます。
46        fputcsv($handle, $row, $separator, '');
47    }
48
49    // ファイルポインタを先頭に戻し、書き込まれた内容を全て読み込みます。
50    rewind($handle);
51    $csvContent = stream_get_contents($handle);
52
53    // ファイルハンドルを閉じます。
54    fclose($handle);
55
56    return $csvContent;
57}
58
59// サンプルデータ
60$sampleData = [
61    [1, '山田 太郎', '商品Aに関する情報'],
62    [2, '田中 花子', '商品B, Cに関する情報'], // フィールド内にカンマが含まれる場合の挙動に注意
63    [3, '鈴木 次郎', '商品Dの情報'],
64    [4, '高橋 健太', '"引用符"を含むデータ'] // データ自体に引用符が含まれてもそのまま出力される
65];
66
67// CSVヘッダー
68$csvHeaders = ['ID', '名前', '説明'];
69
70// ダブルクォーテーションで囲まないCSVデータを生成します。
71$generatedCsv = generateCsvWithoutEnclosure($sampleData, $csvHeaders);
72
73// 生成されたCSVデータを出力します。
74echo $generatedCsv;

PHPのfputcsv関数は、指定されたデータをCSV（Comma Separated Values）形式でファイルやストリームに書き込む際に使用されます。この関数は、表形式のデータを手軽にCSVファイルとして出力したい場合に非常に便利です。

主な引数として、まず$streamには書き込み先のファイルハンドル（fopenなどで開いたもの）を指定します。次に$fieldsには、1行分のデータを要素として持つ配列を渡します。例えば['ID', '名前']のような形です。$separatorはフィールド間の区切り文字を指定し、デフォルトはカンマ「,」です。

特に重要なのが$enclosure引数で、これはフィールド内の区切り文字や改行文字がデータに含まれる場合に、そのフィールド全体を囲むための文字を指定します。デフォルトではダブルクォーテーション「"」が使用され、これによってCSVの構造が保たれます。サンプルコードでは、この$enclosure引数を空文字列''に設定することで、各フィールドがダブルクォーテーションで囲まれないCSVデータを生成しています。これにより、データがそのままの形で出力されますが、注意が必要です。例えば、フィールド内に区切り文字（デフォルトはカンマ）が含まれると、そのフィールドが意図せず複数の列に分割されてしまう可能性があります。また、データ自体に本来のダブルクォーテーションが含まれていてもエスケープされず、そのまま出力されます。これらの挙動を理解した上で、用途に応じて設定を検討してください。$escape引数は$enclosure文字そのものがデータに含まれる場合にエスケープする文字、$eolは行末の文字を指定します。

fputcsv関数の戻り値は、書き込みが成功した場合は書き込まれたバイト数を示す整数、失敗した場合はfalseを返します。サンプルコードでは、php://memoryという特殊なストリームを使用し、実際のファイルを作成せずにメモリ上でCSVデータを生成し、その内容を文字列として取得しています。この方法は、一時的なCSVデータを生成するのに役立ちます。

Copy
1<?php
2
3/**
4 * fputcsv 関数を使用して CSV ファイルにデータを書き込むサンプルです。
5 * 特に「囲み文字」（enclosure）の指定方法と働きに焦点を当てています。
6 *
7 * CSVでは、フィールド内に区切り文字（例: カンマ）や囲み文字自体が含まれる場合、
8 * そのフィールド全体を囲み文字で囲み、囲み文字自体はエスケープします。
9 */
10function writeCsvWithCustomEnclosure(): void
11{
12    // 書き込み対象のファイル名
13    $filename = 'output_with_enclosure.csv';
14
15    // CSVとして書き込むデータ
16    // 3番目の要素にカンマや引用符が含まれていることに注目してください。
17    $data = [
18        ['名前', '年齢', '趣味'],
19        ['山田 太郎', '30', '読書, 映画鑑賞'], // 趣味にカンマが含まれる
20        ['鈴木 花子', '25', '旅行"巡り", 料理'], // 趣味にダブルクォートが含まれる
21        ['田中 次郎', '40', 'プログラミング'],
22    ];
23
24    // ファイルを書き込みモード ('w') で開きます。
25    // ファイルが存在しない場合は作成され、存在する場合は内容がクリアされます。
26    $fileStream = fopen($filename, 'w');
27
28    // ファイルオープンに失敗した場合のエラーハンドリング
29    if ($fileStream === false) {
30        echo "エラー: ファイル '{$filename}' のオープンに失敗しました。\n";
31        return;
32    }
33
34    // fputcsv の引数を定義します。
35    $separator = ',';    // フィールドを区切る文字 (例: カンマ)
36    $enclosure = '"';    // フィールドを囲む文字 (例: ダブルクォート)
37    $escape = '\\';      // 囲み文字をエスケープする文字 (例: バックスラッシュ)
38    $eol = "\n";         // 行の終端文字 (例: 改行)
39
40    // 各データ行を CSV 形式でファイルに書き込みます。
41    foreach ($data as $fields) {
42        // fputcsv 関数で1行分のデータを CSV 形式で書き込みます。
43        // ここでは、明示的に囲み文字 ($enclosure) を指定しています。
44        $result = fputcsv($fileStream, $fields, $separator, $enclosure, $escape, $eol);
45
46        // 書き込みに失敗した場合のエラーハンドリング
47        if ($result === false) {
48            echo "エラー: CSVデータの書き込み中に問題が発生しました。\n";
49            fclose($fileStream); // ファイルを閉じます
50            return;
51        }
52    }
53
54    // すべてのデータ書き込み後、ファイルを閉じます。
55    fclose($fileStream);
56
57    echo "CSVファイル '{$filename}' が正常に作成されました。\n";
58    echo "ファイルの内容を確認してください。\n";
59}
60
61// 関数を実行して、CSV ファイルを生成します。
62writeCsvWithCustomEnclosure();

PHPのfputcsv関数は、配列のデータをCSV（Comma Separated Values）形式でファイルに書き込むために使用されます。このサンプルコードは、特に「囲み文字」（enclosure）の指定と、それがデータ書き込みにどう影響するかを学ぶのに役立ちます。

コードではまず、fopen関数で出力ファイルoutput_with_enclosure.csvを書き込みモードで開きます。その後、定義されたデータ配列をforeachループで1行ずつ処理し、各行をfputcsv関数でファイルに書き込んでいます。

fputcsv関数の主な引数は以下の通りです。

• $stream: 書き込み先のファイルストリームを指定します。
• $fields: CSVの1行として書き込むデータを配列で渡します。
• $separator: 各フィールドを区切る文字です。通常はカンマ (,) を使います。
• $enclosure: フィールド内に区切り文字や囲み文字自体が含まれる場合に、そのフィールド全体を囲む文字です。サンプルではダブルクォート (") を使用しています。fputcsvはこのルールを自動的に適用し、必要に応じてフィールドを囲みます。
• $escape: 囲み文字自体がフィールド内に出現した場合に、その囲み文字をエスケープする文字です。
• $eol: 行の終端を示す文字です。通常は改行コード (\n) を使用します。

fputcsvは、書き込みが成功すると書き込まれたバイト数を整数値で返し、失敗した場合はfalseを返します。このサンプルを実行すると、output_with_enclosure.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ファイルが意図通りに作成されているか検証することができます。