Webエンジニア向けプログラミング解説動画をYouTubeで配信中!
▶ チャンネル登録はこちら

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

CURLOPT_RESUME_FROM定数の使い方について、初心者にもわかりやすく解説します。

作成日: 更新日:

基本的な使い方

CURLOPT_RESUME_FROM定数は、PHPのcURL拡張機能において、データ転送を特定の位置から再開する(レジュームする)ための開始オフセットを表す定数です。

cURLは、HTTPやFTPなど様々なプロトコルを用いてデータを送受信するためのライブラリであり、PHPではcurl_setopt()関数などを使ってcURLの挙動を詳細に設定できます。このCURLOPT_RESUME_FROM定数は、そのcurl_setopt()関数で指定するオプションの一つとして利用されます。

通常、ファイルのダウンロードやアップロード中に通信が中断された場合、最初からやり直す必要があります。しかし、このCURLOPT_RESUME_FROM定数に中断された時点までの転送バイト数を設定することで、そのバイト位置からデータ転送を再開させることが可能になります。これにより、特に大容量のファイルを扱う際に、中断による時間やリソースの無駄を省き、効率的かつ信頼性の高いデータ転送を実現できます。

指定する値はバイト単位の整数であり、転送を開始したいオフセット位置を示します。例えば、これまでに1024バイトのデータが転送されていた場合、この定数に1024を設定することで、1025バイト目からの転送が開始されます。また、負の値を設定した場合は、ファイル末尾からのオフセットとして解釈され、ファイル終端から指定バイト数分さかのぼった位置から転送が開始されます。これは、データ転送の効率化と安定運用に不可欠な機能の一つです。

構文(syntax)

1<?php
2$ch = curl_init();
3curl_setopt($ch, CURLOPT_RESUME_FROM, 102400);
4curl_close($ch);
5?>

引数(parameters)

引数なし

引数はありません

戻り値(return)

戻り値なし

戻り値はありません

サンプルコード

PHP cURLでダウンロード再開とデータ処理をする

1<?php
2
3/**
4 * 指定されたURLからデータをダウンロードし、特定のバイト位置から再開し、
5 * 受信データをカスタムコールバック関数で処理するサンプル。
6 *
7 * この関数は、CURLOPT_RESUME_FROM を使用してダウンロードを再開し、
8 * CURLOPT_WRITEFUNCTION を使用してダウンロードデータをメモリ上で処理します。
9 *
10 * @param string $url ダウンロード対象のURL。サーバーがRangeヘッダをサポートしている必要があります。
11 * @param int $resumeFromBytes ダウンロードを再開するバイト位置 (0から始まる)。
12 * @return string ダウンロードされたデータ、またはエラーメッセージ。
13 */
14function downloadWithResumeAndCustomWrite(string $url, int $resumeFromBytes): string
15{
16    // ダウンロードされたデータを蓄積するための変数
17    $downloadedData = '';
18
19    // cURL セッションを初期化
20    $ch = curl_init();
21
22    if ($ch === false) {
23        return "cURL 初期化に失敗しました。";
24    }
25
26    // ダウンロード対象のURLを設定
27    curl_setopt($ch, CURLOPT_URL, $url);
28
29    // 受信データを文字列として直接返さず、CURLOPT_WRITEFUNCTION で処理するように設定
30    // (CURLOPT_WRITEFUNCTION を設定すると、このオプションは自動的に false とみなされることが多いですが、明示的に設定します)
31    curl_setopt($ch, CURLOPT_RETURNTRANSFER, false);
32    // レスポンスヘッダをダウンロードデータに含めない
33    curl_setopt($ch, CURLOPT_HEADER, false);
34
35    // ダウンロードを再開するバイト位置を設定
36    // サーバーがHTTPのRangeヘッダをサポートしている場合のみ有効です。
37    curl_setopt($ch, CURLOPT_RESUME_FROM, $resumeFromBytes);
38
39    // 受信データを処理するカスタムコールバック関数を設定
40    // この関数は、cURL がデータを受信するたびに呼び出されます。
41    // 第1引数: cURL ハンドル
42    // 第2引数: 受信したデータチャンク
43    // 戻り値: 処理したバイト数 (受信データの全量を処理したことをcURLに通知するために、strlen($data) を返します)
44    curl_setopt($ch, CURLOPT_WRITEFUNCTION, function ($curlHandle, $data) use (&$downloadedData) {
45        $downloadedData .= $data; // 受信データを $downloadedData 変数に追加
46        return strlen($data);     // 受信データの全量を処理したことをcURLに通知
47    });
48
49    // cURL セッションを実行
50    $result = curl_exec($ch);
51
52    // エラーチェック
53    if ($result === false) {
54        $errorMessage = curl_error($ch);
55        curl_close($ch);
56        return "cURL エラー: " . $errorMessage;
57    }
58
59    // cURL セッションを閉じる
60    curl_close($ch);
61
62    return $downloadedData;
63}
64
65// --- サンプル使用 ---
66// httpbin.org は、HTTP Range ヘッダをサポートするダミーのバイトデータを提供します。
67// 例として、500バイトのランダムデータを対象とします。
68$targetUrl = 'https://httpbin.org/bytes/500';
69$resumeBytes = 200; // 200バイト目からダウンロードを再開します。
70
71echo "対象URL: " . $targetUrl . "\n";
72echo "ダウンロード再開位置: " . $resumeBytes . "バイト目から\n\n";
73
74$data = downloadWithResumeAndCustomWrite($targetUrl, $resumeBytes);
75
76// ダウンロード結果の表示
77if (strpos($data, 'cURL エラー:') === 0) {
78    echo $data . "\n";
79} else {
80    echo "ダウンロード成功!\n";
81    echo "ダウンロードされたデータの長さ: " . strlen($data) . "バイト\n";
82
83    // httpbin.org/bytes/N はNバイトのランダムデータを返します。
84    // Range: bytes=X-Y のリクエストには、指定範囲のデータを返します。
85    // Range: bytes=X- のリクエストには、Xバイト目以降のデータを返します。
86    // したがって、500バイトのファイルに対して200バイト目から再開した場合、
87    // 期待されるデータ長は 500 - 200 = 300 バイトです。
88    $expectedLength = 500 - $resumeBytes;
89    if (strlen($data) == $expectedLength) {
90        echo "期待されるデータ長 (" . $expectedLength . "バイト) と一致しました。\n";
91    } else {
92        echo "期待されるデータ長と一致しませんでした。サーバーが部分ダウンロードを\n";
93        echo "期待通りにサポートしていないか、データが途中で途切れた可能性があります。\n";
94    }
95}

このPHPサンプルコードは、cURLライブラリを用いて、指定されたURLからのデータダウンロードを特定のバイト位置から再開し、受信データを独自のPHP関数で処理する方法を示しています。

CURLOPT_RESUME_FROMオプションは、ダウンロードを開始するバイトオフセットを設定するために使用されます。これにより、すでに一部ダウンロード済みのファイルがある場合に、残りの部分だけをサーバーから取得する「レジューム機能」を実現できます。ただし、この機能は、アクセスするサーバーがHTTPのRangeヘッダ(部分的なデータ要求)をサポートしている場合にのみ有効です。

もう一つの重要なオプションであるCURLOPT_WRITEFUNCTIONは、cURLがサーバーからデータを受信するたびに呼び出されるカスタムコールバック関数を指定します。通常、cURLは受信データを直接ファイルに書き込むか、内部バッファに格納しますが、このオプションを使用すると、受信したデータの各チャンク(断片)をPHPスクリプト側でリアルタイムに処理できます。サンプルコード内のコールバック関数は、受け取ったデータチャンクを順次結合して変数に蓄積し、処理したバイト数をcURLに返すことで、データの完全な処理をcURLに通知しています。

downloadWithResumeAndCustomWrite関数は、ダウンロード対象のURLとダウンロードを再開するバイト位置を引数として受け取ります。関数が正常に完了すると、指定されたバイト位置からダウンロードされたデータ全体を文字列として返します。エラーが発生した場合は、その内容を示すエラーメッセージを返します。この仕組みにより、大規模なファイルの効率的なダウンロードや、受信データのカスタム処理が可能になります。

CURLOPT_RESUME_FROMは、ダウンロード対象のサーバーがHTTPのRangeヘッダによる部分ダウンロードをサポートしている場合にのみ有効です。サーバー側の設定をご確認ください。また、CURLOPT_WRITEFUNCTIONを設定すると、受信データはPHPスクリプトのメモリに蓄積されます。サンプルコードのように大きなファイルをダウンロードする場合、システムメモリを大量に消費し、メモリ不足エラーを引き起こす可能性があります。そのため、大規模なダウンロードでは、受信データを直接ファイルへ書き込むなど、メモリ消費を抑える工夫が必要です。CURLOPT_WRITEFUNCTIONに指定するコールバック関数は、処理したデータのバイト数を正確に返す必要があります。これを怠ると、cURLがデータ処理に失敗したと判断し、ダウンロードが途中で中断される原因となりますのでご注意ください。

PHP cURLでダウンロード再開と結果取得

1<?php
2
3/**
4 * 指定されたURLからコンテンツをダウンロードし、CURLOPT_RESUME_FROM と CURLOPT_RETURNTRANSFER の使用例を示します。
5 *
6 * システムエンジニアを目指す初心者向けに、ファイルのダウンロード再開と、
7 * ダウンロード結果を変数として受け取る方法を簡潔に示します。
8 *
9 * @param string $url ダウンロード対象のURL。
10 */
11function downloadFileWithResumeFeature(string $url): void
12{
13    echo "--- 全体ダウンロード (CURLOPT_RETURNTRANSFER の基本動作) ---\n";
14    echo "ターゲットURL: " . $url . "\n\n";
15
16    // cURLセッションを初期化
17    $ch_full = curl_init($url);
18
19    if ($ch_full === false) {
20        echo "エラー: cURLセッションの初期化に失敗しました。\n";
21        return;
22    }
23
24    // CURLOPT_RETURNTRANSFER を true に設定することで、
25    // curl_exec() の結果がブラウザに直接出力されるのではなく、関数の戻り値として文字列で返されます。
26    curl_setopt($ch_full, CURLOPT_RETURNTRANSFER, true);
27
28    // cURLセッションを実行し、結果を取得
29    $full_content = curl_exec($ch_full);
30
31    if ($full_content === false) {
32        echo "エラー: ダウンロードに失敗しました。\n";
33        echo "cURLエラー: " . curl_error($ch_full) . "\n";
34    } else {
35        echo "ダウンロードされたコンテンツ(全体、最初の50バイトのみ表示):\n";
36        echo substr($full_content, 0, 50) . "...\n";
37        echo "コンテンツの総バイト数: " . strlen($full_content) . " バイト\n\n";
38    }
39
40    // cURLセッションを閉じる
41    curl_close($ch_full);
42
43
44    echo "--- 部分ダウンロード (CURLOPT_RESUME_FROM と CURLOPT_RETURNTRANSFER) ---\n";
45
46    // ダウンロードを再開するバイトオフセット(例: 10バイト目から)
47    $resume_from_byte = 10;
48    echo "ダウンロードを " . $resume_from_byte . " バイト目から再開します。\n\n";
49
50    // 新しいcURLセッションを初期化
51    $ch_resume = curl_init($url);
52
53    if ($ch_resume === false) {
54        echo "エラー: cURLセッションの初期化に失敗しました。\n";
55        return;
56    }
57
58    // CURLOPT_RETURNTRANSFER を true に設定
59    curl_setopt($ch_resume, CURLOPT_RETURNTRANSFER, true);
60
61    // CURLOPT_RESUME_FROM を設定することで、指定したバイト数からダウンロードを再開します。
62    // これにより、既にダウンロード済みの部分をスキップして残りを取得できます。
63    curl_setopt($ch_resume, CURLOPT_RESUME_FROM, $resume_from_byte);
64
65    // cURLセッションを実行し、結果を取得
66    $resumed_content = curl_exec($ch_resume);
67
68    if ($resumed_content === false) {
69        echo "エラー: 部分ダウンロードに失敗しました。\n";
70        echo "cURLエラー: " . curl_error($ch_resume) . "\n";
71    } else {
72        echo "ダウンロードされたコンテンツ(" . $resume_from_byte . "バイト目から、最初の50バイトのみ表示):\n";
73        echo substr($resumed_content, 0, 50) . "...\n";
74        echo "コンテンツのバイト数(" . $resume_from_byte . "バイト目以降): " . strlen($resumed_content) . " バイト\n";
75        echo "(このバイト数は、全体のバイト数から " . $resume_from_byte . " バイトを引いたものになります)\n";
76    }
77
78    // cURLセッションを閉じる
79    curl_close($ch_resume);
80}
81
82// 実際にテストを行うためのURLを指定します。
83// これはJSONPlaceholderというテスト用APIのエンドポイントで、安定したテキストコンテンツを提供します。
84// 必要に応じて、ご自身のテスト用のURLに置き換えてください。
85$testUrl = "https://jsonplaceholder.typicode.com/posts/1";
86
87// 関数を実行
88downloadFileWithResumeFeature($testUrl);
89
90?>

このサンプルコードは、PHPのcURL機能を利用してウェブ上のコンテンツをダウンロードする方法と、その際に便利な二つのオプション定数の使い方をシステムエンジニアを目指す初心者向けに解説します。

まず、CURLOPT_RETURNTRANSFERは、ウェブサイトから取得したデータ(コンテンツ)を、直接画面に表示せず、PHPのプログラム内で扱える文字列として変数に格納したい場合にtrueに設定します。これにより、ダウンロードしたコンテンツを後で加工したり、ファイルに保存したりすることが容易になります。

次に、本リファレンスの対象であるCURLOPT_RESUME_FROMは、ダウンロードを特定のバイト位置から再開したい場合に利用する定数です。例えば、大きなファイルのダウンロードが途中で中断された際に、最初からやり直すのではなく、既にダウンロード済みの部分をスキップして残りの部分だけを取得したい場合に、このオプションに開始バイト数を指定します。これにより、ネットワーク負荷を軽減し、効率的にダウンロードを完了できます。

サンプルコードでは、最初にCURLOPT_RETURNTRANSFERを使ったコンテンツ全体のダウンロード例を示し、次にCURLOPT_RESUME_FROMとCURLOPT_RETURNTRANSFERを組み合わせて、指定したバイト位置からコンテンツの残りの部分のみを取得し、それを変数に格納する具体的な手順を紹介しています。これにより、効率的なデータ取得やダウンロード再開機能の実装方法が理解できます。

サンプルコードで利用している CURLOPT_RETURNTRANSFER を true に設定しないと、curl_exec() の結果は変数に格納されず、直接出力されてしまいます。ダウンロード結果を変数で扱う場合は必ず設定してください。CURLOPT_RESUME_FROM は、対象サーバーが部分ダウンロード(Rangeリクエスト)に対応している場合にのみ有効です。対応しないサーバーではこの設定は無視されるか、エラーとなる場合がありますのでご注意ください。cURLの処理では、curl_init() や curl_exec() の戻り値を必ず確認し、失敗した場合は curl_error() で原因を調査することが重要です。また、処理が終わったら curl_close() でcURLセッションを確実に閉じ、システムリソースを適切に解放する習慣をつけましょう。

関連コンテンツ

関連IT用語

関連プログラミング言語