基本的な使用方法 ¶

HTTP リクエストを送信するためには、yii\httpclient\Client をインスタンス化して、その createRequest() メソッドを使って、HTTP リクエストを作成する必要があります。 次に、あなたの目的に従ってリクエストの全てのパラメータを構成して、リクエストを送信します。 結果として、あなたは、レスポンスの全ての情報とデータを保持する yii\httpclient\Response のインスタンスを受け取ることになります。 例えば、

use yii\httpclient\Client;

$client = new Client();
$response = $client->createRequest()
    ->setMethod('post')
    ->setUrl('http://example.com/api/1.0/users')
    ->setData(['name' => 'John Doe', 'email' => 'johndoe@example.com'])
    ->send();
if ($response->isOk) {
    $newUserId = $response->data['id'];
}

新しいリクエストを準備する作業を単純化するために、get()、post()、put() などのショートカット・メソッドを使っても構いません。 同一のドメインに対して複数のリクエストを送信する場合 (例えば REST API 使用する場合) は、 単一の yii\httpclient\Client インスタンスを使って、その baseUrl プロパティにそのドメインを設定することが出来ます。 そのようにすると、新しいリクエストを作成するときに、相対 URL だけを指定することが出来るようになります。 従って、何らかの REST API に対する数個のリクエストは、下記のように書くことが出来ます。

use yii\httpclient\Client;

$client = new Client(['baseUrl' => 'http://example.com/api/1.0']);

$newUserResponse = $client->post('users', ['name' => 'John Doe', 'email' => 'johndoe@example.com'])->send();
$articleResponse = $client->get('articles', ['name' => 'Yii 2.0'])->send();
$client->post('subscriptions', ['user_id' => $newUserResponse->data['id'], 'article_id' => $articleResponse->data['id']])->send();

さまざまなコンテント形式を使う ¶

デフォルトでは、HTTP リクエス・トデータは 'form-urlencoded'、例えば、param1=value1&param2=value2 として送信されます。 これはウェブ・フォームでは一般的な形式ですが、REST API にとってはそうではなく、 通常はコンテントが JSON または XML の形式であることが要求されます。 リクエスト・コンテントに使用される形式は、format プロパティまたは setFormat() メソッドを使用して設定することが出来ます。 下記の形式がサポートされています。

• yii\httpclient\Client::FORMAT_JSON - JSON 形式
• yii\httpclient\Client::FORMAT_URLENCODED - RFC1738 によって urlencode されたクエリ文字列
• yii\httpclient\Client::FORMAT_RAW_URLENCODED - PHP_QUERY_RFC3986 によって urlencode されたクエリ文字列
• yii\httpclient\Client::FORMAT_XML - XML 形式

例えば、

use yii\httpclient\Client;

$client = new Client(['baseUrl' => 'http://example.com/api/1.0']);
$response = $client->createRequest()
    ->setFormat(Client::FORMAT_JSON)
    ->setUrl('articles/search')
    ->setData([
        'query_string' => 'Yii',
        'filter' => [
            'date' => ['>' => '2015-08-01']
        ],
    ])
    ->send();

レスポンス・オブジェクトは、'Content-Type' ヘッダとコンテント自体に基づいて、コンテント形式を自動的に検出します。 従って、ほとんどの場合レスポンスの形式を指定する必要はなく、単純に getData() メソッドまたは data プロパティを使えば、レスポンスを解析することが出来ます。 上記の例の続きとして、レスポンス・データを取得するには次のようにすることが出来ます。

$responseData = $response->getData(); // 全ての記事を取得
count($response->data) // 記事の数を取得
$article = $response->data[0] // 最初の記事を取得

生のコンテントを扱う ¶

誰もあなたに対して内蔵された形式に依存することを強制するものではありません。 HTTP リクエストに生のコンテントを使用する事も、レスポンスの生のコンテントを処理することも可能です。例えば、

use yii\httpclient\Client;

$client = new Client(['baseUrl' => 'http://example.com/api/1.0']);
$response = $client->createRequest()
    ->setUrl('articles/search')
    ->addHeaders(['content-type' => 'application/json'])
    ->setContent('{query_string: "Yii"}')
    ->send();

echo 'Search results:<br>';
echo $response->content;

yii\httpclient\Request は、content が設定されていない場合にだけ、指定された data をフォーマットします。 yii\httpclient\Response は、data を要求した場合にだけ、content を解析します。

リクエストとレスポンスのオブジェクトを事前に構成する ¶

いくつかの似たようなリクエストを単一の yii\httpclient\Client インスタンスを使って処理する場合、 例えば REST API を扱うような場合は、リクエストとレスポンスのオブジェクトのためにあなた自身の構成情報を宣言することによって、 コードを単純化して高速化することが出来ます。 そのためには、yii\httpclient\Client の requestConfig および responsConfig のフィールドを使用します。 例えば、特定のクライアントによって作成される全てのリクエストに対して JSON 形式をセットアップしたい場合は、次のようにします。

use yii\httpclient\Client;

$client = new Client([
    'baseUrl' => 'http://example.com/api/1.0',
    'requestConfig' => [
        'format' => Client::FORMAT_JSON
    ],
    'responseConfig' => [
        'format' => Client::FORMAT_JSON
    ],
]);

$request = $client->createRequest();
echo $request->format; // 出力: 'json'

Tip: 何らかの追加の機能を利用するために、構成情報配列の 'class' キーを使って、 リクエストとレスポンスのオブジェクトにあなた自身のクラスを指定することも可能です。

ヘッダを扱う ¶

setHeaders() メソッドと addHeaders() メソッドを使って、リクエスト・ヘッダを指定することが出来ます。 また、getHeaders() メソッドまたは headers プロパティを使うと、既に定義されているヘッダを \yii\web\HeaderCollection のインスタンスとして取得することが出来ます。 例えば、

use yii\httpclient\Client;

$client = new Client(['baseUrl' => 'http://example.com/api/1.0']);
$request = $client->createRequest()
    ->setHeaders(['content-type' => 'application/json'])
    ->addHeaders(['user-agent' => 'My User Agent']);

$request->getHeaders()->add('accept-language', 'en-US;en');
$request->headers->set('user-agent', 'User agent override');

レスポンス・オブジェクトを取得した後は、getHeaders() メソッドまたは headers プロパティを使って、 すべてのレスポンス・ヘッダにアクセスすることが出来ます。

$response = $request->send();
echo $response->getHeaders()->get('content-type');
echo $response->headers->get('content-encoding');

HTTP Basic 認証 ¶

クライアントは HTTP 認証に対するサポートを内蔵していません。HTTP Basic 認証を使いたい場合は HTTP Basic 認証の形式 に準拠した適切なヘッダを自分で追加しなければなりません。 Basic という単語に続けて、一つの空白と、base64 エンコードされた username:password の文字列とを置いた Authorizaton ヘッダを追加すれば認証できます。

$username = 'yii';
$password = 'verysecret';
$request->headers->set('Authorization', 'Basic ' . base64_encode("$username:$password"));

Note: HTTP Basic 認証はユーザ名とパスワードを平文で送信しますので、 HTTPS を使う安全な接続を通じてのみ使用されるべきです。

クッキーを扱う ¶

クッキーはヘッダの値として送受信されるだけのものですが、yii\httpclient\Request と yii\httpclient\Request は、 \yii\web\Cookie および \yii\web\CookieCollection を使ってクッキーを扱うための独立したインターフェイスを提供しています。

リクエストのクッキーは setCookies() または addCookies() メソッドで指定することが出来ます。 また、getCookies() メソッドまたは cookies プロパティを使うと、既に定義されているクッキーを \yii\web\CookieCollection のインスタンスとして取得することが出来ます。 例えば、

use yii\httpclient\Client;
use yii\web\Cookie;

$client = new Client(['baseUrl' => 'http://example.com/api/1.0']);
$request = $client->createRequest()
    ->setCookies([
        ['name' => 'country', 'value' => 'USA'],
        new Cookie(['name' => 'language', 'value' => 'en-US']),
    ])
    ->addCookies([
        ['name' => 'view_mode', 'value' => 'full']
    ]);

$request->cookies->add(['name' => 'display-notification', 'value' => '0']);

レスポンス・オブジェクトを取得した後は、getCookies() メソッドまたは cookies プロパティを使って、 レスポンスのクッキー全てにアクセスすることが出来ます。

$response = $request->send();
echo $response->getCookies()->get('country');
echo $response->headers->get('PHPSESSID');

単純なコピーを使って、レスポンス・オブジェクトからリクエスト・オブジェクトにクッキーを転送することが出来ます。 例えば、何かのウェブ・アプリケーションでユーザのプロファイルを編集する必要があるとしましょう。 ユーザのプロファイルはログイン後にのみアクセスできますので、最初にログインして、そこで生成されたセッションを使って更に作業をします。

use yii\httpclient\Client;

$client = new Client(['baseUrl' => 'http://example.com']);

$loginResponse = $client->post('login', [
    'username' => 'johndoe',
    'password' => 'somepassword',
])->send();

// $loginResponse->cookies->get('PHPSESSID') が新しいセッション ID を保持している

$client->post('account/profile', ['birthDate' => '10/11/1982'])
    ->setCookies($loginResponse->cookies) // レスポンスのクッキーをリクエストのクッキーに転送
    ->send();

CurlTransport を使ってファイルをダウンロードする ¶

ファイルの中身全体をメモリに読み込まずにファイルをダウンロードすることが出来ます(これは巨大なファイルの場合に特に有用な機能です)。 setOutputFile() メソッドを使って、リクエスト・オブジェクトに(例えば fopen() を使って)ストリーム・リソースを渡します。 これが cURL の CURLOPT_FILE オプションに渡されます。

use yii\httpclient\Client;

$fh = fopen('/path/to/local/file', 'w');
$client = new Client([
    'transport' => 'yii\httpclient\CurlTransport'
]);
$response = $client->createRequest()
    ->setMethod('GET')
    ->setUrl('http://example.com/path/to/remote/file')
    ->setOutputFile($fh)
    ->send();

CurlTransport と CurlFormatter を使ってファイルをアップロードする ¶

ファイルの中身全体をメモリに読み込まずにファイルをアップロードすることが出来ます(これは巨大なファイルの場合に特に有用な機能です)。 CURLFile を使いますので、PHP 5.5.0 以上または PHP 7 が要求されます。

use yii\httpclient\Client;

$client = new Client([
    'transport' => 'yii\httpclient\CurlTransport',     
]);
$response = $client->createRequest()
    ->setFormat(Client::FORMAT_CURL)
    ->setMethod('POST')
    ->setUrl('http://example.com')
    ->setData([
        'name' => 'John Doe',
        'email' => 'johndoe@example.com',
        'file1' => new \CURLFile('/path/to/file1'), 'text/plain', 'file1'),
        'file2' => new \CURLFile('/path/to/file2'), 'text/plain', 'file2'),
    ])
    ->send();