【PHP8.x】curl_getinfo関数の使い方

<?php

declare(strict_types=1);

/**
 * cURLを使用して指定されたURLにリクエストを送信し、
 * curl_getinfo() を使ってレスポンスヘッダーに関する情報を取得・表示します。
 *
 * @return void
 */
function displayResponseHeaderInfo(): void
{
    // 情報を取得する対象のURL
    $url = 'https://api.github.com';

    // 1. cURLセッションを初期化します。
    // curl_init() は CurlHandle オブジェクトまたは false を返します。
    $ch = curl_init();
    if ($ch === false) {
        echo 'cURLセッションの初期化に失敗しました。' . PHP_EOL;
        return;
    }

    try {
        // 2. cURLのオプションを設定します。
        // リクエスト先のURL
        curl_setopt($ch, CURLOPT_URL, $url);
        // レスポンスを文字列として受け取る
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        // リダイレクトされた場合、自動的に移動先のURLを追跡する
        curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
        // User-Agentヘッダーを設定（一部のAPIで要求されるため）
        curl_setopt($ch, CURLOPT_USERAGENT, 'PHP-cURL-Example/1.0');

        // 3. cURLセッションを実行し、レスポンスを取得します。
        $response = curl_exec($ch);
        if ($response === false) {
            echo 'cURLエラー: ' . curl_error($ch) . PHP_EOL;
            return;
        }

        // 4. curl_getinfo() を使用して、ヘッダー関連の情報を取得します。
        // 第2引数に定数を指定することで、特定の情報を取得できます。
        echo "{$url} からのレスポンスヘッダー情報:" . PHP_EOL;
        echo '--------------------------------------------' . PHP_EOL;

        // HTTPステータスコードを取得 (例: 200, 404)
        $httpCode = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
        echo 'HTTPステータスコード: ' . $httpCode . PHP_EOL;

        // Content-Typeヘッダーの値を取得 (例: application/json; charset=utf-8)
        $contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE);
        echo 'Content-Type: ' . ($contentType ?? 'N/A') . PHP_EOL;

        // レスポンスヘッダーの合計サイズをバイト単位で取得
        $headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
        echo 'ヘッダーサイズ: ' . $headerSize . ' バイト' . PHP_EOL;

        // リクエストが完了するまでにかかった合計時間を秒単位で取得
        $totalTime = curl_getinfo($ch, CURLINFO_TOTAL_TIME);
        echo '合計時間: ' . round($totalTime, 4) . ' 秒' . PHP_EOL;

    } finally {
        // 5. cURLセッションを閉じ、リソースを解放します。
        curl_close($ch);
    }
}

// 関数を実行して結果を表示します。
displayResponseHeaderInfo();

curl_getinfo関数は、curl_exec関数でcURLによる通信を実行した後に、その転送に関する詳細な情報を取得するための関数です。通信結果のステータスコードやレスポンスヘッダーの内容を確認するなど、デバッグや処理の分岐に役立ちます。

第1引数$handleには、curl_initで初期化したcURLセッションのハンドルを指定します。第2引数$optionには、取得したい情報の種類を示す定数を指定します。この引数は省略可能で、省略した場合は取得可能な全ての情報が連想配列として返されます。

戻り値は、第2引数で指定した情報に対応する値（整数、文字列など）です。情報が取得できなかった場合はnullやfalseが返ることがあります。

サンプルコードでは、APIへリクエストを送信後、curl_getinfo関数を用いています。第2引数にCURLINFO_RESPONSE_CODEやCURLINFO_CONTENT_TYPEといった定数を指定することで、HTTPステータスコードやContent-Typeヘッダーの値など、特定ヘッダーに関連する情報を個別に取得しています。このように、レスポンスの具体的な内容をプログラムで把握し、その後の処理に活かすことができます。

<?php

/**
 * 存在しないホストやポートに接続を試み、
 * curl_getinfo() で取得するHTTPステータスコードが0になる状況を実演します。
 *
 * HTTPステータスコードが0になるのは、DNS解決の失敗、接続タイムアウト、
 * ネットワークエラーなど、HTTPレベルの通信が確立される前に
 * リクエストが失敗した場合です。
 *
 * @return void
 */
function demonstrateHttpStatusCodeZero(): void
{
    // 誰もリッスンしていないであろうポートを指定し、意図的に接続失敗を誘発します。
    $url = 'http://example.com:9999';

    // 1. cURLセッションを初期化します。
    $curlHandle = curl_init();

    // 2. cURLオプションを設定します。
    curl_setopt_array($curlHandle, [
        // 接続先のURL
        CURLOPT_URL => $url,
        // 接続試行のタイムアウトを2秒に設定
        CURLOPT_CONNECTTIMEOUT => 2,
        // 結果を文字列として返す
        CURLOPT_RETURNTRANSFER => true,
    ]);

    echo "リクエストURL: {$url}" . PHP_EOL;

    // 3. cURLリクエストを実行します。
    // 接続に失敗するため、この関数は false を返します。
    $response = curl_exec($curlHandle);

    // 4. リクエストが失敗したことを確認し、エラー情報を表示します。
    if ($response === false) {
        $errorMessage = curl_error($curlHandle);
        echo "cURLリクエストが失敗しました: {$errorMessage}" . PHP_EOL;
    }

    // 5. curl_getinfo() を使ってHTTPステータスコードを取得します。
    // サーバーと通信できなかったため、ステータスコードは 0 となります。
    $httpCode = curl_getinfo($curlHandle, CURLINFO_HTTP_CODE);

    echo "取得したHTTPステータスコード: {$httpCode}" . PHP_EOL;

    // 6. cURLセッションを終了し、リソースを解放します。
    curl_close($curlHandle);
}

// 関数を実行します。
demonstrateHttpStatusCodeZero();

curl_getinfo関数は、cURLセッションの実行に関する詳細な情報を取得するための関数です。第一引数にはcurl_initで初期化されたcURLハンドルを、第二引数には取得したい情報の種類を示す定数を指定します。第二引数を指定した場合、その情報に対応する値（文字列や数値など）が戻り値として返されます。

このサンプルコードは、curl_getinfoでHTTPステータスコードを取得した際に、その値が0になる状況を説明するものです。コードでは、意図的に存在しないポート（9999）へ接続を試みることで、サーバーとの通信に失敗する状況を再現しています。

curl_exec関数は通信に失敗するためfalseを返します。その後、curl_getinfo関数でHTTPステータスコードを要求すると、戻り値は0となります。これは、HTTPステータスコード（200 OKや404 Not Foundなど）がサーバーとの通信が確立されて初めて得られる情報であるためです。DNSの名前解決失敗や接続タイムアウトなど、HTTP通信が始まる前のネットワークレベルでエラーが発生した場合、取得されるステータスコードは0となり、通信自体が成功しなかったことを示します。