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

Copy
1<?php
2
3/**
4 * 指定されたURLからコンテンツをフェッチし、HTTP転送デコードの挙動を制御します。
5 * CURLOPT_HTTP_TRANSFER_DECODING の利用方法を示します。
6 *
7 * @param string $url フェッチするURL
8 * @param bool $enableTransferDecoding trueでデコードを有効にし（デフォルト）、falseで無効にします。
9 * @return string|false フェッチされたコンテンツ、または失敗した場合はfalse
10 */
11function fetchContentWithDecodingControl(string $url, bool $enableTransferDecoding = true)
12{
13    $ch = curl_init();
14
15    if ($ch === false) {
16        error_log('cURL初期化に失敗しました。');
17        return false;
18    }
19
20    curl_setopt($ch, CURLOPT_URL, $url);
21
22    // curl_exec() が結果を文字列として返すように設定します。
23    // これは、ウェブコンテンツをプログラムで取得し処理する際の一般的な設定です。
24    // （キーワード: CURLOPT_RETURNTRANSFER に関連）
25    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
26
27    // CURLOPT_HTTP_TRANSFER_DECODING は、HTTP転送エンコーディング（例: chunked, gzip）
28    // のデコードをcURLが行うかどうかを制御します。
29    // true (デフォルト): cURLが自動的にデコードを行います。
30    // false: cURLはデコードを行わず、生のデータ（エンコードされた状態）を返します。
31    // このサンプルでは、明示的にデコードを無効にするケースを示します。
32    curl_setopt($ch, CURLOPT_HTTP_TRANSFER_DECODING, $enableTransferDecoding);
33
34    // HTTP/HTTPSリクエストでリダイレクトを自動的に追跡します。
35    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
36
37    // SSL証明書の検証を無効にします。
38    // 開発目的で利用されることがありますが、本番環境ではセキュリティリスクがあるため推奨されません。
39    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
40    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
41
42    $response = curl_exec($ch);
43
44    if (curl_errno($ch)) {
45        $errorMessage = 'cURLエラーが発生しました: ' . curl_error($ch) . ' (コード: ' . curl_errno($ch) . ')';
46        error_log($errorMessage);
47        curl_close($ch);
48        return false;
49    }
50
51    curl_close($ch);
52
53    return $response;
54}
55
56// --- サンプルコードの利用例 ---
57// HTTP転送デコードを無効にして 'http://example.com' のコンテンツをフェッチします。
58// 'http://example.com' は通常シンプルなHTMLを返すため、デコードが無効でも見た目の違いは少ないですが、
59// サーバーが gzip 圧縮などを使用している場合は、生の圧縮データが返されます。
60$contentWithoutDecoding = fetchContentWithDecodingControl('http://example.com', false);
61
62if ($contentWithoutDecoding !== false) {
63    echo "--- HTTP転送デコードを無効にしてフェッチしたコンテンツの一部 (最大500文字) ---\n";
64    // マルチバイト文字列を安全に切り詰めるために mb_strimwidth を使用
65    echo mb_strimwidth($contentWithoutDecoding, 0, 500, "...", 'UTF-8') . "\n";
66} else {
67    echo "コンテンツのフェッチに失敗しました。\n";
68}

このサンプルコードは、PHPのcURLライブラリを使って指定されたURLからコンテンツを取得する際、HTTP転送デコードの挙動を制御する方法を具体的に示しています。CURLOPT_HTTP_TRANSFER_DECODINGは、cURLがHTTPレスポンスで受け取ったデータに対して、gzip圧縮やチャンク転送エンコーディングなどの処理を自動で行うかどうかを設定する定数です。

この定数をtrueに設定すると（これがデフォルトの挙動です）、cURLはサーバーから受け取ったエンコード済みのデータを自動的にデコードし、人間が読んだりプログラムで処理したりしやすい形式のコンテンツを返します。しかし、falseに設定すると、cURLはデコードを行わず、サーバーから送られてきたエンコードされた生のデータをそのまま返します。

サンプルコードのfetchContentWithDecodingControl関数では、第2引数$enableTransferDecodingによってCURLOPT_HTTP_TRANSFER_DECODINGの設定を柔軟に切り替えられるようにしています。これにより、デコードを有効にする場合と無効にする場合の挙動の違いを確認できます。特に、CURLOPT_RETURNTRANSFERをtrueに設定することで、curl_exec()関数が実行結果を画面に出力する代わりに文字列として関数に返し、その後の処理で利用できるようになります（これはキーワードCURLOPT_RETURNTRANSFERに関連する重要な設定です）。

また、CURLOPT_FOLLOWLOCATIONはHTTPリダイレクトを自動で追跡する設定であり、CURLOPT_SSL_VERIFYPEERとCURLOPT_SSL_VERIFYHOSTはSSL証明書の検証を制御しますが、開発環境以外での無効化はセキュリティリスクがあるため注意が必要です。この関数は、コンテンツの取得に成功すればその内容を文字列として返し、失敗した場合はエラーログを出力しfalseを返します。

Copy
1<?php
2
3/**
4 * 指定されたURLからHTTPコンテンツを取得し、HTTP転送エンコーディングを自動デコードして表示します。
5 *
6 * この関数は、CURLOPT_HTTP_TRANSFER_DECODING オプションの利用方法、
7 * および CURLOPT_HTTPHEADER オプションの利用方法を示します。
8 *
9 * @param string $url リクエストを送信するURL。
10 * @return void
11 */
12function fetchDecodedContent(string $url): void
13{
14    // 1. cURLセッションを初期化します。
15    // cURLはURLと対話するためのライブラリです。
16    $ch = curl_init();
17
18    if ($ch === false) {
19        echo "エラー: cURLセッションの初期化に失敗しました。\n";
20        return;
21    }
22
23    // 2. cURLオプションを設定します。
24    // CURLOPT_URL: リクエストを送信するURLを設定します。
25    curl_setopt($ch, CURLOPT_URL, $url);
26
27    // CURLOPT_RETURNTRANSFER: レスポンスボディを文字列として取得するように設定します。
28    // trueに設定すると、curl_exec() は取得したデータを文字列として返します。
29    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
30
31    // CURLOPT_HEADER: レスポンスヘッダも取得するように設定します。
32    // trueに設定すると、レスポンス文字列の先頭にHTTPヘッダが含まれます。
33    curl_setopt($ch, CURLOPT_HEADER, true);
34
35    // CURLOPT_HTTP_TRANSFER_DECODING: HTTPコンテンツ転送エンコーディングの自動デコードを制御します。
36    // - true (デフォルト): cURLは、Content-Encoding (例: gzip, deflate) ヘッダに基づいて
37    //   レスポンスボディを自動的にデコードします。
38    // - false: cURLはデコードを行わず、生のエンコードされたボディを返します。
39    //   この場合、アプリケーション側で手動デコードが必要です。
40    // ここでは、デフォルトの動作である自動デコードを明示的に有効にしています。
41    curl_setopt($ch, CURLOPT_HTTP_TRANSFER_DECODING, true);
42
43    // CURLOPT_ENCODING: サーバーに、クライアントが受け入れ可能なコンテンツエンコーディングを通知します。
44    // 空文字列 ("") を設定すると、cURLがサポートするすべてのエンコーディング (gzip, deflateなど) を
45    // 受け入れることを意味します。これにより、サーバーは通常、Content-Encodingヘッダを付けて
46    // 圧縮されたレスポンスを返す可能性があり、CURLOPT_HTTP_TRANSFER_DECODING が有効な場合にcURLがそれをデコードします。
47    curl_setopt($ch, CURLOPT_ENCODING, "");
48
49    // CURLOPT_HTTPHEADER: カスタムHTTPリクエストヘッダを設定します。
50    // 配列形式で、各要素が 'Header-Name: Value' の形式である必要があります。
51    // これは、PHP のキーワード `curlopt_httpheader` に関連する設定です。
52    $customHeaders = [
53        'Accept: application/json',          // JSON形式のレスポンスを優先して受け入れることをサーバーに通知
54        'User-Agent: MySimpleCurlClient/1.0', // クライアントアプリケーションの識別情報
55    ];
56    curl_setopt($ch, CURLOPT_HTTPHEADER, $customHeaders);
57
58    // 3. cURLリクエストを実行し、レスポンスを取得します。
59    $response = curl_exec($ch);
60
61    // 4. エラーチェックを行います。
62    if (curl_errno($ch)) {
63        // cURLの実行中にエラーが発生した場合
64        echo 'cURLエラー: ' . curl_error($ch) . "\n";
65    } else {
66        // レスポンスからヘッダとボディを分離します。
67        // CURLINFO_HEADER_SIZE は取得したレスポンスヘッダのバイトサイズを返します。
68        $headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
69        $responseHeaders = substr($response, 0, $headerSize);
70        $responseBody = substr($response, $headerSize);
71
72        echo "--- レスポンスヘッダ ---\n";
73        echo $responseHeaders;
74        echo "\n--- レスポンスボディ (自動デコード済み) ---\n";
75        echo $responseBody;
76
77        echo "\n\n補足: 上記レスポンスボディは、";
78        echo "CURLOPT_HTTP_TRANSFER_DECODING オプションが true に設定されているため、";
79        echo "サーバーから圧縮された形式で送信された場合でも、cURLによって自動的にデコードされた結果です。\n";
80        echo "（例: httpbin.org/gzip の場合、Content-Encoding: gzip ヘッダが含まれていても、ボディは展開されています。）\n";
81    }
82
83    // 5. cURLセッションをクローズします。
84    // リソースを解放するために重要です。
85    curl_close($ch);
86}
87
88// --- サンプル使用例 ---
89// httpbin.org は、HTTPリクエストとレスポンスのテストに便利なサービスです。
90// /gzip エンドポイントは、Content-Encoding: gzip ヘッダと圧縮されたJSONボディを返します。
91// これにより、CURLOPT_HTTP_TRANSFER_DECODING の効果を明確に確認できます。
92$targetUrl = 'https://httpbin.org/gzip'; 
93// または、圧縮されないシンプルなGETリクエストをテストする場合:
94// $targetUrl = 'https://httpbin.org/get';
95
96echo "URL: {$targetUrl} からコンテンツを取得します。\n";
97echo "CURLOPT_HTTP_TRANSFER_DECODING オプションにより、HTTP転送エンコーディングは自動的にデコードされます。\n";
98echo "CURLOPT_HTTPHEADER オプションにより、カスタムヘッダが送信されます。\n\n";
99
100fetchDecodedContent($targetUrl);
101
102?>

このPHPサンプルコードは、指定されたURLからHTTPコンテンツを取得する際に、HTTP転送エンコーディングの自動デコード機能と、カスタムHTTPヘッダの送信方法を示すものです。

CURLOPT_HTTP_TRANSFER_DECODINGは、cURLがHTTPレスポンスのボディを自動的にデコードするかどうかを制御する定数です。ウェブサーバーはデータ転送量を削減するため、コンテンツをgzipなどの形式で圧縮して送信することがありますが、この定数をtrueに設定すると、cURLはサーバーから圧縮されたデータを受け取った際に自動的にそれを解凍し、デコードされた生データとしてアプリケーションに提供します。これにより、開発者は手動でデコード処理を記述する手間を省くことができます。

また、CURLOPT_ENCODINGオプションを空文字列で設定することで、cURLはサポートする全ての圧縮エンコーディングを受け入れることをサーバーに通知し、圧縮されたレスポンスを促します。

さらに、CURLOPT_HTTPHEADERオプションは、AcceptやUser-AgentといったカスタムHTTPリクエストヘッダをサーバーに送信するために利用されます。これにより、クライアントが受け入れ可能なデータ形式をサーバーに伝えたり、自身のアプリケーションを識別させたりすることが可能です。

サンプルコードのfetchDecodedContent関数は、引数としてリクエスト対象の$urlを受け取ります。この関数は内部でcURLセッションを初期化し、これらのオプションを含む必要な設定を行った後、リクエストを実行してレスポンスを取得します。エラーが発生した場合はその情報を表示し、成功した場合はレスポンスヘッダと、自動デコードされたボディ内容を出力します。この関数は画面に表示を行うため、特定の値を戻り値として返しません（void）。