PHPのcurl_getinfo関数の使い方について解説

2025-02-19更新日: 2025-02-19

PHPのcurl_getinfo関数は、cURLを使ったリクエスト後に通信の詳細情報を取得するための機能です。

たとえば、HTTPレスポンスコードや転送時間、取得したデータサイズなどが確認でき、ネットワーク通信のデバッグやパフォーマンス改善に役立ちます。

本記事では、curl_getinfoの基本的な使い方と取得できる情報について簡潔に解説します。

目次から探す

基本動作と書式
- curl_getinfoの役割
- cURLセッションとの連携
取得可能な情報詳細
エラー処理とリソース管理
- エラー発生時の対処
- セッション終了とリソース解放
利用例と出力確認
- 実装例のコード紹介
まとめ

基本動作と書式

curl_getinfoの役割

curl_getinfo は、cURLセッションからさまざまな情報を取得するための関数です。

HTTPステータスコードや転送にかかった時間、データ量など、実行結果に関する詳細な情報を配列形式で返してくれます。

これにより、通信状況の確認やデバッグが容易になります。

関数の基本構造

curl_getinfo は、基本的にcURLハンドル(リソース)を引数として受け取り、そのセッションで得られた情報を返します。

例えば、以下のサンプルコードでは、URLへ接続した後の情報を取得しています。

<?php
// URLに対するcURLセッションを初期化する
$ch = curl_init("http://example.com/");
// コンテンツを直接出力しないように設定
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
// リクエストを実行しレスポンスを取得
$response = curl_exec($ch);
// curl_getinfoで詳細な情報を取得する
$info = curl_getinfo($ch);
// 取得した情報のうち、HTTPステータスコードを出力する
echo "HTTPステータスコード: " . $info['http_code'];
// セッションを閉じる
curl_close($ch);
?>

output
HTTPステータスコード: 200

戻り値の形式と型

curl_getinfo が返す情報は、連想配列の形式です。

各要素には以下のような情報が含まれています。

url : リクエストしたURL
content_type : サーバから返されたコンテンツタイプ
http_code : HTTPステータスコード
total_time : リクエストにかかった合計時間

また、特定のパラメータを直接取得する場合、第二引数にパラメータのキー名(定数)を指定すると、その値が返されます。

cURLセッションとの連携

cURLセッションを扱う際、まずは接続の初期化やオプションの設定を行い、リクエスト後にcurl_getinfoで情報を取得する流れとなります。

以下、それぞれについて説明します。

セッションの初期化と設定

cURLセッションは、curl_init で初期化します。

初期化後は、curl_setopt を利用して必要なオプションを設定します。

特に、レスポンスを直接出力しないために、CURLOPT_RETURNTRANSFER を true に設定することが一般的です。

例として、以下のコードはURLに接続するための基本的な設定を示します。

<?php
// cURLセッションの初期化
$ch = curl_init("http://example.com/");
// レスポンスを変数に格納するための設定
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
?>

cURL実行後の情報取得

設定後、curl_exec によりリクエストを実行し、サーバからのレスポンスやエラーなどが取得できます。

その後、curl_getinfo を用いて、HTTPステータスコードや転送に要した時間などを確認します。

以下のサンプルコードでは、リクエスト実行後に各種情報を出力する例を示しています。

<?php
// cURLセッション初期化
$ch = curl_init("http://example.com/");
// レスポンスを直接出力しない設定
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
// リクエスト実行
$response = curl_exec($ch);
// 実行結果の情報を取得
$info = curl_getinfo($ch);
// HTTPステータスコードと転送時間の出力
echo "HTTP Code: " . $info['http_code'] . "\n";
echo "Total Time: " . $info['total_time'] . " sec\n";
// セッション終了
curl_close($ch);
?>

output
HTTP Code: 200
Total Time: 0.345 sec

取得可能な情報詳細

HTTP関連情報

HTTPステータスコード

curl_getinfo で取得できる一番基本的な情報のひとつがHTTPステータスコードです。

サーバからのレスポンスコードを確認することで、リクエストが成功したか、エラーが発生したかを一目で把握できます。

HTTPステータスコードは、http_code キーを用いてアクセスします。

HTTPバージョンの違い

通信に使われたHTTPのバージョンも確認することができます。

サーバとのやり取りで利用されたプロトコルのバージョン(例: HTTP/1.1 や HTTP/2)を知ることで、通信の最適化の判断材料になります。

curl_getinfo で取得した連想配列の中には、http_version というキーが含まれていることがあり、これをチェックすることで確認できます。

タイミング情報

合計転送時間の確認

リクエスト全体にかかった時間(合計転送時間)は、total_time キーで取得できます。

これは、サーバへの接続開始から全データの受信完了までの時間を秒単位で示しており、通信性能を評価する指標となります。

例えば、以下の式で表せます。

$Total Time = Connection Time + Transfer Time$

接続およびDNS解決時間

DNS解決やサーバへの接続にかかった時間も取得可能です。

例えば、namelookup_time はDNSで名前解決に要した時間を、connect_time はサーバへの接続にかかった時間を示します。

これらの情報を分析することで、どの段階で遅延が発生しているかを把握できます。

データ量とエラー情報

ダウンロード／アップロードサイズ

転送されたデータの量は、size_download や size_upload のキーで取得でき、受信または送信されたバイト数を示します。

これにより、実際のデータ通信の規模を確認することが可能です。

エラー番号とメッセージ

通信中にエラーが発生した場合、curl_getinfo だけでなく、curl_errno や curl_error を利用して、エラー番号や詳細なエラーメッセージを取得できます。

curl_getinfo 自体はエラー情報を含む配列の一部ではないですが、通信状況を確認する際に併用することで、問題の原因を特定しやすくなります。

エラー処理とリソース管理

エラー発生時の対処

エラーコードの確認方法

cURLによるリクエストで問題が発生した場合は、curl_errno を利用することで、エラー番号を確認できます。

エラー番号により、接続エラーやタイムアウトなど、どのような問題が発生したかを特定する手がかりとなります。

以下のコード例では、エラー番号の確認方法を示しています。

<?php
// cURLセッション初期化
$ch = curl_init("http://example.com/");
// レスポンスを返すように設定
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
// リクエスト実行
$response = curl_exec($ch);
// エラー番号を取得
$errorNumber = curl_errno($ch);
if ($errorNumber !== 0) {
    // エラー番号が0以外の場合にはエラーが発生したと判断
    echo "エラー番号: " . $errorNumber;
}
curl_close($ch);
?>

output
エラー番号: 7

エラーメッセージの取得

エラー発生時には、curl_error を利用して、具体的なエラーメッセージを取得できます。

エラーメッセージはログ出力やユーザ向けの通知に活用でき、問題解決の手助けとなります。

<?php
// cURLセッション初期化
$ch = curl_init("http://example.com/");
// レスポンスを返すように設定
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
// リクエスト実行
$response = curl_exec($ch);
// エラーメッセージを取得
$errorMessage = curl_error($ch);
if (!empty($errorMessage)) {
    echo "エラーメッセージ: " . $errorMessage;
}
curl_close($ch);
?>

output
エラーメッセージ: Failed to connect to example.com port 80: Connection refused

セッション終了とリソース解放

cURLセッションのクローズ

cURLセッションを利用後は、curl_close を用いてセッションを終了し、リソースを解放する必要があります。

これにより、メモリリークなどの問題を防ぐことができます。

セッション終了処理は、エラー処理の後や最終的な情報取得後に必ず実行するようにしてください。

<?php
// cURLセッション初期化
$ch = curl_init("http://example.com/");
// 必要なオプションの設定
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
// リクエスト実行と情報取得
$response = curl_exec($ch);
// curl_getinfo等の処理を実施
$info = curl_getinfo($ch);
// セッション終了でリソースを解放
curl_close($ch);
?>

利用例と出力確認

実装例のコード紹介

基本コードの構成

実際の利用例として、以下のサンプルコードでは、URLに対するリクエストの実行、情報の取得、そして出力までの一連の流れを示しています。

コード内にはわかりやすいコメントを挿入しているため、各行の役割が把握しやすくなっています。

<?php
// cURLセッションの初期化(対象URL: example.com)
$ch = curl_init("http://example.com/");
// レスポンスを文字列として取得する設定
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
// リクエストを実行
$response = curl_exec($ch);
// リクエスト実行中にエラーがあった場合は、エラー番号とメッセージを確認
if (curl_errno($ch)) {
    // エラー番号を取得
    $errorCode = curl_errno($ch);
    // エラーメッセージを取得
    $errorMsg = curl_error($ch);
    echo "Error Code: $errorCode\n";
    echo "Error Message: $errorMsg\n";
} else {
    // curl_getinfoを使用して、リクエストに関する情報を取得
    $info = curl_getinfo($ch);
    // HTTPステータスコードと合計転送時間を出力する
    echo "HTTP Code: " . $info['http_code'] . "\n";
    echo "Total Transfer Time: " . $info['total_time'] . " sec\n";
}
// セッション終了とリソースの解放
curl_close($ch);
?>

取得パラメータの出力確認

実行後に取得できる主要なパラメータとして、HTTPステータスコードや転送時間が出力されます。

以下は、サンプルコード実行時に出力される例です。

output
HTTP Code: 200
Total Transfer Time: 0.456 sec

まとめ

本記事では、PHPのcurl_getinfo関数の基本動作や取得可能な情報、エラー処理とリソース管理の方法について具体的に説明しました。

全体を通して、cURL通信の各種パラメータ取得とその活用方法が整理され、実践的なコード例で理解が深まる内容となっています。

ぜひ、実装例を参考にして、実際のプロジェクトに取り入れてみてください。