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

Copy
1<?php
2
3/**
4 * CURL転送中に `CURLPAUSE_ALL` を使用してデータ受信を一時停止するデモンストレーション関数。
5 *
6 * この関数は、大容量ファイルのダウンロード中に `CURLPAUSE_ALL` 定数を利用して、
7 * データ受信を一時的に中断する例を示します。
8 * `CURLPAUSE_ALL` をコールバック関数から返すと、`curl_exec()` は中断され、
9 * PHPスクリプトの実行が再開されます。これにより、レスポンスデータの受信を
10 * 一時的に「待たない」状態を作り出し、その間に他の処理を行うことが可能になります。
11 *
12 * @param string $url ダウンロードするファイルのURL。
13 *                    適切な大きなファイルのダウンロードURLに置き換えてください。
14 *                    例: 'https://speedtest.tele2.net/1MB.zip' (テスト用1MBファイル)
15 *                    例: 'https://www.learningcontainer.com/wp-content/uploads/2020/07/100MB.bin' (テスト用100MBファイル)
16 * @return void
17 */
18function demonstrateCurlPauseAll(string $url): void
19{
20    echo "--- ダウンロード開始 (URL: " . $url . ") ---\n";
21
22    $ch = curl_init();
23    if (!$ch) {
24        echo "CURL初期化エラー\n";
25        return;
26    }
27
28    curl_setopt($ch, CURLOPT_URL, $url);
29    curl_setopt($ch, CURLOPT_HEADER, 0);
30    // 転送されたデータを直接出力せず、WRITEFUNCTIONで処理する
31    curl_setopt($ch, CURLOPT_RETURNTRANSFER, false);
32    // 転送が長時間続かないよう、最大転送時間を設定 (秒)
33    curl_setopt($ch, CURLOPT_TIMEOUT, 60);
34
35    // 受信データを処理するコールバック関数を設定
36    // このコールバックは、データを受信するたびに呼び出されます。
37    curl_setopt($ch, CURLOPT_WRITEFUNCTION, function ($ch_inner, $data) {
38        static $totalReceivedBytes = 0;
39        static $pausedOnce = false; // 一度だけ一時停止するようにフラグを設定
40
41        $receivedBytes = strlen($data);
42        $totalReceivedBytes += $receivedBytes;
43
44        echo "受信中: " . $receivedBytes . "バイト (合計: " . $totalReceivedBytes . "バイト)\n";
45
46        // 初回のみ、一定量のデータを受信したら転送を一時停止する
47        // ここで CURLPAUSE_ALL を返すと、curl_exec() は中断され、
48        // メインスクリプトの実行が再開されます。
49        if (!$pausedOnce && $totalReceivedBytes > 1024 * 50) { // 例: 50KBを受信したら一時停止
50            $pausedOnce = true;
51            echo "--------------------------------------------------\n";
52            echo "!!! CURLPAUSE_ALL を返して転送を一時停止しました !!!\n";
53            echo "!!! メインスクリプトに制御が戻ります。           !!!\n";
54            echo "--------------------------------------------------\n";
55            return CURLPAUSE_ALL; // ここで転送を一時停止し、curl_exec() は true を返す
56        }
57
58        // 通常は、処理したバイト数を返すことで転送を継続します。
59        return $receivedBytes;
60    });
61
62    // 転送を実行
63    // コールバック関数が CURLPAUSE_ALL を返した場合、この curl_exec() は true を返して終了します。
64    // それ以外の場合は、転送が完了するかエラーになるまでブロックします。
65    $execResult = curl_exec($ch);
66
67    if ($execResult === true) {
68        echo "\n--- CURL転送が一時停止により中断され、制御が戻りました ---\n";
69        echo "CURLセッションはまだ開いています。\n";
70        echo "ここで、レスポンスの受信を待たない間に別の処理を実行できます...\n";
71        sleep(3); // 3秒間待機する例
72        echo "別の処理が完了しました。\n";
73
74        // 注意: 単一の curl_exec() で一時停止した後、curl_pause() を使って転送を再開しても、
75        // curl_exec() は既に完了していると見なされるため、自動で転送は続きません。
76        // 実際の転送再開やノンブロッキング処理には `curl_multi_*` 関連の関数が必要です。
77        // このコードは `CURLPAUSE_ALL` が制御をメインスクリプトに戻すことを示しています。
78    } elseif ($execResult === false) {
79        echo "CURL転送エラー: " . curl_error($ch) . "\n";
80    } else {
81        // 通常は、一時停止が発生しなかったか、ファイルが非常に小さかった場合
82        echo "CURL転送が正常に完了しました。\n";
83    }
84
85    curl_close($ch);
86    echo "--- ダウンロード終了 ---\n";
87}
88
89// サンプル使用例
90demonstrateCurlPauseAll('https://speedtest.tele2.net/1MB.zip');

CURLPAUSE_ALLは、PHPのcURL拡張機能で利用できる特別な定数です。この定数は、cURLによるデータ転送中に設定されたコールバック関数（例えば、受信データを処理するCURLOPT_WRITEFUNCTIONなど）の戻り値として使用されることで、現在の転送処理を一時的に中断させる役割を持っています。

コールバック関数がCURLPAUSE_ALLを返すと、現在実行中のcurl_exec()はそこで一時停止し、転送が完了していなくてもtrueを返して終了し、PHPスクリプトのメイン処理に制御が戻ります。これにより、すべてのレスポンスデータが受信されるのを待たずに、その間に別の処理を実行することが可能になります。つまり、「レスポンスを待たない」状態を作り出し、プログラムの柔軟性を高めることができます。

例えば、大量のデータダウンロード中に一定量を受信した時点で一時停止し、その間に別の準備処理を行う、といった用途が考えられます。CURLPAUSE_ALL自体に引数や直接の戻り値はありませんが、コールバック関数の戻り値として使うことで、cURLの実行フローを制御する重要な機能を提供します。一時停止後の転送再開には、curl_multi_*関数群を使ったより詳細な制御が必要になることに留意してください。

Copy
1<?php
2
3/**
4 * Demonstrates the use of CURLPAUSE_ALL constant for pausing and resuming
5 * a cURL transfer within a multi-cURL context.
6 *
7 * This function initiates multiple cURL requests concurrently using curl_multi_* functions.
8 * It then shows how to use `curl_pause` with `CURLPAUSE_ALL` to temporarily halt
9 * a specific cURL transfer, and then `CURLPAUSE_CONT` to resume it.
10 * The `curlm_call_multi_perform` keyword refers to the internal mechanism used by
11 * `curl_multi_exec` for non-blocking operations, which is implicitly demonstrated here
12 * as the multi-cURL loop continues processing other requests even when one is paused.
13 *
14 * This example is designed for beginners to understand the concept of pausing cURL transfers.
15 *
16 * @return void
17 */
18function demonstrateCurlPauseAndResumeInMulti(): void
19{
20    // Ensure the cURL extension is loaded
21    if (!extension_loaded('curl')) {
22        echo "Error: cURL extension is not loaded. Please enable it in your php.ini.\n";
23        return;
24    }
25
26    // URLs to fetch. Using httpbin.org to simulate different response times.
27    // httpbin.org/delay/X waits for X seconds before responding.
28    $urls = [
29        'main_request'   => 'https://httpbin.org/delay/5', // This one will be paused and resumed
30        'other_request1' => 'https://httpbin.org/get',
31        'other_request2' => 'https://httpbin.org/delay/2',
32    ];
33
34    // 1. Initialize a multi cURL handle
35    $mh = curl_multi_init();
36    if ($mh === false) {
37        echo "Error: Failed to initialize multi cURL handle.\n";
38        return;
39    }
40
41    $handles = []; // Array to store individual cURL handles
42    $handleMain = null; // To store the handle we intend to pause/resume
43
44    // 2. Prepare individual cURL handles and add them to the multi handle
45    foreach ($urls as $name => $url) {
46        $ch = curl_init();
47        if ($ch === false) {
48            echo "Error: Failed to initialize cURL handle for {$url}.\n";
49            continue;
50        }
51
52        curl_setopt($ch, CURLOPT_URL, $url);
53        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return the transfer as a string
54        curl_setopt($ch, CURLOPT_HEADER, false);      // Don't include headers in the output
55
56        curl_multi_add_handle($mh, $ch);
57        $handles[$name] = $ch;
58
59        if ($name === 'main_request') {
60            $handleMain = $ch; // Mark this handle for pausing/resuming later
61        }
62
63        echo "Prepared cURL handle for '{$name}': {$url}\n";
64    }
65
66    $active = null; // Will store the number of active cURL handles
67    $isPaused = false; // Flag to track if the main handle is currently paused
68    $pauseTriggered = false; // Flag to ensure pause is triggered only once
69
70    echo "\nStarting concurrent cURL transfers...\n";
71    echo "Observe how 'other_request1' and 'other_request2' can complete while 'main_request' is paused.\n";
72
73    // 3. Execute the cURL requests in a non-blocking loop
74    do {
75        // curl_multi_exec performs data transfer on active handles.
76        // It's non-blocking and will return immediately if no data is available.
77        // The internal "curlm_call_multi_perform" logic is executed here,
78        // allowing multiple transfers to progress in parallel.
79        $mrc = curl_multi_exec($mh, $active);
80
81        // Check for cURL multi errors
82        if ($mrc !== CURLM_OK && $mrc !== CURLM_CALL_MULTI_PERFORM) {
83            echo "cURL multi error: " . curl_multi_strerror($mrc) . "\n";
84            break;
85        }
86
87        // --- Demonstrate CURLPAUSE_ALL and CURLPAUSE_CONT ---
88        // We attempt to pause 'main_request' after it has started, and then resume it.
89        if ($handleMain) {
90            // Trigger pause after initial processing (e.g., after 0.1 seconds of transfer time)
91            if (!$pauseTriggered && curl_getinfo($handleMain, CURLINFO_TOTAL_TIME) > 0.1) {
92                echo "\n--- Triggering PAUSE for 'main_request' using CURLPAUSE_ALL ---\n";
93                // CURLPAUSE_ALL: Pauses both send and receive operations on the handle.
94                $pauseResult = curl_pause($handleMain, CURLPAUSE_ALL);
95                if ($pauseResult === CURLE_OK) {
96                    echo "Successfully PAUSED 'main_request'. It will remain paused until explicitly resumed.\n";
97                    $isPaused = true;
98                    $pauseTriggered = true;
99                } else {
100                    echo "Failed to PAUSE 'main_request'. Error: " . curl_strerror($pauseResult) . "\n";
101                }
102            }
103
104            // If 'main_request' is paused, wait a bit (e.g., 3 seconds from script start)
105            // and then resume it. This is a simple timer for demonstration purposes.
106            if ($isPaused && (microtime(true) - $_SERVER['REQUEST_TIME_FLOAT']) > 3.0) {
107                echo "\n--- Resuming 'main_request' using CURLPAUSE_CONT ---\n";
108                // CURLPAUSE_CONT: Resumes previously paused operations on the handle.
109                $resumeResult = curl_pause($handleMain, CURLPAUSE_CONT);
110                if ($resumeResult === CURLE_OK) {
111                    echo "Successfully RESUMED 'main_request'. Transfer should now continue.\n";
112                    $isPaused = false;
113                    // We can clear $handleMain to prevent further pause/resume attempts on this specific handle.
114                    // The handle itself will still be processed until completion by curl_multi_exec.
115                    $handleMain = null; 
116                } else {
117                    echo "Failed to RESUME 'main_request'. Error: " . curl_strerror($resumeResult) . "\n";
118                }
119            }
120        }
121        // --- End of CURLPAUSE_ALL & CURLPAUSE_CONT demonstration ---
122
123        // Check for completed handles and process them.
124        // This loop helps to show when other requests are finishing.
125        while ($info = curl_multi_info_read($mh)) {
126            if ($info['msg'] === CURLMSG_DONE) {
127                $ch_done = $info['handle'];
128                $name_done = array_search($ch_done, $handles, true); // Find the original name of the handle
129                echo "Handle '{$name_done}' (URL: {$urls[$name_done]}) has finished with status " . curl_getinfo($ch_done, CURLINFO_HTTP_CODE) . ".\n";
130                // Results for this handle will be retrieved in the cleanup phase.
131            }
132        }
133
134        // If there are still active handles, wait for activity (or timeout)
135        if ($active > 0) {
136            // curl_multi_select blocks until there is activity on any of the handles,
137            // or until the timeout occurs. This prevents a tight loop and reduces CPU usage.
138            $selectResult = curl_multi_select($mh, 0.5); // Wait up to 0.5 seconds for activity
139            if ($selectResult === -1) {
140                // select failed, or no file descriptors were found. Sleep briefly to prevent tight loop.
141                usleep(100000); // Sleep for 100 milliseconds
142            }
143        }
144
145    } while ($active > 0); // Continue as long as there are active transfers
146
147    echo "\nAll concurrent cURL transfers finished.\n";
148
149    // 4. Retrieve results and clean up all handles
150    foreach ($handles as $name => $ch) {
151        $error = curl_error($ch);
152        if (!empty($error)) {
153            echo "Error for '{$name}' (URL: {$urls[$name]}): {$error}\n";
154        } else {
155            $content = curl_multi_getcontent($ch); // Get the content fetched by the handle
156            echo "--- Final Result for '{$name}' (URL: {$urls[$name]}) ---\n";
157            echo "Status Code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
158            echo "Total Time: " . round(curl_getinfo($ch, CURLINFO_TOTAL_TIME), 2) . "s\n";
159            // Display only a part of the content for brevity
160            echo "Content (first 100 chars): " . substr($content, 0, 100) . "...\n\n";
161        }
162        curl_multi_remove_handle($mh, $ch); // Remove handle from the multi stack
163        curl_close($ch); // Close the individual cURL handle
164    }
165
166    curl_multi_close($mh); // Close the multi cURL handle
167    echo "All cURL handles and multi handle closed.\n";
168}
169
170// Execute the demonstration function
171demonstrateCurlPauseAndResumeInMulti();

このサンプルコードは、PHPのcURL拡張機能を用いて複数のHTTPリクエストを並行して処理する際に、特定のリクエストを一時的に停止し、その後再開する方法を実演しています。

CURLPAUSE_ALLは、curl_pause()関数と組み合わせて使用する定数です。この定数を指定することで、該当するcURL転送のデータ送信（アップロード）とデータ受信（ダウンロード）の両操作を完全に一時停止させることができます。一時停止された転送は、curl_pause()関数にCURLPAUSE_CONTを渡すことで再開されます。

コードでは、curl_multi_init()やcurl_multi_exec()といったマルチcURL関数を使用して、複数のウェブサイトへのリクエストを非同期に実行しています。処理の途中で、対象となる「main_request」に対してcurl_pause($ch, CURLPAUSE_ALL)を呼び出して転送を一時停止し、一定時間が経過した後にcurl_pause($ch, CURLPAUSE_CONT)で再開しています。この一時停止中も、他のリクエストは影響を受けることなく処理を続行します。これは、curl_multi_exec()が内部でcurlm_call_multi_performと呼ばれる非ブロッキングなメカニズムを利用し、効率的に並列処理を行うためです。

CURLPAUSE_ALL定数自体は、特定の値を示すものであり、引数や戻り値はありません。この定数をcurl_pause()関数の引数として渡すことで、指定されたcURLハンドルにおける転送の一時停止を指示する役割を果たします。この例は、並行処理中に特定の転送を柔軟に制御するcURLの高度な機能を示しています。