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

<?php

/**
 * curl_setopt_array を使用してHTTP GETリクエストを実行するサンプルコード。
 *
 * このスクリプトは、指定されたURLに対してGETリクエストを送信し、
 * レスポンスを表示します。エラーハンドリングも含まれています。
 * curl_setopt_array が期待通りに動作しない場合の原因として、
 * cURLセッションの初期化失敗や、オプション設定後の実行時のエラーが考えられます。
 *
 * この例では、公開されているJSON Placeholder APIを利用します。
 */

// ターゲットURL
$url = "https://jsonplaceholder.typicode.com/posts/1";

// cURLセッションを初期化
// curl_init() は CurlHandle オブジェクト、または失敗時に false を返します。
$ch = curl_init();

if ($ch === false) {
    // cURLセッションの初期化に失敗した場合のエラー処理
    echo "エラー: cURLセッションの初期化に失敗しました。\n";
    exit;
}

// curl_setopt_array() に渡すオプション配列を定義
// キーは CURLOPT_XXX 定数、値はそれぞれのオプション設定です。
$options = [
    CURLOPT_URL            => $url,          // リクエストを送信するURL
    CURLOPT_RETURNTRANSFER => true,          // 転送結果を文字列で取得する (出力しない)
    CURLOPT_HEADER         => false,         // レスポンスヘッダを含めない
    CURLOPT_FOLLOWLOCATION => true,          // HTTPリダイレクトを追跡する
    CURLOPT_TIMEOUT        => 30,            // 最大実行時間 (秒)
    CURLOPT_SSL_VERIFYPEER => true,          // SSL証明書の検証を有効にする
    CURLOPT_SSL_VERIFYHOST => 2,             // ホスト名の検証レベル (PHP 5.4.0以降は2を指定)
];

// curl_setopt_array() を使用して複数のオプションを一度に設定
// すべてのオプションが正常に設定された場合に true を返します。
if (curl_setopt_array($ch, $options)) {
    echo "cURLオプションの設定に成功しました。\n";

    // cURLセッションを実行し、結果を取得
    // 成功した場合、CURLOPT_RETURNTRANSFER が true なので結果文字列を返します。
    // 失敗した場合、false を返します。
    $response = curl_exec($ch);

    // cURL実行後のエラーチェック
    if (curl_errno($ch)) {
        // エラーが発生した場合、エラーコードとエラーメッセージを表示
        echo "cURL実行エラー (" . curl_errno($ch) . "): " . curl_error($ch) . "\n";
    } else {
        // 成功した場合、取得したレスポンスを表示
        echo "--- レスポンス開始 ---\n";
        echo $response;
        echo "\n--- レスポンス終了 ---\n";
    }
} else {
    // オプション設定に失敗した場合のエラー処理
    // この関数は、通常、無効なオプションキーが含まれている場合に失敗します。
    echo "エラー: cURLオプションの設定に失敗しました。\n";
}

// cURLセッションを閉じる (リソースを解放)
curl_close($ch);

?>

curl_setopt_array関数は、PHPのcURL拡張機能の一部で、HTTPリクエストなどを行うための複数のcURLオプションを一度に設定するために使用されます。

この関数は、二つの引数を取ります。一つ目は、curl_init()関数で初期化されたcURLセッションのハンドル（CurlHandleオブジェクト）です。二つ目は、設定したいcURLオプションをキーと値のペアで指定する配列です。例えば、リクエスト先のURLはCURLOPT_URL、転送結果を文字列で受け取るかはCURLOPT_RETURNTRANSFERなどの定数で指定します。この関数は、全てのオプションが正常に設定された場合にtrueを返し、一つでも設定に失敗した場合はfalseを返します。オプションのキーが無効である場合などに失敗することがあります。

提示されたサンプルコードでは、まずcurl_init()でcURLセッションを開始し、その結果が成功したかを確認しています。次に、リクエスト先のURLやレスポンスの取得方法など、必要なオプションを$optionsという配列にまとめて定義しています。そして、この$options配列をcurl_setopt_array()に渡し、一度に複数の設定を行っています。設定が成功した場合、curl_exec()で実際にHTTP GETリクエストを実行し、その結果を表示します。curl_init()の失敗、curl_setopt_array()での設定失敗、またはcurl_exec()の実行エラーなど、それぞれの段階でエラーを丁寧にチェックし、適切にメッセージを出力している点が重要です。最後にcurl_close()でセッションを閉じ、リソースを解放しています。このように複数のオプションを一括で設定することで、コードが簡潔になり、効率的にcURLリクエストを扱えるようになります。

<?php

/**
 * curl_setopt_array を使用してHTTP POSTリクエストを送信します。
 *
 * @param string $url POSTリクエストを送信するターゲットURL。
 * @param array $postData 送信するPOSTデータの連想配列。
 * @return string|false リクエストが成功した場合はレスポンスの内容、失敗した場合はfalse。
 */
function sendCurlPostRequest(string $url, array $postData)
{
    // cURLセッションを初期化します。
    $ch = curl_init();

    if ($ch === false) {
        error_log('cURLセッションの初期化に失敗しました。');
        return false;
    }

    // POSTデータをURLエンコードされた文字列に変換します。
    // 例: ['name' => 'John Doe', 'age' => 30] は "name=John+Doe&age=30" になります。
    $postFields = http_build_query($postData);

    // cURLオプションを連想配列で定義します。
    $options = [
        CURLOPT_URL            => $url,            // リクエスト先のURL
        CURLOPT_POST           => true,            // HTTP POSTリクエストを有効にします。
        CURLOPT_POSTFIELDS     => $postFields,     // 送信するPOSTデータ。
        CURLOPT_RETURNTRANSFER => true,            // 転送結果を文字列として返します（画面出力はしません）。
        CURLOPT_HEADER         => false,           // レスポンスヘッダをレスポンスに含めません。
        CURLOPT_FAILONERROR    => true,            // HTTPステータスコードが400以上の場合にエラーとします。
        CURLOPT_TIMEOUT        => 30,              // 最大実行時間を30秒に設定します。
    ];

    // curl_setopt_array を使用して、定義した複数のオプションを一括で設定します。
    // 成功した場合は true、失敗した場合は false を返します。
    if (!curl_setopt_array($ch, $options)) {
        error_log('cURLオプションの設定に失敗しました: ' . curl_error($ch));
        curl_close($ch);
        return false;
    }

    // cURLセッションを実行し、レスポンスを取得します。
    $response = curl_exec($ch);

    // cURL実行中にエラーが発生したか確認します。
    if (curl_errno($ch)) {
        error_log('cURLエラーが発生しました: ' . curl_error($ch));
        $response = false;
    }

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

    return $response;
}

// --- サンプル使用例 ---
// テスト用のPOSTリクエストを受け付けるURL (例: httpbin.org はテストに便利です)
$targetUrl = 'https://httpbin.org/post';

// 送信するPOSTデータ
$dataToSend = [
    'username' => 'testuser',
    'password' => 'securepassword123',
    'email'    => 'test@example.com',
];

echo "POSTリクエストを {$targetUrl} へ送信中...\n";

// 関数を呼び出してPOSTリクエストを送信します。
$result = sendCurlPostRequest($targetUrl, $dataToSend);

if ($result !== false) {
    echo "レスポンス:\n";
    // レスポンスがJSON形式の場合、デコードして整形すると見やすくなります。
    $decodedResponse = json_decode($result, true);
    if (json_last_error() === JSON_ERROR_NONE) {
        print_r($decodedResponse);
    } else {
        echo $result . "\n";
    }
} else {
    echo "POSTリクエストの送信に失敗しました。\n";
}

curl_setopt_array関数は、PHPのcURL拡張機能において、一度に複数のオプションをcURLセッションに設定するための関数です。個々のオプションをcurl_setopt関数で一つずつ設定する代わりに、オプションのキーと値のペアからなる連想配列を渡すことで、コードをより簡潔にし、可読性を高めることができます。

この関数の第1引数には、curl_init()によって初期化されたcURLセッションハンドルを指定します。これは、どの通信セッションにオプションを設定するかを識別するためのものです。第2引数には、設定したいオプションを連想配列で渡します。例えば、CURLOPT_URLキーにリクエスト先のURLを、CURLOPT_POSTキーにtrueを設定することで、POSTリクエストを指定できます。

戻り値は真偽値（bool）です。指定した全てのオプションが正常に設定できた場合はtrueを返し、いずれかのオプション設定に失敗した場合はfalseを返します。

サンプルコードでは、この関数を用いてPOSTリクエストに必要な設定（URL、POSTメソッドの有効化、送信データ、レスポンスの取得方法など）を$optionsという配列にまとめて定義し、一括でcURLセッションに適用しています。これにより、どのような通信設定が行われているかが一目でわかりやすくなっています。このように、curl_setopt_arrayは、外部APIとの連携など、複雑な通信設定を効率的に管理する際に非常に便利な関数です。