- POSTデータは連想配列のまま渡さず、
json_encode($payload, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE)でJSON文字列に変換し、Content-Type: application/jsonヘッダーを付与する - 外部APIの遅延でPHPプロセスがハングするのを防ぐため、
CURLOPT_CONNECTTIMEOUT(接続待機)とCURLOPT_TIMEOUT(全体待機)を必ず明示する curl_exec() === falseは通信エラーしか検知できないため、curl_getinfo($ch, CURLINFO_HTTP_CODE)でHTTPステータスコード(4xx / 5xx)も必ずチェックする
1. 発生する症状・やりたいこと(前提条件)
決済API・Webhook通知(Slack / Discord等)・生成AI APIなどをPHP標準の cURL 拡張モジュールから呼び出す際、最小限のサンプルコードをそのまま本番へ載せると以下のようなトラブルが発生しがちです。
CURLOPT_POSTFIELDSに配列を直接渡してしまい、multipart/form-data扱いになってAPI側から400 Bad Requestや415 Unsupported Media Typeが返る- 通信先サーバーが応答しないときにタイムアウトせず、PHP-FPMのワーカープロセスが占有されてサイト全体が
504 Gateway Timeoutになる - APIが
401 Unauthorizedや500 Internal Server Errorを返しているのに、curl_exec()が文字列を返すため正常終了と誤判定してしまう
// 期待する動作:タイムアウト・通信失敗・HTTP 4xx/5xx を厳密に区別してJSONを送受信する
POST https://api.example.com/v1/orders
Content-Type: application/json; charset=utf-8
{"order_id": 1024, "customer": "山田太郎"} ---> HTTP 200/201 & レスポンス配列を取得
2. ❌ やりがちなNGコード vs ⭕ 実務で使える正解コード
本番障害やエラー握りつぶしを引き起こす典型的なNG実装と、PHP 8.3 / 8.4 対応の堅牢な正解コード(コピペ即戦力関数)を比較します。
<?php
$ch = curl_init('https://api.example.com/v1/orders');
// NG 1: 配列のまま渡すと multipart/form-data になり JSON として認識されない
curl_setopt($ch, CURLOPT_POSTFIELDS, ['order_id' => 1024]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
// NG 2: タイムアウト未設定のため、相手サーバーが固まると無制限に待ち続ける
$response = curl_exec($ch);
// NG 3: HTTP 400 や 500 でも $response は false にならず、エラーを検知できない
if ($response === false) {
throw new RuntimeException('送信失敗');
}
$data = json_decode($response, true);
CURLOPT_POSTFIELDS にPHPの配列を渡すと、リクエスト形式が強制的に multipart/form-data になってしまいます。また、curl_exec() が false を返すのは「DNS解決失敗」や「タイムアウト」などのネットワーク層エラー時のみで、HTTP 400 / 500 エラー時はエラーJSON文字列が返るため CURLINFO_HTTP_CODE によるステータス判定が必須です。
<?php
declare(strict_types=1);
/**
* 外部APIへJSONをPOST送信し、デコード済みレスポンス配列を返す
*
* @param string $url 送信先エンドポイントURL
* @param array<string, mixed> $payload 送信する連想配列データ
* @param string|null $token Bearerトークン(不要な場合はnull)
* @return array<string, mixed>
* @throws RuntimeException|JsonException
*/
function postJsonWithCurl(string $url, array $payload, ?string $token = null): array
{
$jsonBody = json_encode($payload, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
$headers = [
'Content-Type: application/json; charset=utf-8',
'Accept: application/json',
'Content-Length: ' . strlen($jsonBody),
];
if ($token !== null && $token !== '') {
$headers[] = 'Authorization: Bearer ' . $token;
}
$ch = curl_init($url);
if ($ch === false) {
throw new RuntimeException('cURLの初期化に失敗しました');
}
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $jsonBody,
CURLOPT_HTTPHEADER => $headers,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 5, // 接続確立までの最大待機秒数
CURLOPT_TIMEOUT => 15, // 通信全体の最大待機秒数
]);
$rawResponse = curl_exec($ch);
$httpCode = (int)curl_getinfo($ch, CURLINFO_HTTP_CODE);
$curlErrno = curl_errno($ch);
$curlError = curl_error($ch);
if ($rawResponse === false || $curlErrno !== 0) {
throw new RuntimeException(sprintf('cURL通信エラー (errno=%d): %s', $curlErrno, $curlError));
}
if ($httpCode < 200 || $httpCode >= 300) {
throw new RuntimeException(sprintf('APIエラー (HTTP %d): %s', $httpCode, $rawResponse));
}
return ($rawResponse === '') ? [] : json_decode($rawResponse, true, 512, JSON_THROW_ON_ERROR);
}
3. 仕様・使い分けの比較早見表
JSON API通信で必須となる cURL オプションの役割と、実務での推奨設定値の早見表です。
| 方法 / オプション定数 | 特徴・挙動 | おすすめな場面・推奨設定 |
|---|---|---|
CURLOPT_POSTFIELDS |
文字列を渡すとそのままリクエストボディとして送信。配列を渡すと multipart/form-data に変化する |
JSON送信時は必ず json_encode() 済みの文字列を渡す |
CURLOPT_CONNECTTIMEOUT |
TCP接続(ハンドシェイク)完了までのタイムアウト秒数 | 相手サーバーのダウンを即座に検知するため 3〜5秒 を推奨 |
CURLOPT_TIMEOUT |
接続開始からレスポンス受信完了までのトータル制限秒数 | 同期Webリクエスト内では 10〜15秒、バッチ処理では要件に応じて設定 |
CURLOPT_RETURNTRANSFER |
true にするとレスポンスを画面出力せず curl_exec() の戻り値として文字列で返す |
API連携では常に true を指定する |
CURLINFO_HTTP_CODE |
curl_getinfo() で最後に受信したHTTPステータスコード(200, 404, 500 等)を整数取得 |
200 <= $code && $code < 300 でAPIの成否を判定する |
CURLOPT_FAILONERROR |
true にするとHTTP 400以上のときに curl_exec() が false を返す |
エラー時のレスポンスボディ(エラー詳細JSON)が取得できなくなるため、原則 false(デフォルト)のままにする |
4. 実務でハマりやすい3つの注意点
外部APIとのJSON通信を本番運用する際に、現場のコードレビューで頻繁に指摘される3つの落とし穴です。
HTTP 400 や 422(バリデーションエラー)を検知しようとして CURLOPT_FAILONERROR => true を設定すると、curl_exec() が即座に false を返し、API側が返してくれたエラーメッセージのJSONボディが破棄されてしまいます。エラー原因をログに残すためにも、ステータス判定は必ず CURLINFO_HTTP_CODE で行ってください。
PHPでは連想配列とリスト配列が同じ array 型のため、中身が空の $payload = [] をそのまま json_encode() すると "{}" ではなく "[]" になり、API側で型エラーになることがあります。空オブジェクトを送る可能性がある箇所は (object)$payload にキャストするか、JSON_FORCE_OBJECT の利用を検討してください。
Webhookや削除・更新系APIでは、成功時にステータス 204 No Content(レスポンスボディが空文字 "")を返すものがあります。空文字をそのまま json_decode('', true, 512, JSON_THROW_ON_ERROR) に渡すと Syntax error 例外がスローされるため、事前に $rawResponse === '' の判定を入れておくと安全です。
5. よくある質問(FAQ)
PHPのcURL実装に関してよく検索される疑問と回答をまとめました。
Q. PHP 8以降で curl_close($ch) を呼ぶ必要はありますか?
PHP 8.0以降、curl_init() の戻り値はリソース型から CurlHandle オブジェクトに変更され、curl_close() は何もしない関数(No-op)となりました。さらにPHP 8.5では非推奨(Deprecated)となるため、PHP 8以降のコードでは curl_close($ch) を記述しないのがベストプラクティスです。
Q. ローカル環境で「SSL certificate problem (errno=60)」が出る場合はどうすればいいですか?
PHP実行環境に最新のCA証明書バンドル(cacert.pem)が設定されていないことが原因です。安易に CURLOPT_SSL_VERIFYPEER => false で検証を無効化すると中間者攻撃(MITM)の脆弱性になるため、php.ini の curl.cainfo に正しい証明書パスを設定して解決してください。
Q. file_get_contents() や Guzzle とどう使い分ければいいですか?
外部ライブラリを導入できない環境や単発のAPI呼び出しには、細かなタイムアウト制御と接続再利用が効く標準の cURL が最適です。一方、非同期並列リクエストやミドルウェアによる自動リトライが必要な大規模開発(Laravel等)では、Guzzle(またはLaravelの Http ファサード)を採用するのがおすすめです。