Request_Curl - 类別

优质

小牛编辑

136浏览

2023-12-01

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');