Programmer's Reference Guide

Zend_Http

導入

Zend_Http_Client は、Hyper-Text Transfer Protocol (HTTP) リクエストを簡単に扱うためのインターフェイスを提供します。 Zend_Http_Client は、HTTP クライアントとしての最低限の機能をサポートしているだけでなく、 HTTP 認証やファイルのアップロードといった高度な機能もサポートしています。リクエストに成功すると (失敗しても) Zend_Http_Response オブジェクトを返します。これを使用すると、レスポンスのヘッダや本文にアクセスできます (このセクションを参照して下さい)。

Zend_Http_Client の使用法

クラスのコンストラクタには、オプションの引数として URL を指定できます (文字列か Zend_Uri_Http オブジェクトのどちらでも可能です)。また、配列あるいは Zend_Config オブジェクトで設定オプションを指定することもできます。どちらも省略することが可能で、その場合は後から setUri() メソッドや setConfig() メソッドで指定します。

例1 Zend_Http_Client のインスタンスの作成

$client = new Zend_Http_Client('http://example.org', array(
    'maxredirects' => 0,
    'timeout'      => 30));
 
// これは、上とまったく同じことです
$client = new Zend_Http_Client();
$client->setUri('http://example.org');
$client->setConfig(array(
    'maxredirects' => 0,
    'timeout'      => 30));
 
// Zend_Config オブジェクトを使ってクライアントの設定を行うこともできます
$config = new Zend_Config_Ini('httpclient.ini', 'secure');
$client->setConfig($config);

注意: Zend_Http_Client は Zend_Uri_Http を用いて URL を検証します。つまり、URL 中にあるパイプ記号 ('|') やキャレット記号 ('^') などの特殊文字はデフォルトでは許可されないということです。これを変更するには、Zend_Uri のオプション 'allow_unwise' を 'TRUE' に設定します。詳細はこのセクションを参照ください。

設定パラメータ

コンストラクタおよび setConfig() メソッドでは、設定パラメータの連想配列あるいは Zend_Config オブジェクトを受け取ります。これらのパラメータは、設定してもしなくてもかまいません。すべてのパラメータにはデフォルト値があります。

**Zend_Http_Client の設定パラメータ**
パラメータ	説明	期待する値	デフォルト値
maxredirects	リダイレクトをたどる最大数 (0 = たどらない)	integer	5
strict	ヘッダ名の検証を行うかどうか。 `FALSE` に設定すると、検証関数をスキップします。通常はこれを変更してはいけません。	boolean	`TRUE`
strictredirects	リダイレクトの際に RFC に厳密に従うかどうか (このセクションを参照ください)	boolean	`FALSE`
useragent	ユーザエージェントを表す文字列 (リクエストヘッダに付加されます)	string	'Zend_Http_Client'
timeout	接続タイムアウト秒数	integer	10
httpversion	HTTP プロトコルのバージョン (通常は '1.1' あるいは '1.0')	string	'1.1'
adapter	使用する接続アダプタクラス (このセクションを参照ください)	mixed	'Zend_Http_Client_Adapter_Socket'
keepalive	サーバとの keep-alive 接続を有効にするかどうか。同一サーバに連続してリクエストが発生する場合などに便利で、性能を向上させるでしょう。	boolean	`FALSE`
storeresponse	直近のレスポンスを保存して後から getLastResponse() で取得できるようにするかどうか。 `FALSE` の場合、 getLastResponse() は `NULL` を返します。	boolean	`TRUE`
encodecookies	クッキー値を urlencode/urldecode を介して渡すべきかどうか。これを有効にすると、一部の Web サーバーでサポートを壊します。これを無効にすると、クッキーが含むことができる値の範囲を制限します。	boolean	`TRUE`

基本的な HTTP リクエストの処理

シンプルな HTTP リクエストを実行するのは非常に簡単で、単に request() メソッドを実行するだけです。たったの三行ですんでしまいます。

例2 シンプルな GET リクエストの処理

$client = new Zend_Http_Client('http://example.org');
$response = $client->request();

request() メソッドには、オプションでパラメータを指定できます。このパラメータはリクエストメソッドで、HTTP プロトコルで定義されている GET、POST、PUT、 HEAD、DELETE、TRACE、 OPTIONS そして CONNECT のいずれかを指定可能です。 ^[1] http://www.w3.org/Protocols/rfc2616/rfc2616.html 利便性を高めるため、これらはすべてクラス定数として定義されています。たとえば Zend_Http_Client::GET、Zend_Http_Client::POST などのようになっています。

メソッドを指定しない場合は、直近の setMethod() コールで指定されたメソッドを使用します。 setMethod() もコールされていない場合は、デフォルトのリクエストメソッドとして GET を使用します (上の例を参照ください)。

例3 GET 以外のリクエストメソッドの使用

// POST リクエストを実行します
$response = $client->request('POST');
 
// POST リクエストを実行するためのもうひとつの方法です
$client->setMethod(Zend_Http_Client::POST);
$response = $client->request();

GET や POST へのパラメータの追加

GET パラメータを HTTP リクエストに追加するのは簡単です。 URL の一部として指定するか、あるいは setParameterGet() メソッドを使用します。このメソッドは、GET パラメータの名前を最初の引数、そして GET パラメータの値を二番目の引数として受け取ります。さらに便利に使用するため、setParameterGet() メソッドでは name => value 形式の連想配列で GET 変数を指定することもできます。これは、複数の GET パラメータを指定する必要がある場合に便利です。

例4 GET パラメータの設定

// setParameterGet メソッドで GET パラメータを指定します
$client->setParameterGet('knight', 'lancelot');
 
// このような URL を指定するのと同じことです
$client->setUri('http://example.com/index.php?knight=lancelot');
 
// 複数のパラメータを一度に追加します
$client->setParameterGet(array(
    'first_name'  => 'Bender',
    'middle_name' => 'Bending'
    'made_in'     => 'Mexico',
));

GET パラメータはあらゆるリクエストメソッドで送信できますが、 POST パラメータは POST リクエストの本文としてしか送信できません。 POST パラメータをリクエストに追加する方法は、GET パラメータを追加する場合と非常に似ています。使用するのは setParameterPost() メソッドで、このメソッドの使用法は setParameterGet() メソッドと同じです。

例5 POST パラメータの設定

// POST パラメータを設定します
$client->setParameterPost('language', 'fr');
 
// 複数の POST パラメータを設定します。そのうちのひとつは複数の値を持ちます。
$client->setParameterPost(array(
    'language'  => 'es',
    'country'   => 'ar',
    'selection' => array(45, 32, 80)
));

POST リクエストを送信する際には、GET パラメータと POST パラメータの両方を設定できることに注意しましょう。一方、POST パラメータを POST 以外のリクエストで指定しても何のエラーも発生しませんが、これは無意味です。POST 以外のリクエストでは、 POST パラメータを指定しても無視されます。

直近のリクエストやレスポンスへのアクセス

Zend_Http_Client では、そのクライアントオブジェクトが直近に送信したリクエストおよび直近に受信したレスポンスにアクセスするためのメソッドを提供しています。 Zend_Http_Client->getLastRequest() は何もパラメータを受け取らず、クライアントが直近に送信した HTTP リクエストを文字列で返します。同様に Zend_Http_Client->getLastResponse() は、クライアントが直近に受信した HTTP レスポンスを Zend_Http_Response オブジェクトで返します。

^[1] RFC 2616 - を参照ください。

Zend_Http

Zend_Http
プログラマ向けリファレンスガイド

Zend_Http_Client - 高度な使用法

Comments

Posted by: Thomas on: 2010-06-18 20:01:08 ⁋

Small typo in the code example under Using Zend_Http_Client

12. // You can also use a Zend_Config object to set the client's configuration
13 .$config = new Zend_Config_Ini('httpclient.ini, 'secure');
14. $client->setConfig($config);

There should be a ' at after the first parameter on line 13

Posted by: Swaagie on: 2010-11-12 16:27:57 ⁋

$client->setParameterGet(array(
'first_name' => 'Bender',
'middle_name' => 'Bending'
'made_in' => 'Mexico',
));

There should be a comma after 'Bending', 'Mexico' could loose the comma.

Posted by: Michael on: 2011-06-27 19:05:43 ⁋

NOTE you're probably better off doing this:

$client->request('GET');
if ($client->getLastResponse()->isSuccessful()) {
$response = $client->getLastResponse()->getBody();
}

then this:
$response = $client->request('GET');

This is because the client may choose to use gz encoding but yet will not uncompress it directly (instead you must use the response object to uncompress it)

Posted by: Thomas Godar on: 2011-07-13 19:47:15 ⁋

I Noticed that the class Zend_Http_Client uses protected properties but does not prefix the variable names with underscores. This annoys me particularly since the code lacks public getters for proprieties like $options... but that is not immediately obvious since you would think $options is public. Good class to extend on.

Posted by: James on: 2011-10-13 16:10:39 ⁋

@ Michael - that is a fantastic tip!

Thank you so much, I would have been going round the bend trying to get it to work without that.

Cheers