unirest-php/README.md

Unirest for PHP

Unirest is a set of lightweight HTTP libraries available in multiple languages.

Features

• Utility methods to call GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE, PATCH requests
• Supports form parameters, file uploads and custom body entities
• Supports gzip
• Supports Basic Authentication natively
• Customizable timeout
• Customizable default headers for every request (DRY)
• Automatic JSON parsing into a native object for JSON responses

Requirements

• cURL

Installation

Using Composer

To install unirest-php with Composer, just add the following to your composer.json file:

{
    "require-dev": {
        "mashape/unirest-php": "2.*"
    }
}

or by running the following command:

composer require mashape/unirest-php

This will get you the latest version of the reporter and install it. If you do want the master, untagged, version you may use the command below:

composer require mashape/php-test-reporter:@dev-master

Composer installs autoloader at ./vendor/autoloader.php. to include the library in your script, add:

require_once 'vendor/autoload.php';

If you use Symfony2, autoloader has to be detected automatically.

You can see this library on Packagist.

Install from source

Unirest-PHP requires PHP v5.4+. Download the PHP library from Github, then include Unirest.php in your script:

git clone git@github.com:Mashape/unirest-php.git 

require_once '/path/to/unirest-php/src/Unirest.php';

Usage

Creating a Request

So you're probably wondering how using Unirest makes creating requests in PHP easier, let's look at a working example:

$headers = array("Accept" => "application/json");
$body = array("foo" => "hellow", "bar" => "world");

$response = Unirest\Request::post("http://httpbin.org/post", $headers, $body);

$response->code;        // HTTP Status code
$response->headers;     // Headers
$response->body;        // Parsed body
$response->raw_body;    // Unparsed body

File Uploads

To upload files in a multipart form representation use the return value of Unirest\File::add($path) as the value of a parameter:

$headers = array("Accept" => "application/json");
$body = array("file" => Unirest\File::add("/tmp/file.txt"));

$response = Unirest\Request::post("http://httpbin.org/post", $headers, $body);

Custom Entity Body

Sending a custom body such as a JSON Object rather than a string or form style parameters we utilize json_encode for the body:

$headers = array("Accept" => "application/json");
$body =   json_encode(array("foo" => "hellow", "bar" => "world"));

$response = Unirest\Request::post("http://httpbin.org/post", $headers, $body);

Basic Authentication

Authenticating the request with basic authentication can be done by providing the username and password arguments:

$response = Unirest\Request::get("http://httpbin.org/get", null, null, "username", "password");

Request Object

Unirest\Request::get($url, $headers = array(), $parameters = null, $username = null, $password = null)
Unirest\Request::post($url, $headers = array(), $body = null, $username = null, $password = null)
Unirest\Request::put($url, $headers = array(), $body = null, $username = null, $password = null)
Unirest\Request::patch($url, $headers = array(), $body = null, $username = null, $password = null)
Unirest\Request::delete($url, $headers = array(), $body = null, $username = null, $password = null)

• url - Endpoint, address, or uri to be acted upon and requested information from.
• headers - Request Headers as associative array or object
• body - Request Body as associative array or object
• username - Basic Authentication username
• password - Basic Authentication password

You can send a request with any standard or custom HTTP Method:

Unirest\Request::send(Unirest\Method::LINK, $url, $headers = array(), $body);

Unirest\Request::send('CHECKOUT', $url, $headers = array(), $body);

Response Object

Upon recieving a response Unirest returns the result in the form of an Object, this object should always have the same keys for each language regarding to the response details.

• code - HTTP Response Status Code (Example 200)
• headers - HTTP Response Headers
• body - Parsed response body where applicable, for example JSON responses are parsed to Objects / Associative Arrays.
• raw_body - Un-parsed response body

Advanced Configuration

You can set some advanced configuration to tune Unirest-PHP:

Custom JSON Decode Flags

Unirest uses PHP's JSON Extension for automatically decoding JSON responses. sometime you may want to return associative arrays, limit the depth of recursion, or use any of the customization flags.

To do so, simply set the desired options using the jsonOpts request method:

Unirest\Request::jsonOpts(true, 512, JSON_NUMERIC_CHECK & JSON_FORCE_OBJECT & JSON_UNESCAPED_SLASHES);

Timeout

You can set a custom timeout value (in seconds):

Unirest\Request::timeout(5); // 5s timeout

Proxy

Set the proxy to use for the upcoming request.

you can also set the proxy type to be one of CURLPROXY_HTTP, CURLPROXY_HTTP_1_0, CURLPROXY_SOCKS4, CURLPROXY_SOCKS5, CURLPROXY_SOCKS4A, and CURLPROXY_SOCKS5_HOSTNAME.

check the cURL docs for more info.

// quick setup with default port: 1080
Unirest\Request::proxy('10.10.10.1');

// custom port and proxy type
Unirest\Request::proxy('10.10.10.1', 8080, CURLPROXY_HTTP)l

// enable tunneling
Unirest\Request::proxy('10.10.10.1', 8080, CURLPROXY_HTTP, true);

Default Request Headers

You can set default headers that will be sent on every request:

Unirest\Request::defaultHeader("Header1", "Value1");
Unirest\Request::defaultHeader("Header2", "Value2");

You can do set default headers in bulk:

Unirest\Request::defaultHeaders(array(
    "Header1" => "Value1",
    "Header2" => "Value2"
));

You can clear the default headers anytime with:

Unirest\Request::clearDefaultHeaders();

SSL validation

You can explicitly enable or disable SSL certificate validation when consuming an SSL protected endpoint:

Unirest\Request::verifyPeer(false); // Disables SSL cert validation

By default is true.

---

Made with ♥ from the Mashape team