【PHP8.x】CURLOPT_FAILONERROR定数の使い方

Copy
1<?php
2
3/**
4 * CURLOPT_FAILONERROR の使用例
5 *
6 * このオプションを true に設定すると、HTTPステータスコードが 400 (Bad Request) 以上の場合、
7 * cURL リクエストは失敗とみなされ、curl_exec() は false を返します。
8 * 通常、cURL は HTTP エラーコードを受け取っても成功とみなし、レスポンスボディを返します。
9 *
10 * システムエンジニアを目指す初心者向け:
11 * 外部のAPIやウェブサイトと通信する際、エラーレスポンス（例: 404 Not Found, 500 Internal Server Error）
12 * を受け取った場合に、それを明確な失敗として処理したい場合にこのオプションが役立ちます。
13 */
14function demonstrateCurlFailOnError(): void
15{
16    // 意図的に HTTP 404 エラーを返すテスト用URL
17    // このURLは常に HTTP 404 Not Found ステータスコードを返します。
18    $url = 'https://httpbin.org/status/404';
19
20    echo "CURLOPT_FAILONERROR を有効にした cURL リクエストのデモンストレーション:\n";
21    echo "対象URL: {$url}\n\n";
22
23    // cURL セッションを初期化
24    $ch = curl_init();
25
26    if ($ch === false) {
27        echo "cURL の初期化に失敗しました。\n";
28        return;
29    }
30
31    // オプションを設定
32    curl_setopt($ch, CURLOPT_URL, $url);
33    // レスポンスを文字列として取得（画面に直接出力しない）
34    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
35    // ここが CURLOPT_FAILONERROR の設定箇所
36    // HTTPステータスコードが400以上の場合、curl_exec() を false にする
37    curl_setopt($ch, CURLOPT_FAILONERROR, true);
38
39    // cURL リクエストを実行
40    $response = curl_exec($ch);
41
42    // リクエスト結果をチェック
43    if ($response === false) {
44        // CURLOPT_FAILONERROR が true のため、HTTP 4xx/5xx エラーもここで捕捉されます
45        $errorCode = curl_errno($ch);
46        $errorMessage = curl_error($ch);
47        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
48
49        echo "cURL リクエストが失敗しました。\n";
50        echo "  HTTP ステータスコード: {$httpCode}\n";
51        echo "  cURL エラーコード: {$errorCode}\n";
52        echo "  cURL エラーメッセージ: {$errorMessage}\n";
53    } else {
54        // このブロックは CURLOPT_FAILONERROR が true の場合、
55        // HTTP 2xx/3xx ステータスコードの時のみ実行されます。
56        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
57
58        echo "cURL リクエストが成功しました。\n";
59        echo "  HTTP ステータスコード: {$httpCode}\n";
60        echo "  レスポンスボディの先頭部分:\n";
61        echo "  " . substr($response, 0, 150) . (strlen($response) > 150 ? '...' : '') . "\n";
62    }
63
64    // cURL セッションを閉じる
65    curl_close($ch);
66}
67
68// 関数を実行
69demonstrateCurlFailOnError();
70

CURLOPT_FAILONERRORは、PHPのcURL拡張機能で利用される定数です。この定数をcurl_setopt()関数を通じてtrueに設定することで、cURLリクエストのエラーハンドリングの挙動を変更できます。

通常、cURLはHTTPステータスコードが400番台（クライアントエラー）や500番台（サーバーエラー）であっても、レスポンスボディが返されればcurl_exec()関数を成功とみなし、レスポンスを返します。しかし、CURLOPT_FAILONERRORをtrueにすると、HTTPステータスコードが400以上の場合に、curl_exec()がfalseを返すようになります。これにより、HTTPエラーコードを受け取った場合をcURL操作自体の失敗として、より簡単に処理できるようになります。

この定数自体に引数や戻り値はありませんが、curl_setopt()の第三引数にtrueまたはfalseを指定して設定し、その結果がcurl_exec()関数の戻り値に影響を与えます。

サンプルコードでは、HTTP 404エラーを返すよう設定されたURLに対し、CURLOPT_FAILONERRORをtrueにしてcURLリクエストを実行しています。その結果、HTTP 404エラーを受け取った際にcurl_exec()がfalseを返し、リクエストが明確な失敗として処理される様子を示しています。システムエンジニアを目指す初心者の方にとって、外部のAPIなどと通信する際に、エラーレスポンスを確実に検出して適切なエラー処理を実装するために役立つ重要なオプションです。