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

set_header($header, $content = null)

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.

get_headers()

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.

set_auto_format($auto_format)

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