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

Copy
1<?php
2
3/**
4 * CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE の使用例。
5 *
6 * この定数は、curl_multi_setopt() とともに使用され、
7 * Content-Length ヘッダのサイズが実際のダウンロードサイズと異なる場合に、
8 * 許容される誤差の最大値（バイト単位）を設定します。
9 * この値を超える誤差がある場合、その接続は「不良」とみなされる可能性があります。
10 *
11 * @param int $penaltySize 許容されるContent-Lengthの誤差（バイト単位）。
12 *                         デフォルトは0（誤差を許容しない）。
13 * @return void
14 */
15function demonstrateCurlContentLengthPenalty(int $penaltySize = 1024): void
16{
17    // cURLマルチハンドルを初期化します。
18    $mh = curl_multi_init();
19
20    // 複数のcURLハンドルを初期化します。
21    // 例として、ダミーのURLを使用します。実際には複数の異なるURLを設定できます。
22    $ch1 = curl_init('http://example.com/');
23    $ch2 = curl_init('http://www.php.net/');
24
25    // 個々のcURLハンドルにオプションを設定します。
26    // CURLOPT_RETURNTRANSFER: 実行結果を文字列で返すようにします。
27    curl_setopt($ch1, CURLOPT_RETURNTRANSFER, true);
28    curl_setopt($ch2, CURLOPT_RETURNTRANSFER, true);
29
30    // 個々のハンドルをマルチハンドルに追加します。
31    curl_multi_add_handle($mh, $ch1);
32    curl_multi_add_handle($mh, $ch2);
33
34    // CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE オプションを設定します。
35    // ここで設定した値（$penaltySize）は、Content-Lengthが実際のサイズと
36    // 異なっていても許容される最大の誤差です。
37    // 例えば、1024 を設定すると、Content-Lengthが1KBずれていても有効とみなされます。
38    curl_multi_setopt($mh, CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE, $penaltySize);
39
40    echo "CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE が " . $penaltySize . " バイトに設定されました。\n";
41    echo "これは、Content-Lengthが最大でこの値の誤差を許容することを示します。\n\n";
42
43    // すべてのリクエストが完了するまでcURLマルチハンドルを実行します。
44    $running = null;
45    do {
46        $mrc = curl_multi_exec($mh, $running);
47        // activityを待つことでCPU使用率を低減します。
48        if ($running > 0) {
49            curl_multi_select($mh);
50        }
51    } while ($running > 0 && $mrc == CURLM_OK);
52
53    // 各ハンドルの結果を取得し、エラーを確認します。
54    $result1 = curl_multi_getcontent($ch1);
55    $error1 = curl_error($ch1);
56
57    $result2 = curl_multi_getcontent($ch2);
58    $error2 = curl_error($ch2);
59
60    echo "--- リクエスト結果 ---\n";
61
62    if ($error1) {
63        echo "ch1 (http://example.com/) の取得中にエラーが発生しました: " . $error1 . "\n";
64    } else {
65        echo "ch1 (http://example.com/) のコンテンツを成功裏に取得しました (長さ: " . strlen($result1) . " バイト)。\n";
66    }
67
68    if ($error2) {
69        echo "ch2 (http://www.php.net/) の取得中にエラーが発生しました: " . $error2 . "\n";
70    } else {
71        echo "ch2 (http://www.php.net/) のコンテンツを成功裏に取得しました (長さ: " . strlen($result2) . " バイト)。\n";
72    }
73
74    // 個々のcURLハンドルをマルチハンドルから削除し、閉じます。
75    curl_multi_remove_handle($mh, $ch1);
76    curl_close($ch1);
77
78    curl_multi_remove_handle($mh, $ch2);
79    curl_close($ch2);
80
81    // cURLマルチハンドルを閉じます。
82    curl_multi_close($mh);
83}
84
85// 関数を実行してデモンストレーションを行います。
86demonstrateCurlContentLengthPenalty();
87
88?>

CURLMOPT_CONTENT_LENGTH_PENALTY_SIZEは、PHPのcURL拡張機能を用いてHTTP通信を行う際に使用される定数です。この定数は、複数のダウンロード処理を効率的に行うためのcurl_multi_setopt()関数と組み合わせて使われます。その主な役割は、ウェブサーバーが示すコンテンツの予想されるサイズ（Content-Lengthヘッダで提供される情報）と、実際にダウンロードされたデータのサイズとの間に、どの程度の誤差を許容するかをバイト単位で設定することです。

具体的には、この定数に整数値（int型）を設定することで、Content-Lengthが実際のダウンロードサイズと設定した値の範囲内で異なっていても、cURLはそのダウンロードを正常とみなすことができます。例えば、1024を設定すれば、最大1KBまでのサイズ誤差は許容されます。もしこの許容範囲を超える誤差があった場合、cURLはそのダウンロードデータが不完全である可能性を判断する基準の一つとなります。

サンプルコードでは、curl_multi_init()で作成したマルチハンドルに対し、curl_multi_setopt($mh, CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE, $penaltySize);のように設定しています。定数自体は引数を持ちませんが、curl_multi_setopt()の第三引数として渡される$penaltySizeが、許容する誤差の具体的な値を指定します。これにより、ネットワークの不安定さなどによるわずかなサイズ差異でダウンロードが不成功と判定されるのを防ぎ、より堅牢なデータ取得処理を構築できるようになります。

Copy
1<?php
2
3/**
4 * CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE オプションを設定し、
5 * マルチcURLハンドラを使用して簡単なHTTPリクエストを実行する例。
6 *
7 * このオプションは、HTTP/2接続においてContent-Lengthヘッダの値が
8 * 不正確な場合に、libcurlが課すペナルティサイズ（バイト単位）を制御します。
9 * 主に、特定の条件下でのHTTP/2のパフォーマンスチューニングに利用されます。
10 * システムエンジニアを目指す初心者の方は、マルチcURLの基本的な使い方と
11 * オプション設定の方法を理解する上で参考にしてください。
12 */
13function demonstrateCurlMultiPenaltySizeOption(): void
14{
15    echo "--- PHP cURL Multi Penalty Size Example ---\n\n";
16
17    // 1. マルチcURLハンドラを初期化します。
18    //    これは複数のcURLリクエストを並行して管理するためのコンテナです。
19    $mh = curl_multi_init();
20    if ($mh === false) {
21        echo "エラー: マルチcURLハンドラの初期化に失敗しました。\n";
22        return;
23    }
24    echo "マルチcURLハンドラを初期化しました。\n";
25
26    // 2. CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE オプションを設定します。
27    //    この例では、ペナルティサイズを200バイトに設定します。
28    //    デフォルト値は100バイトで、-1を設定するとこの機能は無効になります。
29    $penaltySize = 200; // 例として200バイトに設定
30    if (curl_multi_setopt($mh, CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE, $penaltySize)) {
31        echo "CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE を {$penaltySize} バイトに設定しました。\n";
32    } else {
33        echo "エラー: CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE の設定に失敗しました。\n";
34        curl_multi_close($mh);
35        return;
36    }
37
38    // 3. 個別のcURLハンドラを作成し、マルチハンドラに追加します。
39    //    ここでは、例として2つのウェブサイトにリクエストを送ります。
40    $ch1 = curl_init("https://www.example.com/");
41    $ch2 = curl_init("https://www.google.com/");
42
43    if ($ch1 === false || $ch2 === false) {
44        echo "エラー: 個別のcURLハンドラの初期化に失敗しました。\n";
45        curl_multi_close($mh);
46        return;
47    }
48
49    // リクエスト結果を文字列として返すように設定
50    curl_setopt($ch1, CURLOPT_RETURNTRANSFER, true);
51    curl_setopt($ch2, CURLOPT_RETURNTRANSFER, true);
52
53    // 個別のハンドラをマルチハンドラに追加
54    curl_multi_add_handle($mh, $ch1);
55    curl_multi_add_handle($mh, $ch2);
56    echo "2つのcURLハンドラ（example.com, google.com）をマルチハンドラに追加しました。\n";
57
58    // 4. マルチcURLリクエストを実行します。
59    //    すべてのリクエストが完了するまでループします。
60    $active = null; // 現在アクティブなハンドラの数を格納する変数
61
62    // curl_multi_exec を呼び出し、最初の実行を行います。
63    // CURLM_CALL_MULTI_PERFORM が返される間は、処理を継続する必要があります。
64    do {
65        $mrc = curl_multi_exec($mh, $active);
66    } while ($mrc === CURLM_CALL_MULTI_PERFORM);
67
68    // すべてのリクエストが終了するまで待機します。
69    while ($active && $mrc === CURLM_OK) {
70        // 新しいデータが利用可能になるまで待機します（最大0.5秒）
71        if (curl_multi_select($mh, 0.5) !== -1) {
72            // データが利用可能になったら再度実行
73            do {
74                $mrc = curl_multi_exec($mh, $active);
75            } while ($mrc === CURLM_CALL_MULTI_PERFORM);
76        }
77    }
78    echo "\nすべてのマルチcURLリクエストの実行が完了しました。\n";
79
80    // 5. 各cURLハンドルの結果を取得し、表示します。
81    if (curl_errno($ch1) === 0) {
82        echo "\nexample.com からの応答（最初の100文字）: " . substr(curl_multi_getcontent($ch1), 0, 100) . "...\n";
83    } else {
84        echo "\nexample.com の取得中にエラーが発生しました: " . curl_error($ch1) . "\n";
85    }
86
87    if (curl_errno($ch2) === 0) {
88        echo "google.com からの応答（最初の100文字）: " . substr(curl_multi_getcontent($ch2), 0, 100) . "...\n";
89    } else {
90        echo "google.com の取得中にエラーが発生しました: " . curl_error($ch2) . "\n";
91    }
92
93    // 6. cURLハンドラのクリーンアップを行います。
94    curl_multi_remove_handle($mh, $ch1);
95    curl_multi_remove_handle($mh, $ch2);
96    curl_close($ch1);
97    curl_close($ch2);
98    echo "\n個別のcURLハンドラをクリーンアップしました。\n";
99
100    // 7. マルチcURLハンドラのクリーンアップを行います。
101    curl_multi_close($mh);
102    echo "マルチcURLハンドラをクローズしました。\n";
103
104    echo "\n--- サンプルコード終了 ---\n";
105}
106
107// 関数を実行します。
108demonstrateCurlMultiPenaltySizeOption();

CURLMOPT_CONTENT_LENGTH_PENALTY_SIZEはPHPのcURL拡張機能で利用される定数で、HTTP/2プロトコルにおいてContent-Lengthヘッダの値が正確でない場合に、libcurlが適用するペナルティサイズ（バイト単位）を制御します。この定数は整数型（int）の値をとり、デフォルトは100バイトですが、-1を設定するとこの機能は無効になります。主にHTTP/2通信の特定のパフォーマンス調整に用いられます。

このサンプルコードは、複数のHTTPリクエストを並行して処理する「マルチcURLハンドラ」の基本的な使い方を示しながら、CURLMOPT_CONTENT_LENGTH_PENALTY_SIZEオプションの設定例を紹介しています。まず、curl_multi_init()関数で複数のcURLリクエストを管理するマルチハンドラを初期化します。次に、curl_multi_setopt()関数を使って、このマルチハンドラに対してCURLMOPT_CONTENT_LENGTH_PENALTY_SIZEを200バイトに設定しています。

その後、curl_init()で個別のcURLハンドラを作成し、それぞれをcurl_multi_add_handle()でマルチハンドラに追加します。実際のHTTPリクエストの実行はcurl_multi_exec()関数とcurl_multi_select()関数を組み合わせて行われ、CURLM_CALL_MULTI_PERFORMが返される間は処理を継続する必要があります。すべてのリクエストが完了すると、curl_multi_getcontent()で各リクエストの結果を取得できます。最後に、curl_multi_remove_handle()やcurl_close()、curl_multi_close()を使用して、作成したcURLリソースを適切に解放しています。

システムエンジニアを目指す初心者の方にとって、このコードはマルチcURLを使った並行リクエストの処理方法と、cURLの挙動を細かく制御するためのオプション設定の一例として、理解を深めるのに役立つでしょう。