Request_Curl Class
The Request_Curl class is mainly intended to process REST requests through PHP's cURL extension, but can be used to fetch
any content through an HTTP request.
Creating an instance
You can forge an instance of this class through the Request class:
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
The set_method method allows you to set the HTTP request method.
Static |
No |
Parameters |
Param |
Default |
Description |
$method |
required |
The HTTP method (GET, HEAD, POST, PUT, DELETE) to use for this request. |
|
Returns |
Request_Curl, for chaining |
Example |
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
$curl->set_method('post');
|
The get_method method allows you to get the current HTTP request method set.
Static |
No |
Parameters |
None.
|
Returns |
mixed, defined HTTP method in uppercase, or null if none set. |
Example |
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
$curl->set_method('post');
$method = $curl->get_method();
|
The set_params method allows you to set parameters to pass on the HTTP request.
Static |
No |
Parameters |
Param |
Default |
Description |
$params |
required |
Array of parameters for the request. |
|
Returns |
Request_Curl, for chaining |
Example |
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
$curl->set_params(array('userid' => 12, 'data' => $payload));
$params = array('userid' => 12, 'data' => $payload));
$curl->set_params(array('form-data' => $params));
|
Your param array will automatically convert to the respective format when you set the Content-Type header to one of the
followng values:
- application/xml
- application/soap+xml
- text/xml
- application/json
- text/json
- text/csv
- application/csv
- application/vnd.php.serialized
The way these parameters are used depends on the request generated. For GET requests, these will be converted
to a query string. For POST requests, they will become the POST body.
If you do not set the Content-Type header while sending a request body, your body will be of the type
application/x-www-form-urlencoded. If you prefer to send your request as multipart/form-data, see the
above example.
The set_option method allows you to define a CURL option to be passed to the request.
Static |
No |
Parameters |
Param |
Default |
Description |
$option |
required |
cURL option to set. Usually, this is one of the cURL constants. |
$value |
required |
Value to set this option to. |
|
Returns |
Request_Curl, for chaining |
Example |
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
$curl->set_option(CURLOPT_USERPWD, $username . ':' . $password);
|
The set_options method allows you to define multiple CURL options to be passed to the request.
Static |
No |
Parameters |
Param |
Default |
Description |
$options |
required |
Array of cURL options and values to set. |
|
Returns |
Request_Curl, for chaining |
Example |
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
$curl->set_options(array(
CURLOPT_TIMEOUT => 30,
CURLOPT_FOLLOWLOCATION => true,
)
);
|
The add_param method allows you to add one or more parameters to the ones already defined.
Static |
No |
Parameters |
Param |
Default |
Description |
$param |
required |
Name of the parameter to set, or an array of parameters and values. |
$value |
null
|
Value to be defined. Only used when $param is a string value. |
|
Returns |
Request_Curl, for chaining |
Example |
$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);
|
The set_header method allows you to set a HTTP request header as part of the request.
Static |
No |
Parameters |
Param |
Default |
Description |
$header |
required |
The name of the HTTP header entry. |
$content |
null
|
The header value to be set. |
|
Returns |
Request_Curl, for chaining |
Example |
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
$curl->set_header('auth-token', 'WV4YaeV8QeWVVVOE');
|
If you need to set a header that is not in the form "Name: Value", pass the value in $header, and do not pass any content.
The get_headers method allows you to retrieve all currently defined HTTP request headers.
Static |
No |
Parameters |
None.
|
Returns |
Array, all headers set. |
Example |
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
$curl->set_header('auth-token', 'WV4YaeV8QeWVVVOE');
$headers = $curl->get_headers();
|
The set_mime_type method allows you to define the HTTP ACCEPT header.
Static |
No |
Parameters |
Param |
Default |
Description |
$mime |
required |
The mime type of the requested response. This will be used to set the ACCEPT header.
'xml' => 'application/xml',
'json' => 'application/json',
'serialize' => 'application/vnd.php.serialized',
'php' => 'text/plain',
'csv' => 'text/csv',
|
|
Returns |
Request_Curl, for chaining |
Example |
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
$curl->set_mime_type('json');
|
This is only a request. You should verify if the service you're calling actually supports
and uses the mime type in the HTTP ACCEPT header, and if it supports the type you're requesting.
The set_auto_format method allows you to switch auto formatting on or off. Since 1.7.2, this is switched of by default, and when switched off, you will have to parse the cURL response yourself.
Static |
No |
Parameters |
Param |
Default |
Description |
$auto_format |
required |
True if you want the returned response to be converted into an array, false if you want to access it as it is received. |
|
Returns |
Request_Curl, for chaining |
Example |
$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!
The execute method executes the defined cURL request.
Static |
No |
Parameters |
Param |
Default |
Description |
$additional_params |
array()
|
Any additional parameters you want to pass to the request. |
|
Returns |
Request_Curl, for chaining |
Example |
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
$result = $curl->execute();
|
The set_response method sets the response received from the request.
Static |
No |
Parameters |
Param |
Default |
Description |
$body |
required |
The data to be set as the response body. |
$status |
required |
The HTTP status of the created response. |
$mime |
null
|
The mime type the data is in. This is used with auto_format to convert the body into an array. |
$headers |
null
|
Any HTTP response headers you want to set. |
|
Returns |
Response, the created response object. |
Example |
$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'));
|
Normally you should not use this method. It is used after the request is executed to prepare the requests response object.
The response method returns the current request response.
Static |
No |
Parameters |
None.
|
Returns |
Response, the created response object. |
Example |
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
$curl->execute();
$result = $curl->response();
|
The response_info method allows you to retrieve a cURL response value, or all response values.
Static |
No |
Parameters |
Param |
Default |
Description |
$key |
null
|
Specific response value to retrieve. Don't specify it when you want to retrieve all values. |
$default |
null
|
Value to be returned when the requested value does not exist. |
|
Returns |
Mixed, depending on the data type of the requested value. |
Example |
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
$curl->execute();
$size = $curl->response_info(CURLINFO_SIZE_DOWNLOAD, false);
|
The http_login method allows you to use basic authentication when executing the request.
Static |
No |
Parameters |
Param |
Default |
Description |
$username |
''
|
Name of the user you want to use to perform the authentication. |
$password |
''
|
That users password. |
$type |
'any'
|
Type of authentication to perform. Supported are: BASIC, DIGEST, GSSNEGOTIATE, NTLM, ANY and ANYSAFE. |
|
Returns |
Response, the created response object. |
Example |
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
$curl->http_login('username', 'mypass', 'NTLM');
|