【PHP8.x】CURLOPT_WRITEFUNCTION定数の使い方

Copy
1<?php
2
3/**
4 * CURLOP_WRITEFUNCTION の使用例
5 *
6 * CURLOPT_WRITEFUNCTION は、cURL がリモートからデータを受信するたびに呼び出される
7 * コールバック関数を設定するために使用します。この関数を使うことで、受信したデータを
8 * メモリに直接保存したり、ファイルに書き込んだり、リアルタイムで処理したりできます。
9 *
10 * この例では、取得したウェブページのコンテンツを `$receivedData` 変数に蓄積します。
11 *
12 * @param string $url データを取得するURL
13 * @return void
14 */
15function fetchDataWithWriteFunction(string $url): void
16{
17    // cURL リソースを初期化
18    $ch = curl_init();
19
20    if ($ch === false) {
21        echo "cURL の初期化に失敗しました。\n";
22        return;
23    }
24
25    // 受信したデータを格納するための変数
26    $receivedData = '';
27
28    // 取得するURLを設定
29    curl_setopt($ch, CURLOPT_URL, $url);
30
31    // ヘッダーをレスポンスに含めない
32    curl_setopt($ch, CURLOPT_HEADER, false);
33
34    // CURLOPT_WRITEFUNCTION を設定し、コールバック関数を指定
35    // クロージャ（無名関数）を使用し、use キーワードで $receivedData 変数をキャプチャ（参照渡し）
36    curl_setopt($ch, CURLOPT_WRITEFUNCTION, function ($curl_resource, $data_chunk) use (&$receivedData) {
37        // 受信したデータのチャンクを $receivedData に追加
38        $receivedData .= $data_chunk;
39
40        // cURL に対して、受信したデータのバイト数を返さなければならない
41        // これを返さないと、cURL はエラーとみなし処理を停止することがあります
42        return strlen($data_chunk);
43    });
44
45    // CURLOPT_RETURNTRANSFER は、CURLOPT_WRITEFUNCTION と組み合わせて使う場合、
46    // 通常は false にするか、設定しない（デフォルトが false）のが適切です。
47    // true にすると、curl_exec() がデータを返そうとし、CURLOPT_WRITEFUNCTION
48    // との挙動が衝突する可能性があります。
49    // curl_setopt($ch, CURLOPT_RETURNTRANSFER, false); // 明示的に指定することも可能
50
51    // cURL セッションを実行
52    $result = curl_exec($ch);
53
54    // エラーチェック
55    if (curl_errno($ch)) {
56        echo 'cURL エラーが発生しました: ' . curl_error($ch) . "\n";
57    } else {
58        echo "cURL リクエストが成功しました。\n";
59        echo "受信データの一部 (最初の500文字):\n";
60        // HTMLコンテンツとして安全に出力するために htmlspecialchars を使用
61        echo htmlspecialchars(substr($receivedData, 0, 500)) . "...\n";
62        echo "受信データの合計バイト数: " . strlen($receivedData) . " バイト\n";
63    }
64
65    // cURL セッションを閉じる
66    curl_close($ch);
67}
68
69// 使用例：http://example.com からデータを取得
70// このURLはテストやドキュメント目的で利用されることが想定されているため、安全です。
71fetchDataWithWriteFunction("http://example.com");
72
73?>

CURLOPT_WRITEFUNCTIONは、PHPのcURL拡張機能でリモートからデータを受信する際に、そのデータをどのように処理するかをカスタマイズするための定数です。これを使用することで、cURLがウェブページなどのデータを少しずつ受信するたびに、指定した関数（コールバック関数）を呼び出すように設定できます。これにより、受信したデータをリアルタイムで処理したり、メモリ上の変数に直接蓄積したり、ファイルに書き込んだりすることが可能になります。

設定するコールバック関数は、二つの引数を受け取ります。一つ目はcURLリソース自体、二つ目は実際に受信したデータの塊（チャンク）です。この関数の中で、受信した$data_chunkを$receivedData変数に連結して蓄積する処理などを行います。コールバック関数は、処理したデータのバイト数（通常はstrlen($data_chunk)）をcURLに返す必要があります。この戻り値を正しく返さないと、cURLがエラーとみなし、処理が中断される可能性がありますので注意が必要です。

このサンプルコードでは、http://example.comから取得したデータを$receivedDataという変数に順次追加していきます。CURLOPT_WRITEFUNCTIONを設定する場合、curl_exec()がデータを文字列として返そうとするCURLOPT_RETURNTRANSFERは通常falseにするか、設定しない（デフォルトがfalse）のが適切です。これにより、データ処理の責務がCURLOPT_WRITEFUNCTIONに集中し、意図しない挙動を防ぎます。最後に、蓄積されたデータの最初の部分と合計バイト数を出力して、機能が正常に動作したことを確認しています。

Copy
1<?php
2
3/**
4 * CURLOPT_WRITEFUNCTION を使用して、指定されたURLのコンテンツを取得する関数。
5 * この関数は、cURLが受信したデータをカスタムのコールバック関数で処理する方法を示します。
6 *
7 * @param string $url 取得するURL。
8 * @return string|false 成功した場合は取得したコンテンツ、失敗した場合は false を返します。
9 */
10function fetchContentWithCustomWriteFunction(string $url): string|false
11{
12    // cURLセッションを初期化します
13    $ch = curl_init();
14
15    // cURLリソースが正しく初期化されたか確認します
16    if ($ch === false) {
17        error_log("cURLセッションの初期化に失敗しました。");
18        return false;
19    }
20
21    // ダウンロードしたデータを格納するための変数を準備します
22    // この変数は、CURLOPT_WRITEFUNCTIONで設定するコールバック関数内で更新されます。
23    $receivedContent = '';
24
25    // cURLオプションを設定します
26    // 1. 取得するURLを設定します
27    curl_setopt($ch, CURLOPT_URL, $url);
28
29    // 2. レスポンスボディを curl_exec の戻り値として直接返さず、
30    //    CURLOPT_WRITEFUNCTION で設定するコールバック関数に渡すようにします。
31    //    これが CURLOPT_WRITEFUNCTION を機能させるために重要です。
32    curl_setopt($ch, CURLOPT_RETURNTRANSFER, false);
33
34    // 3. HTTPヘッダーをレスポンスに含めないように設定します。
35    curl_setopt($ch, CURLOPT_HEADER, false);
36
37    // 4. CURLOPT_WRITEFUNCTION を設定します。
38    //    これは、cURLがデータを受信するたびに呼び出されるコールバック関数です。
39    //    コールバック関数は、cURLリソースと受信したデータチャンクを引数に取ります。
40    //    &receivedContent はクロージャの「use」によって、外側のスコープの $receivedContent 変数を参照（&$receivedContent）できるようにします。
41    curl_setopt($ch, CURLOPT_WRITEFUNCTION, function (
42        /** @var resource $curl_handle */ $curl_handle,
43        /** @var string $data */ $data
44    ) use (&$receivedContent): int {
45        // 受信したデータチャンクを $receivedContent に追記します。
46        $receivedContent .= $data;
47        // cURLに対して、処理したデータのバイト数を返します。
48        // これが受信したデータのバイト数と異なる場合、または0の場合、cURLは転送をエラーと判断します。
49        return strlen($data);
50    });
51
52    // cURLセッションを実行し、HTTPリクエストを送信します。
53    // CURLOPT_RETURNTRANSFER が false なので、$success は成功/失敗の真偽値になります。
54    $success = curl_exec($ch);
55
56    // cURLの実行が失敗したかチェックします
57    if ($success === false) {
58        $error_message = curl_error($ch); // エラーメッセージを取得
59        $error_code = curl_errno($ch);   // エラーコードを取得
60        error_log("cURLエラーが発生しました: [{$error_code}] {$error_message}");
61        curl_close($ch); // エラーの場合もcURLセッションを閉じます
62        return false;
63    }
64
65    // cURLセッションを閉じ、リソースを解放します。
66    curl_close($ch);
67
68    // カスタムの書き込み関数によって取得されたコンテンツを返します。
69    return $receivedContent;
70}
71
72// --- 使用例 ---
73// 実際にアクセス可能なURLを指定してください。
74$targetUrl = 'https://www.example.com/';
75
76echo "{$targetUrl} から CURLOPT_WRITEFUNCTION を使用してコンテンツを取得します...\n";
77
78// 関数を呼び出してコンテンツを取得します
79$content = fetchContentWithCustomWriteFunction($targetUrl);
80
81if ($content !== false) {
82    echo "コンテンツの取得に成功しました。合計サイズ: " . strlen($content) . " バイト。\n";
83    echo "--- コンテンツの最初の200文字 ---\n";
84    // マルチバイト文字列にも対応するため mb_substr を使用
85    echo mb_substr($content, 0, 200, 'UTF-8') . "...\n";
86    echo "-------------------------------------------\n";
87} else {
88    echo "コンテンツの取得に失敗しました。\n";
89}

CURLOPT_WRITEFUNCTIONは、PHPのcURL拡張機能において、ネットワークからデータを受信する際に、その受信データをどのように処理するかを定義するカスタム関数（コールバック関数）を指定するための定数です。このサンプルコードは、指定されたURLのコンテンツを、標準的なcURLの戻り値として直接受け取るのではなく、CURLOPT_WRITEFUNCTIONに設定した独自の関数で段階的に収集する方法を示しています。

まず、curl_init()でcURLセッションを初期化し、CURLOPT_URLでアクセスするURLを設定します。次に、CURLOPT_RETURNTRANSFERをfalseに設定することが重要です。これにより、curl_exec()がデータの文字列を直接返すのではなく、CURLOPT_WRITEFUNCTIONで指定された関数にデータが渡されるようになります。

CURLOPT_WRITEFUNCTIONには匿名関数が設定されています。この関数は、cURLがデータの一部を受信するたびに自動的に呼び出されます。匿名関数は二つの引数を受け取ります。一つ目はcURLリソース、二つ目は実際に受信したデータの一部（チャンク）です。use (&$receivedContent)構文によって、関数外で定義された$receivedContent変数に、受信したデータチャンクを順次追記していきます。このコールバック関数は、処理したデータのバイト数を返す必要があり、これによりcURLはデータ処理が成功したと判断します。

最後にcurl_exec()を実行すると、CURLOPT_WRITEFUNCTIONで設定された関数が何度も呼び出され、最終的に$receivedContent変数に完全なコンテンツが格納されます。エラーが発生した場合はcurl_error()で詳細を確認し、処理が完了したらcurl_close()でリソースを解放します。この方法により、例えば非常に大きなデータを扱う際に、メモリ使用量を抑えながらデータを処理するような、より柔軟な制御が可能となります。