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

作成日: 2025年09月11日更新日: 2025年09月29日

curl_error関数は、指定されたcURLセッションで最後に発生したエラーの詳細な内容を文字列として取得する関数です。この関数は、主にcurl_exec()など、cURL関連の関数が期待通りに動作しなかった場合に、何が問題だったのかを具体的に把握するために利用されます。

引数には、curl_init()関数で初期化されたcURLリソース（ハンドル）を一つ指定します。このハンドルは、特定のcURL通信セッションを識別するためのものです。関数は、該当するcURLセッションで最後に発生したエラーメッセージを文字列として返します。もしエラーが全く発生していなければ、空の文字列が返されます。

例えば、外部のWeb APIへリクエストを送信する際や、リモートのサーバーからファイルをダウンロードする際に、ネットワークの問題や設定の誤りなどによって処理が失敗することがあります。そのような状況でcurl_error()関数を使用することで、「接続に失敗しました」や「URLが無効です」といった具体的なエラーメッセージを受け取り、問題解決のための手がかりを得ることができます。

この関数は、エラーの種類を数値で取得するcurl_errno()関数と組み合わせて使用されることが多いです。curl_errno()はエラーコードを返しますが、curl_error()はそのエラーコードに対応する人間が理解しやすいエラーメッセージを返します。これにより、開発者はエラーの状況をより正確に把握し、適切なエラー処理やデバッグを行うことが可能になります。

基本的な使い方

構文(syntax)

<?php
$ch = curl_init();
if ($ch === false) {
    // cURLハンドルの初期化に失敗した場合の処理
    exit('Failed to initialize cURL.');
}

// 存在しないURLなどを設定してエラーを発生させる例
curl_setopt($ch, CURLOPT_URL, "http://invalid.url.example.com");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

if ($response === false) {
    // cURL実行中にエラーが発生した場合、そのエラーメッセージを取得
    echo curl_error($ch);
}

curl_close($ch);
?>

引数(parameters)

CurlHandle $handle

CurlHandle $handle: エラー情報を取得したい cURL セッションのハンドル

戻り値(return)

string

curl_error関数は、直前のcURLセッションで発生したエラーメッセージを文字列で返します。エラーが発生していない場合は空文字列を返します。

サンプルコード

PHP: curl_error でSSL証明書エラーを確認する

<?php

/**
 * curl_error 関数の使用例：SSL証明書エラーの確認.
 *
 * CURLOPT_SSL_VERIFYPEER を true に設定した場合、SSL証明書の検証が行われる。
 * 検証に失敗した場合、curl_error 関数で具体的なエラー内容を取得できる。
 */

// curl ハンドルを初期化
$ch = curl_init('https://example.com');

// SSL 証明書の検証を有効にする
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);

// CURLOPT_RETURNTRANSFER を true に設定して、結果を文字列として返すようにする
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// URL を取得
$result = curl_exec($ch);

// エラーが発生した場合
if ($result === false) {
    // エラー内容を取得
    $error = curl_error($ch);

    // エラーコードが60の場合（SSL証明書の問題）
    if (strpos($error, '60') !== false) {
        echo "SSL証明書のエラーが発生しました: " . $error . PHP_EOL;
        echo "CURLOPT_CAINFO または CURLOPT_CAPATH が正しく設定されているか確認してください。" . PHP_EOL;
    } else {
        echo "cURL エラーが発生しました: " . $error . PHP_EOL;
    }
} else {
    // 成功した場合の処理
    echo "リクエスト成功!" . PHP_EOL;
}

// curl ハンドルを閉じる
curl_close($ch);

?>

curl_error関数は、cURLセッションで発生した最後のエラーメッセージを取得するために使用します。引数には、エラー情報を取得したいcURLハンドルのリソース $handle を指定します。この関数は文字列型の戻り値を返し、エラーが発生しなかった場合は空文字列を返します。

サンプルコードでは、SSL証明書の検証エラーが発生した場合に、curl_error関数を使ってエラー内容を取得する方法を示しています。CURLOPT_SSL_VERIFYPEER オプションを true に設定することで、cURLはSSL証明書の検証を行うようになります。検証に失敗した場合、curl_exec関数は false を返し、curl_error関数で具体的なエラー内容を確認できます。

サンプルコードでは、エラーメッセージにエラーコード 60 が含まれているかをチェックしています。エラーコード 60 は、通常、SSL証明書の検証に失敗した場合に発生します。このエラーが発生した場合、CURLOPT_CAINFO または CURLOPT_CAPATH オプションが正しく設定されているか確認する必要があります。これらのオプションは、信頼できる認証局（CA）の証明書ファイルまたはディレクトリを指定するために使用します。 curl_error関数を使用することで、cURLセッションで発生した問題を特定し、適切な対処を行うことができます。

curl_error関数は、cURL処理中に発生したエラーメッセージを取得するために使用します。サンプルコードでは、SSL証明書の検証エラー（エラーコード60）を検知する例を示しています。CURLOPT_SSL_VERIFYPEERをtrueに設定すると、SSL証明書の検証が厳格に行われ、証明書に問題がある場合にエラーが発生します。CURLOPT_CAINFOまたはCURLOPT_CAPATHオプションで、信頼できる認証局（CA）の証明書を指定する必要があります。これらの設定が正しくないと、SSL証明書のエラーが発生しやすいため注意が必要です。また、curl_error関数でエラー内容を取得する前に、curl_exec関数の戻り値がfalseであることを確認してください。

PHP cURL エラー 7 接続エラーを取得する

<?php

// cURL エラー 7 は、接続エラー（ホストが見つからない、接続を拒否されたなど）を表します。
// この例では、存在しないホストに接続を試み、エラーメッセージを取得します。

$ch = curl_init('https://invalid.example.com'); // 存在しないホスト

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // レスポンスを文字列として返す

$result = curl_exec($ch);

if ($result === false) {
    $error_number = curl_errno($ch);
    $error_message = curl_error($ch);

    echo "cURL error ($error_number): $error_message\n";

    // エラー番号 7 は、接続に失敗したことを示します。
    if ($error_number === 7) {
        echo "接続エラーが発生しました。ホスト名が正しいか、ネットワーク接続を確認してください。\n";
    }
} else {
    echo "成功: " . $result . "\n";
}

curl_close($ch);

?>

このPHPのサンプルコードは、cURLライブラリのcurl_error関数を使用して、cURL操作中に発生したエラーの詳細情報を取得する方法を示しています。特に、エラーコード7（CURLE_COULDNT_CONNECT）が発生した場合の対処法を解説しています。

curl_init関数で存在しないホスト（https://invalid.example.com）への接続を試み、`curl_exec`関数で実行します。`curl_exec`関数が`false`を返した場合、エラーが発生したことを意味します。

curl_errno関数は、最後に発生したエラーのエラーコードを整数値で返します。一方、curl_error関数は、同じエラーに対応するエラーメッセージを文字列で返します。引数には、cURLセッションを表すCurlHandleオブジェクトを渡します。

サンプルコードでは、curl_errnoでエラーコードを取得し、curl_errorでエラーメッセージを取得して表示します。エラーコードが7の場合、接続エラーが発生したことを示唆し、ホスト名が正しいか、ネットワーク接続に問題がないかを確認するよう促すメッセージを表示します。

最後に、curl_close関数でcURLセッションを閉じ、リソースを解放します。この例を通して、cURLエラー発生時のエラー情報の取得と、特定のエラーコードに対する適切な対応を学ぶことができます。システムエンジニアを目指す上で、外部APIとの連携などで発生する可能性のあるエラーへの対処は重要なスキルです。

サンプルコードの注意点と補足です。curl_error関数は、直前のcurl_execでエラーが発生した場合にのみ有効なエラーメッセージを返します。エラーが発生しなかった場合、空文字列が返されます。エラー番号を確認するには、curl_errno関数を使用します。cURL エラー 7 は、名前解決の失敗、接続拒否など、様々な接続問題を意味します。ホスト名が正しいか、DNS設定やネットワーク接続に問題がないか確認が必要です。本番環境では、エラーメッセージをそのまま表示せず、ログに記録するなどの処理を検討してください。エラー処理を適切に行うことで、問題発生時の原因特定を容易にできます。