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

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

作成日: 2025年09月11日更新日: 2026年02月23日

基本的な使い方

CURL_IPRESOLVE_V4定数は、PHPのcURLライブラリでネットワーク通信を行う際に、ドメイン名（ホスト名）をIPアドレスに解決する方法を制御するために使用される定数です。

cURLは、プログラムから外部のウェブサービスやサーバーに対してHTTPリクエストを送信するなど、様々なネットワーク通信を行うための機能を提供します。この際、アクセス先のウェブサイトのドメイン名（例えば、「www.example.com」）は、実際に通信するために必要な数値のアドレスであるIPアドレスに変換（これを「名前解決」と呼びます）される必要があります。

このCURL_IPRESOLVE_V4定数は、CURLOPT_IPRESOLVEというcURLオプションに設定することで機能します。CURLOPT_IPRESOLVEオプションにCURL_IPRESOLVE_V4定数を指定すると、cURLは名前解決の処理において、IPv4形式のIPアドレスのみを探すように動作します。つまり、IPv6形式のアドレスが見つかってもそれを無視し、IPv4アドレスだけを優先的に使用して接続を試みます。

この設定は、システムが稼働するネットワーク環境がIPv4のみに対応している場合や、IPv6での名前解決が不要、または予期せぬ問題を引き起こす可能性がある場合に特に有用です。例えば、アプリケーションが特定のIPv4専用サービスと連携する際や、通信の安定性を確保したい場合に、意図した通りのIPバージョンで通信を開始できるようになります。これにより、ネットワーク環境に起因する接続エラーのリスクを軽減し、より堅牢なシステムを構築する手助けとなります。

構文(syntax)


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

引数(parameters)

引数なし

引数はありません

戻り値(return)

int

CURL_IPRESOLVE_V4 は、IPアドレスの解決方法を指定するための整数定数です。IPv4アドレスのみを使用するように設定します。

サンプルコード

PHP cURL IPv4解決でURLを取得する


1<?php
2
3/**
4 * CURL_IPRESOLVE_V4定数を使用して、IPv4アドレスのみでDNS解決を行うcURLリクエストの例。
5 *
6 * この関数は、指定されたURLに対してcURLリクエストを実行し、
7 * DNS解決にIPv4アドレスのみを使用するように設定します。
8 * これは、システムがIPv6を優先する場合でも、強制的にIPv4を使用させたい場合に役立ちます。
9 *
10 * @param string $url リクエストを送信するURL。
11 * @return string|false リクエストの応答ボディ、または失敗した場合はfalse。
12 */
13function fetchContentWithIpv4Resolution(string $url): string|false
14{
15    // cURLセッションを初期化します。
16    // cURLは、様々なプロトコルでデータ転送を行うためのライブラリです。
17    $ch = curl_init();
18
19    // cURLオプションを設定します。
20    // アクセスするURLを設定します。
21    curl_setopt($ch, CURLOPT_URL, $url);
22
23    // CURLOPT_IPRESOLVEオプションにCURL_IPRESOLVE_V4定数を設定します。
24    // CURL_IPRESOLVE_V4は、DNSの名前解決をIPv4アドレスに強制する定数です。
25    // これにより、IPv6が利用可能な環境でもIPv4のみが使用されます。
26    curl_setopt($ch, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V4);
27
28    // 転送結果を文字列として返すように設定します。
29    // これを設定しない場合、curl_exec()は結果を直接出力します。
30    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
31
32    // HTTPヘッダーを含めないように設定します。
33    curl_setopt($ch, CURLOPT_HEADER, false);
34
35    // cURLセッションを実行し、結果（応答ボディ）を取得します。
36    $response = curl_exec($ch);
37
38    // cURLの実行中にエラーが発生した場合は、エラーメッセージを表示します。
39    if (curl_errno($ch)) {
40        echo 'cURLエラー: ' . curl_error($ch) . PHP_EOL;
41        $response = false; // エラー時はfalseを返します
42    }
43
44    // cURLセッションを閉じ、使用したリソースを解放します。
45    curl_close($ch);
46
47    return $response;
48}
49
50// サンプルとして、IPv4解決を強制して 'http://example.com' にアクセスしてみます。
51$targetUrl = 'http://example.com';
52echo "{$targetUrl} へのアクセスをIPv4解決のみで試行中..." . PHP_EOL;
53
54$result = fetchContentWithIpv4Resolution($targetUrl);
55
56if ($result !== false) {
57    echo "成功しました。取得したコンテンツの最初の200文字:\n";
58    // 取得したコンテンツが長い場合のために、最初の部分だけを表示します。
59    echo substr($result, 0, 200) . '...' . PHP_EOL;
60} else {
61    echo "失敗しました。上記のcURLエラーメッセージを確認してください。" . PHP_EOL;
62}
63

このPHPサンプルコードは、PHPのcURL拡張機能とCURL_IPRESOLVE_V4定数を使用して、指定されたURLへアクセスする際に、DNSの名前解決をIPv4アドレスのみに限定する方法を示しています。CURL_IPRESOLVE_V4は、cURLリクエストにおいて名前解決をIPv4に強制するための整数定数です。これにより、システムがIPv6を優先する環境でも、意図的にIPv4での通信を行いたい場合に役立ちます。

fetchContentWithIpv4Resolution関数は、引数としてアクセス先のURL（$url、文字列型）を受け取ります。関数内では、まずcURLセッションを初期化し、curl_setopt()関数で各種オプションを設定します。ここでCURLOPT_IPRESOLVEオプションにCURL_IPRESOLVE_V4を設定することにより、DNS解決がIPv4に強制されます。他にも、転送結果を文字列として取得するためのCURLOPT_RETURNTRANSFERなども設定されます。

その後、curl_exec()でcURLリクエストが実行され、サーバーからの応答ボディが取得されます。もしリクエスト中にエラーが発生した場合は、その旨がコンソールに表示され、関数はブール値のfalseを返します。正常に処理が完了した場合は、取得した応答ボディが文字列として返されます。この機能は、特定のネットワーク環境での互換性確保や、デバッグ時などに特に有用です。

このコードはDNSの名前解決をIPv4に強制しますが、通常はCURL_IPRESOLVE_WHATEVER（デフォルト）を利用し、システムが最適なIPバージョンを自動で選択するように任せるべきです。IPv4に固定すると、IPv6のみで提供されるサービスへ接続できなくなるため、この設定が必要な特定の状況を理解して利用してください。 cURLリクエストの実行時には、必ずcurl_errno()でエラーを確認し、問題を適切に処理することが重要です。また、使用後のcurl_close()によるリソース解放も忘れないでください。この機能はPHPのcURL拡張がインストールされている環境でのみ動作しますので、事前に動作環境を確認してください。