Request_Curl クラス

Request_Curl クラスは、主に PHP の cURL 拡張モジュールを介して REST リクエストを処理することを意図していますが、 HTTP リクエストを介して任意のコンテンツを取得するために使用することができます。

インスタンスの生成

Request クラスを介して、このクラスのインスタンスを生成できます: 

// Request_Curl オブジェクトを作成
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');

// これはオブジェクトを作成するだけであって、リクエストを実行するわけではないことに注意！

set_method($method)

set_method メソッドは、HTTP リクエストメソッドをセットできます。

静的 いいえ
パラメータ
パラメータ デフォルト 説明
$method 必須 リクエストに使われる HTTP メソッド (GET 、HEAD 、POST 、PUT 、DELETE) 。
返り値 Request_Curl 、メソッドチェーン用
例 
// Request_Curl オブジェクトを作成
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');

// これは HTTP POST になる
$curl->set_method('post');

get_method()

get_method メソッドは、現在の HTTP リクエストメソッドのセットを取得することができます。

静的 いいえ
パラメータ なし。
返り値 mixed 。定義されている HTTP メソッド (大文字) 、セットされていない場合は null 。
例 
// Request_Curl オブジェクトを作成
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');

// これは HTTP POST になる
$curl->set_method('post');

// 'POST' を返す
$method = $curl->get_method();

set_params($params)

set_params メソッドは、HTTP リクエストに渡すパラメータを設定することができます。

静的 いいえ
パラメータ
パラメータ デフォルト 説明
$params 必須 リクエストに使用するパラメータの配列。
返り値 Request_Curl 、メソッドチェーン用
例 
// Request_Curl オブジェクトを作成
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');

// いくつかのパラメータをセット
$curl->set_params(array('userid' => 12, 'data' => $payload));

// multipart/form-data
$params = array('userid' => 12, 'data' => $payload));
$curl->set_params(array('form-data' => $params));
パラメータの配列は次のいずれかの値に Content-Type ヘッダを設定すると自動的にそれぞれの形式に変換します：
  • application/xml
  • application/soap+xml
  • text/xml
  • application/json
  • text/json
  • text/csv
  • application/csv
  • application/vnd.php.serialized

これらのパラメータが使用されている方法は生成された要求に依存します。 GET リクエストの場合、 これらはクエリ文字列に変換されます。 POST リクエストの場合、それらは POST ボディとなります。

リクエストボディの送信で Content-Type ヘッダを設定しない場合、ボディは application/x-www-form-urlencoded タイプになります。 multipart/form-data としてリクエストを送信する場合は、 上記の例を参照してください。

set_option($option, $value)

set_option メソッドは、リクエストに渡される CURL オプションを定義することができます。

静的 いいえ
パラメータ
パラメータ デフォルト 説明
$option 必須 セットする cURL オプション。通常は、1 つの cURL 定数。
$value 必須 オプションにセットする値。
返り値 Request_Curl 、メソッドチェーン用
例 
// Request_Curl オブジェクトを作成
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');

// リクエストで使うためのユーザ名とパスワードをセット
$curl->set_option(CURLOPT_USERPWD, $username . ':' . $password);

set_options(array $options)

set_options メソッドは、リクエストに渡される複数の CURL オプションを定義することができます。

静的 いいえ
パラメータ
パラメータ デフォルト 説明
$options 必須 cURL オプションとセットしたい値の配列。
返り値 Request_Curl 、メソッドチェーン用
例 
// Request_Curl オブジェクトを作成
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');

// リクエストで使用するいくつかのオプションをセット
$curl->set_options(array(
	CURLOPT_TIMEOUT => 30,
	CURLOPT_FOLLOWLOCATION => true,
	)
);

add_param($param, $value = null)

add_param メソッドは、すでに定義されたものに 1 つ以上のパラメータを追加することができます。

静的 いいえ
パラメータ
パラメータ デフォルト 説明
$param 必須 セットしたいパラメータの名前、またはパラメータと値の配列。
$value 
null
 定義したい値。$param が文字列値の場合のみ使われる。
返り値 Request_Curl 、メソッドチェーン用
例 
// Request_Curl オブジェクトを作成
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');

// いくつかパラメータを追加
$curl->add_param(array('userid' => 12, 'data' => $payload));

// または、1 つを追加
$curl->add_param('data', $payload);

set_header($header, $content = null)

set_header メソッドは、リクエストの一部として HTTP リクエストヘッダをセットすることができます。

静的 いいえ
パラメータ
パラメータ デフォルト 説明
$header 必須 HTTP ヘッダエントリの名前。
$content 
null
 セットしたいヘッダの値。
返り値 Request_Curl 、メソッドチェーン用
例 
// Request_Curl オブジェクトを作成
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');

// バックエンドサーバに認証トークンを渡す
$curl->set_header('auth-token', 'WV4YaeV8QeWVVVOE');

"名前: 値" の形式でないヘッダをセットする必要がある場合、値は $header の中で渡し、$content には何も渡さないこと。

get_headers()

get_headers メソッドは、現在定義されているすべての HTTP リクエストヘッダを取得することができます。

静的 いいえ
パラメータ なし。
返り値 Array 、全てのヘッダセット。
例 
// Request_Curl オブジェクトを作成
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');

// バックエンドサーバに認証トークンを渡す
$curl->set_header('auth-token', 'WV4YaeV8QeWVVVOE');

// array('auth-token:WV4YaeV8QeWVVVOE') を返す
$headers = $curl->get_headers();

set_mime_type($mime)

set_mime_type メソッドは、HTTP ACCEPT ヘッダを定義することができます。

静的 いいえ
パラメータ
パラメータ デフォルト 説明
$mime 必須 リクエストしたレスポンスの mime タイプ。これは、ACCEPT ヘッダをセットするために使われます。 
// 現在サポートされているタイプ:
'xml' => 'application/xml',
'json' => 'application/json',
'serialize' => 'application/vnd.php.serialized',
'php' => 'text/plain',
'csv' => 'text/csv',
返り値 Request_Curl 、メソッドチェーン用
例 
// Request_Curl オブジェクトを作成
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');

// json で返して欲しいとバックエンドに伝える
$curl->set_mime_type('json');

これはリクエストだけです。呼んでいるサービスが実際にサポートされていて、 HTTP ACCEPT ヘッダの中の mime タイプが利用できるか確認すべきです。 サポートされているならばリクエストできます。

set_auto_format($auto_format)

set_auto_format メソッドは、自動整形をオンまたはオフにすることができます。 1.7.2 以降、これはデフォルトでオフになっており、オフ時には cURL のレスポンスを自分で解析する必要があります。

静的 いいえ
パラメータ
パラメータ デフォルト 説明
$auto_format 必須 返ってきたレスポンスを配列に変換したいならば true 、受け取ったそのままにアクセスしたいならば false 。
返り値 Request_Curl 、メソッドチェーン用
例 
// Request_Curl オブジェクトを作成
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');

// 配列で返り値が欲しい
$curl->set_auto_format(true);

自動整形は次の MIME タイプをサポートしています：

  • application/xml
  • text/xml
  • application/json
  • text/json
  • text/csv
  • application/csv
  • application/vnd.php.serialized
有効になっており応答がこれらのタイプのいずれかにあるとき、それが自動的に処理され、 PHP の配列形式でコントローラに返されます。

これはデータのソースが信頼できるか、そして / または、受信した入力を検証している場合にのみ有効にします。 JSON とシリアル化された配列はオブジェクトを含めることができます。それらのコンストラクタは自動整形中のインスタンス化時に実行されるので、 おそらくサーバを損なう、意図しないコードが実行される可能性があります！

execute(array $additional_params = array())

execute メソッドは、定義された cURL リクエストを実行します。

静的 いいえ
パラメータ
パラメータ デフォルト 説明
$additional_params 
array()
 リクエストに渡したい追加のパラメータ。
返り値 Request_Curl 、メソッドチェーン用
例 
// Request_Curl オブジェクトを作成
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');

// リクエストを実行
$result = $curl->execute();

set_response($body, $status, $mime = null, $headers = array())

set_response メソッドは、リクエストから受け取ったレスポンスをセットします。

静的 いいえ
パラメータ
パラメータ デフォルト 説明
$body 必須 レスポンスボディとしてセットされるデータ。
$status 必須 レスポンスを作成した HTTP ステータス。
$mime 
null
 データの mime タイプ。これは auto_format でボディを配列へ変換するために使われます。
$headers 
null
 セットしたい HTTP レスポンスヘッダ。
返り値 Response 、作成された response オブジェクト。
例 
// Request_Curl オブジェクトを作成
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');

// カスタムレスポンスを作成
$curl->set_response($body, $this->response_info('http_code', 200), 'json', array('auth-token' => 'WV4YaeV8QeWVVVOE'));

通常は、このメソッドを使用すべきではありません。リクエストがリクエストのレスポンスオブジェクトを準備するために実行された後、このメソッドが使用されます。

response()

response メソッドは、現在のリクエストレスポンスを返します。

静的 いいえ
パラメータ なし。
返り値 Response 、作成された response オブジェクト。
例 
// Request_Curl オブジェクトを作成
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');

// いくつかのパラメータとオプションがセットされているとして、実行する
$curl->execute();

// 結果の Response オブジェクトを取得
$result = $curl->response();

response_info($key = null, $default = null)

response_info メソッドは、cURL レスポンスの値、または全てのレスポンスの値を取得することができます。

静的 いいえ
パラメータ
パラメータ デフォルト 説明
$key 
null
 取得したいレスポンスの値を指定します。全ての値を取得したい場合は指定しないでください。
$default 
null
 リクエストした値が存在しない場合に返される値。
返り値 Mixed 、リクエストした値のデータタイプによる。
例 
// Request_Curl オブジェクトを作成
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');

// いくつかのパラメータとオプションがセットされているとして、実行する
$curl->execute();

// リクエストでダウンロードしたバイト数を取得
$size = $curl->response_info(CURLINFO_SIZE_DOWNLOAD, false);

http_login($username = '', $password = '', $type = 'any')

http_login メソッドは、リクエストを実行する際に basic 認証を使用することができます。

静的 いいえ
パラメータ
パラメータ デフォルト 説明
$username 
''
 認証を行うユーザの名前。
$password 
''
 ユーザのパスワード。
$type 
'any'
 認証方法のタイプ。サポートしているのは: BASIC 、DIGEST 、GSSNEGOTIATE 、NTLM 、ANY と ANYSAFE 。
返り値 Response 、作成した response オブジェクト。
例 
// Request_Curl オブジェクトを作成
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');

// IIS サーバの認証を試みる
$curl->http_login('username', 'mypass', 'NTLM');