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:
// create a Request_Curl object
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
// note that this only creates the object, it does not execute the request!
set_method($method)
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 |
// create a Request_Curl object
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
// this is going to be an HTTP POST
$curl->set_method('post');
|
get_method()
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 |
// create a Request_Curl object
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
// this is going to be an HTTP POST
$curl->set_method('post');
// returns 'POST'
$method = $curl->get_method();
|
set_params($params)
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 |
// create a Request_Curl object
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
// set some parameters
$curl->set_params(array('userid' => 12, 'data' => $payload));
// multipart/form-data
$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.
set_option($option, $value)
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 |
// create a Request_Curl object
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
// set a username and password to be used in the request
$curl->set_option(CURLOPT_USERPWD, $username . ':' . $password);
|
set_options(array $options)
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 |
// create a Request_Curl object
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
// set some options to be used in the request
$curl->set_options(array(
CURLOPT_TIMEOUT => 30,
CURLOPT_FOLLOWLOCATION => true,
)
);
|
add_param($param, $value = null)
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 |
// create a Request_Curl object
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
// add some parameters
$curl->add_param(array('userid' => 12, 'data' => $payload));
// or add a single one
$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 |
// create a Request_Curl object
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
// pass an authentication token to the backend server
$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 |
// create a Request_Curl object
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
// pass an authentication token to the backend server
$curl->set_header('auth-token', 'WV4YaeV8QeWVVVOE');
// returns array('auth-token:WV4YaeV8QeWVVVOE')
$headers = $curl->get_headers();
|
set_mime_type($mime)
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.
// currently supported types are:
'xml' => 'application/xml',
'json' => 'application/json',
'serialize' => 'application/vnd.php.serialized',
'php' => 'text/plain',
'csv' => 'text/csv',
|
|
| Returns |
Request_Curl, for chaining |
| Example |
// create a Request_Curl object
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
// tell the backend we want json returned
$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 |
// create a Request_Curl object
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
// we want an array returned
$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())
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 |
// create a Request_Curl object
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
// execute the request
$result = $curl->execute();
|
set_response($body, $status, $mime = null, $headers = array())
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 |
// create a Request_Curl object
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
// create a custom response
$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.
response()
The response method returns the current request response.
| Static |
No |
| Parameters |
None.
|
| Returns |
Response, the created response object. |
| Example |
// create a Request_Curl object
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
// assume some parameters and options were set, and execute
$curl->execute();
// fetch the resulting Response object
$result = $curl->response();
|
response_info($key = null, $default = null)
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 |
// create a Request_Curl object
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
// assume some parameters and options were set, and execute
$curl->execute();
// get the number of bytes downloaded in the request
$size = $curl->response_info(CURLINFO_SIZE_DOWNLOAD, false);
|
http_login($username = '', $password = '', $type = 'any')
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 |
// create a Request_Curl object
$curl = Request::forge('http://rest.example.org/api/v1/this/info', 'curl');
// authenticate against an IIS server
$curl->http_login('username', 'mypass', 'NTLM');
|
