CURLRequest クラス

CURLRequest クラスは、他の Web サイトやサーバーと通信できる、CURL に基づいた軽量な HTTP クライアントです。Google 検索の結果を取得したり、Web ページや画像を取得したり、API と通信したりなど、さまざまな用途に使用できます。

このクラスは、広く利用されているライブラリの 1 つである Guzzle HTTP Client ライブラリをモデルにしています。可能な限り構文は同じに保たれているため、このライブラリが提供するよりも強力なものをアプリケーションが必要とする場合でも、Guzzle を使用するために移行するために変更する必要はほとんどありません。

注意

このクラスを使用するには、PHP のバージョンに cURL ライブラリ がインストールされている必要があります。これは一般的に利用可能な非常に一般的なライブラリですが、すべてのホストが提供するわけではないため、問題が発生した場合はホストに確認してください。

CURLRequest の設定

オプションの共有

重要

この設定は、下位互換性のためだけに存在します。新しいプロジェクトでは使用しないでください。すでに使用している場合でも、無効にすることをお勧めします。

注意

v4.4.0 以降、デフォルト値は false に変更されました。

リクエスト間で全てのオプションを共有したい場合は、**app/Config/CURLRequest.php** で $shareOptions を true に設定します。

<?php

namespace Config;

use CodeIgniter\Config\BaseConfig;

class CURLRequest extends BaseConfig
{
    // ...
    public bool $shareOptions = true;
}

クラスのインスタンスで複数のリクエストを送信する場合、この動作は不要なヘッダーと本文を含むエラーリクエストを引き起こす可能性があります。

注意

v4.2.0 より前のバージョンでは、バグにより $shareOptions が false の場合でも、リクエストの本文はリセットされません。

ライブラリのロード

ライブラリは、手動でロードするか、Services クラスを介してロードできます。

Services クラスでロードするには、curlrequest() メソッドを呼び出します

<?php

$client = \Config\Services::curlrequest();

cURL がリクエストをどのように処理するかを変更するために、最初のパラメータとしてデフォルトオプションの配列を渡すことができます。オプションについては、このドキュメントで後述します。

<?php

$options = [
    'baseURI' => 'http://example.com/api/v1/',
    'timeout' => 3,
];
$client = \Config\Services::curlrequest($options);

注意

$shareOptions が false の場合、クラスコンストラクタに渡されたデフォルトオプションは、すべてのリクエストに使用されます。その他のオプションは、リクエスト送信後にリセットされます。

手動でクラスを作成する場合は、いくつかの依存関係を渡す必要があります。最初のパラメータは Config\App クラスのインスタンスです。2 番目のパラメータは URI インスタンスです。3 番目のパラメータは Response オブジェクトです。4 番目のパラメータは、オプションのデフォルトの $options 配列です。

<?php

$client = new \CodeIgniter\HTTP\CURLRequest(
    new \Config\App(),
    new \CodeIgniter\HTTP\URI(),
    new \CodeIgniter\HTTP\Response(new \Config\App()),
    $options
);

ライブラリの操作

CURL リクエストの操作は、単に Request を作成し、Response オブジェクトを取得することです。これは、通信を処理することを目的としています。その後、情報の処理方法を完全に制御できます。

リクエストの作成

ほとんどの通信は request() メソッドを介して行われ、このメソッドはリクエストを開始し、Response インスタンスを返します。これは、パラメータとして HTTP メソッド、URL、およびオプションの配列を受け取ります。

<?php

$client = \Config\Services::curlrequest();

$response = $client->request('GET', 'https://api.github.com/user', [
    'auth' => ['user', 'pass'],
]);

重要

デフォルトでは、返された HTTP コードが 400 以上の場合、CURLRequest は HTTPException をスローします。レスポンスを取得したい場合は、http_errors オプションを参照してください。

注意

$shareOptions が false の場合、メソッドに渡されたオプションはリクエストに使用されます。リクエストの送信後、それらはクリアされます。全ての要求にオプションを使用する場合は、コンストラクタでオプションを渡します。

レスポンスは CodeIgniter\HTTP\Response のインスタンスであるため、通常のすべての情報を利用できます。

<?php

echo $response->getStatusCode();
echo $response->getBody();
echo $response->header('Content-Type');
$language = $response->negotiateLanguage(['en', 'fr']);

request() メソッドが最も柔軟ですが、次のショートカットメソッドも使用できます。それらはそれぞれ、最初のパラメータとして URL、2 番目のパラメータとしてオプションの配列を受け取ります。

<?php

$client->get('http://example.com');
$client->delete('http://example.com');
$client->head('http://example.com');
$client->options('http://example.com');
$client->patch('http://example.com');
$client->put('http://example.com');
$client->post('http://example.com');

ベース URI

クラスのインスタンス化中に、オプションの 1 つとして baseURI を設定できます。これにより、ベース URI を設定し、そのクライアントを使用してすべてのリクエストを相対 URL で行うことができます。これは、API を使用する場合に特に便利です。

<?php

$client = \Config\Services::curlrequest([
    'baseURI' => 'https://example.com/api/v1/',
]);

// GET http:example.com/api/v1/photos
$client->get('photos');

// GET http:example.com/api/v1/photos/13
$client->delete('photos/13');

相対 URI が request() メソッドまたはショートカットメソッドのいずれかに提供されると、RFC 2986, セクション 2 で説明されているルールに従って、baseURI と組み合わされます。時間を節約するために、組み合わせがどのように解決されるかのいくつかの例を次に示します。

baseURI	URI	結果
http://foo.com	/bar	http://foo.com/bar
http://foo.com/foo	/bar	http://foo.com/bar
http://foo.com/foo	bar	http://foo.com/bar
http://foo.com/foo/	bar	http://foo.com/foo/bar
http://foo.com	http://baz.com	http://baz.com
http://foo.com/?bar	bar	http://foo.com/bar

レスポンスの使用

各 request() 呼び出しは、多くの役立つ情報といくつかの便利なメソッドを含む Response オブジェクトを返します。最もよく使用されるメソッドでは、レスポンス自体を判断できます。

レスポンスのステータスコードと理由句を取得できます

<?php

$code   = $response->getStatusCode(); // 200
$reason = $response->getReason(); // OK

レスポンスからヘッダーを取得できます

<?php

// Get a header line
echo $response->getHeaderLine('Content-Type');

// Get all headers
foreach ($response->headers() as $name => $value) {
    echo $name . ': ' . $response->getHeaderLine($name) . "\n";
}

本文は getBody() メソッドを使用して取得できます

<?php

$body = $response->getBody();

本文は、リモートサーバーによって提供される生の本文です。コンテンツタイプにフォーマットが必要な場合は、スクリプトでそれを処理する必要があります。

<?php

if (strpos($response->header('content-type'), 'application/json') !== false) {
    $body = json_decode($body);
}

リクエストオプション

このセクションでは、コンストラクタ、request() メソッド、またはショートカットメソッドに渡すことができるすべての利用可能なオプションについて説明します。

allow_redirects

デフォルトでは、cURL はリモートサーバーが返す全ての "Location:" ヘッダーに従います。allow_redirects オプションを使用すると、その動作を変更できます。

値を false に設定すると、リダイレクトを一切行いません

<?php

$client->request('GET', 'http://example.com', ['allow_redirects' => false]);

true に設定すると、デフォルト設定がリクエストに適用されます

<?php

$client->request('GET', 'http://example.com', ['allow_redirects' => true]);
/*
 * Sets the following defaults:
 * 'max'       => 5, // Maximum number of redirects to follow before stopping
 * 'strict'    => true, // Ensure POST requests stay POST requests through redirects
 * 'protocols' => ['http', 'https'] // Restrict redirects to one or more protocols
 */

allow_redirects オプションの値として配列を渡して、デフォルトの代わりに新しい設定を指定できます

<?php

$client->request('GET', 'http://example.com', ['allow_redirects' => [
    'max'       => 10,
    'protocols' => ['https'], // Force HTTPS domains only.
]]);

注意

PHP が safe_mode の場合、または open_basedir が有効になっている場合、リダイレクトの追跡は機能しません。

auth

HTTP Basic および Digest 認証のための認証情報を提供できます。Digest 認証をサポートするためには、スクリプトで追加の処理が必要となる場合があります。ここでは、ユーザー名とパスワードを渡すだけです。値は、最初の要素がユーザー名、2番目の要素がパスワードである配列でなければなりません。3番目のパラメータは、使用する認証タイプで、basic または digest のいずれかです。

<?php

$client->request('GET', 'http://example.com', ['auth' => ['username', 'password', 'digest']]);

body

PUT や POST のように、リクエストボディをサポートするリクエストタイプでは、ボディを設定する方法が2つあります。1つ目は、setBody() メソッドを使用する方法です。

<?php

$client->setBody($body)->request('put', 'http://example.com');

2つ目の方法は、body オプションを渡す方法です。これは Guzzle API との互換性を維持するために提供されており、前の例と全く同じように機能します。値は文字列である必要があります。

<?php

$client->request('put', 'http://example.com', ['body' => $body]);

cert

PEM形式のクライアント側証明書の場所を指定するには、cert オプションとして、ファイルへのフルパスを持つ文字列を渡します。パスワードが必要な場合は、最初の要素が証明書のパス、2番目の要素がパスワードである配列に値を設定します。

<?php

$client->request('get', '/', ['cert' => ['/path/server.pem', 'password']]);

connect_timeout

デフォルトでは、CodeIgniter は cURL がウェブサイトへの接続を試みる時間に制限を課していません。この値を変更する必要がある場合は、connect_timeout オプションを使用して、秒単位で時間を渡すことで変更できます。無期限に待機するには 0 を渡すことができます。

<?php

$client->request('GET', 'http://example.com', ['connect_timeout' => 0]);

cookie

これは、CURL がクッキー値を読み込み、クッキー値を保存するために使用するファイル名を指定します。これは、CURL_COOKIEJAR および CURL_COOKIEFILE オプションを使用して行われます。例を示します。

<?php

$client->request('GET', 'http://example.com', ['cookie' => WRITEPATH . 'CookieSaver.txt']);

debug

debug が渡され、true に設定されている場合、スクリプト実行中に追加のデバッグが STDERR にエコーされます。

これは、CURLOPT_VERBOSE を渡し、出力をエコーすることで行われます。したがって、spark serve を介して組み込みサーバーを実行している場合は、コンソールに出力が表示されます。それ以外の場合は、出力はサーバーのエラーログに書き込まれます。

<?php

$client->request('GET', 'http://example.com', ['debug' => true]);

デバッグの値をファイル名として渡すと、出力がファイルに書き込まれます。

<?php

$client->request('GET', 'http://example.com', ['debug' => '/usr/local/curl_log.txt']);

delay

リクエストを送信する前に、ミリ秒単位で一時停止できます。

<?php

// Delay for 2 seconds
$client->request('GET', 'http://example.com', ['delay' => 2000]);

form_params

form_params オプションに連想配列を渡すことで、application/x-www-form-urlencoded POST リクエストでフォームデータを送信できます。これにより、Content-Type ヘッダーがまだ設定されていない場合、application/x-www-form-urlencoded に設定されます。

<?php

$client->request('POST', '/post', [
    'form_params' => [
        'foo' => 'bar',
        'baz' => ['hi', 'there'],
    ],
]);

注意

form_params は、multipart オプションと組み合わせて使用することはできません。どちらか一方を使用する必要があります。application/x-www-form-urlencoded リクエストには form_params を、multipart/form-data リクエストには multipart を使用してください。

headers

setHeader() メソッドを使用することで、このリクエストに必要なヘッダーを設定できますが、ヘッダーの連想配列をオプションとして渡すこともできます。各キーはヘッダーの名前で、各値はヘッダーフィールドを表す文字列または文字列の配列です。

<?php

$client->request('get', '/', [
    'headers' => [
        'User-Agent' => 'testing/1.0',
        'Accept'     => 'application/json',
        'X-Foo'      => ['Bar', 'Baz'],
    ],
]);

コンストラクターにヘッダーが渡されると、それらはデフォルト値として扱われ、後からヘッダー配列や setHeader() の呼び出しによって上書きされます。

http_errors

デフォルトでは、返された HTTP コードが 400 以上の場合、CURLRequest は HTTPException をスローします。

レスポンスボディを確認したい場合は、http_errors を false に設定して、代わりにコンテンツを返すことができます。

<?php

$client->request('GET', '/status/500');
// If the response code is 500, an HTTPException is thrown,
// and a detailed error report is displayed if in development mode.

$response = $client->request('GET', '/status/500', ['http_errors' => false]);
echo $response->getStatusCode(); // 500
echo $response->getBody();       // You can see the response body.

json

json オプションは、JSON エンコードされたデータをリクエストのボディとして簡単にアップロードするために使用されます。application/json の Content-Type ヘッダーが追加され、既に設定されている可能性のある Content-Type を上書きします。このオプションに提供されるデータは、json_encode() が受け入れる任意の値を指定できます。

<?php

$response = $client->request('PUT', '/put', ['json' => ['foo' => 'bar']]);

注意

このオプションでは、json_encode() 関数や Content-Type ヘッダーをカスタマイズすることはできません。それが必要な場合は、データを手動でエンコードし、CURLRequest の setBody() メソッドを介して渡し、setHeader() メソッドで Content-Type ヘッダーを設定する必要があります。

multipart

POST リクエストでファイルやその他のデータを送信する必要がある場合は、multipart オプションを CURLFile クラス とともに使用できます。値は、送信する POST データの連想配列である必要があります。より安全に使用するために、ファイル名の先頭に @ を付ける古いファイルアップロード方法は無効化されました。送信したいファイルはすべて、CURLFile のインスタンスとして渡す必要があります。

<?php

$post_data = [
    'foo'      => 'bar',
    'userfile' => new \CURLFile('/path/to/file.txt'),
];

注意

multipart は、form_params オプションと組み合わせて使用することはできません。どちらか一方のみを使用できます。application/x-www-form-urlencoded リクエストには form_params を、multipart/form-data リクエストには multipart を使用してください。

proxy

バージョン 4.4.0 で新規追加。

連想配列を proxy オプションとして渡すことで、プロキシを設定できます。

<?php

$client->request(
    'GET',
    'http://example.com',
    ['proxy' => 'https://:3128']
);

query

連想配列を query オプションとして渡すことで、クエリ文字列変数として送信するデータを渡すことができます。

<?php

// Send a GET request to /get?foo=bar
$client->request('GET', '/get', ['query' => ['foo' => 'bar']]);

timeout

デフォルトでは、cURL 関数は時間制限なしに、必要な時間だけ実行できます。これは、timeout オプションで変更できます。値は、関数を実行する秒数である必要があります。無期限に待機するには 0 を使用します。

<?php

$client->request('GET', 'http://example.com', ['timeout' => 5]);

user_agent

リクエストの User Agent を指定できます。

<?php

$client->request('GET', 'http://example.com', ['user_agent' => 'CodeIgniter Framework v4']);

verify

このオプションは、SSL 証明書の検証動作を記述します。verify オプションが true の場合、SSL 証明書検証が有効になり、オペレーティングシステムによって提供されるデフォルトの CA バンドルが使用されます。false に設定すると、証明書検証が無効になります（これは安全ではなく、中間者攻撃を許容します！）。カスタム証明書で検証を有効にするために、CA バンドルへのパスを含む文字列に設定できます。デフォルト値は true です。

<?php

// Use the system's CA bundle (this is the default setting)
$client->request('GET', '/', ['verify' => true]);

// Use a custom SSL certificate on disk.
$client->request('GET', '/', ['verify' => '/path/to/cert.pem']);

// Disable validation entirely. (Insecure!)
$client->request('GET', '/', ['verify' => false]);

version

使用する HTTP プロトコルを設定するには、バージョン番号（通常は 1.0 または 1.1、2.0 は v4.3.0 以降でサポートされています）の文字列または浮動小数点数を渡すことができます。

<?php

// Force HTTP/1.0
$client->request('GET', '/', ['version' => 1.0]);