Usage

Ready to go? Make sure you have Requests installed before attempting any of the steps in this guide.

Loading Requests

Before we can load Requests up, we'll need to make sure it's loaded. This is a simple two-step:

// First, include Requests
include('/path/to/library/Requests.php');

// Next, make sure Requests can load internal classes
Requests::register_autoloader();

If you'd like to bring along your own autoloader, you can forget about this completely.

Make a GET Request

One of the most basic things you can do with HTTP is make a GET request.

Let's grab GitHub's public timeline:

$response = Requests::get('https://github.com/timeline.json');

$response is now a Requests_Response object. Response objects are what you'll be working with whenever you want to get data back from your request.

Using the Response Object

Now that we have the response from GitHub, let's get the body of the response.

var_dump($response->body);
// string(42865) "[{"repository":{"url":"...

Custom Headers

If you want to add custom headers to the request, simply pass them in as an associative array as the second parameter:

$response = Requests::get('https://github.com/timeline.json', array('X-Requests' => 'Is Awesome!'));

Make a POST Request

Making a POST request is very similar to making a GET:

$response = Requests::post('http://httpbin.org/post');

You'll probably also want to pass in some data. You can pass in either a string, an array or an object (Requests uses [http_build_query][build_query] internally) as the third parameter (after the URL and headers):

[build_query]: http://php.net/http_build_query

$data = array('key1' => 'value1', 'key2' => 'value2');
$response = Requests::post('http://httpbin.org/post', array(), $data);
var_dump($response->body);

This gives the output:

string(503) "{
  "origin": "124.191.162.147", 
  "files": {}, 
  "form": {
    "key2": "value2", 
    "key1": "value1"
  }, 
  "headers": {
    "Content-Length": "23", 
    "Accept-Encoding": "deflate;q=1.0, compress;q=0.5, gzip;q=0.5", 
    "X-Forwarded-Port": "80", 
    "Connection": "keep-alive", 
    "User-Agent": "php-requests/1.6-dev", 
    "Host": "httpbin.org", 
    "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8"
  }, 
  "url": "http://httpbin.org/post", 
  "args": {}, 
  "data": ""
}"

To send raw data, simply pass in a string instead. You'll probably also want to set the Content-Type header to ensure the remote server knows what you're sending it:

$url = 'https://api.github.com/some/endpoint';
$headers = array('Content-Type' => 'application/json');
$data = array('some' => 'data');
$response = Requests::post($url, $headers, json_encode($data));

Note that if you don't manually specify a Content-Type header, Requests has undefined behaviour for the header. It may be set to various values depending on the internal execution path, so it's recommended to set this explicitly if you need to.

Status Codes

The Response object also gives you access to the status code:

var_dump($response->status_code);
// int(200)

You can also easily check if this status code is a success code, or if it's an error:

var_dump($response->success);
// bool(true)

Response Headers

We can also grab headers pretty easily:

var_dump($response->headers['Date']);
// string(29) "Thu, 09 Feb 2012 15:22:06 GMT"

Note that this is case-insensitive, so the following are all equivalent:

• `$response->headers['Date']`
• `$response->headers['date']`
• `$response->headers['DATE']`
• `$response->headers['dAtE']`

If a header isn't set, this will give null. You can also check with isset($response->headers['date'])