Request_Curl - 类別 - FuelPHP 简体中文手册

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 請求方法。

靜態	否
參数	無。
回傳	混合，定義大寫的 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));

这些參数使用的方式取決於產生的請求。對於 GET 請求，这些将被轉換为一个查詢字串。對於 POST 請求，他們将成为 POST 主體。

set_option($option, $value)

set_option 方法能让你定義一个 CURL 選項以被傳遞到該請求。

靜態否

參数

參数	預設	描述
`$option`	必要	要設定的 cURL 選項。通常这是一个 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 方法能让你添加一个或更多參数到已定義的。

靜態否

參数

參数	預設	描述
`$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));

// 或添加单一參数
$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');

如果你需要設定一个非 "Name: Value" 形式的表頭，在 $header 傳遞值，并且不要傳遞任何內容。

get_headers()

get_headers 方法能让你取回所有目前已定義的 HTTP 請求表頭。

靜態	否
參数	無。
回傳	陣列，所有設定的表頭。
範例	`// 建立一个 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 方法能让你切換自动格式化開關。 Since 1.7.2, this is switched of by default, and when switched off, you will have to parse the cURL response yourself.

靜態否

參数

參数	預設	描述
`$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);

Auto formatting has support for the following mime types:

application/xml
text/xml
application/json
text/json
text/csv
application/csv
application/vnd.php.serialized

so when enabled and the response is in one of these types, it will be processed automatically, and returned to your controller in the form of a PHP array.

Only enable this is the source of the data is trustworthy, and/or if you have validated the received input. JSON and serialized arrays could contain objects. Since their constructor will execute upon instantiation during auto formatting, it may lead to unintended code execution, possibly compromizing your server!

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，建立的回應物件。

範例

// 建立一个 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，建立的回應物件。
範例	`// 建立一个 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`	當該請求值不存在時要被回傳的值。

回傳混合，取決於請求值的資料类型。

範例

// 建立一个 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 方法能让你在执行請求時使用基本的認證。

靜態否

參数

參数	預設	描述
`$username`	`''`	你想用來执行認證的使用者名稱。
`$password`	`''`	使用者密码。
`$type`	`'any'`	要执行的認證类型。支援的有：BASIC、DIGEST、GSSNEGOTIATE、NTLM、ANY 和 ANYSAFE。

回傳 Response，建立的回應物件。

範例

// 建立一个 Request_Curl 物件
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');

// 對一个 IIS 伺服器認證
$curl->http_login('username', 'mypass', 'NTLM');