unirest-php

Unirest for PHP [![Build Status][travis-image]][travis-url] [![version][packagist-version]][packagist-url]

[![Downloads][packagist-downloads]][packagist-url] [![Code Climate][codeclimate-quality]][codeclimate-url] [![Coverage Status][codeclimate-coverage]][codeclimate-url] [![Dependencies][versioneye-image]][versioneye-url] [![Gitter][gitter-image]][gitter-url] [![License][packagist-license]][license-url] ![][unirest-logo]

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, Digest, Negotiate, NTLM Authentication natively
• Customizable timeout
• Customizable default headers for every request (DRY)
• Automatic JSON parsing into a native object for JSON responses

Requirements

• cURL
• PHP 5.4+

Installation

Using Composer

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

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

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

Download the PHP library from Github, then include Unirest.php in your script:

git clone [email protected]: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');
$query = array('foo' => 'hello', 'bar' => 'world');

$response = Unirest\Request::post('http://mockbin.com/request', $headers, $query);

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

JSON Requests (application/json)

A JSON Request can be constructed using the Unirest\Request\Body::Json helper:

$headers = array('Accept' => 'application/json');
$data = array('name' => 'ahmad', 'company' => 'mashape');

$body = Unirest\Request\Body::json($data);

$response = Unirest\Request::post('http://mockbin.com/request', $headers, $body);

Notes:

• Content-Type headers will be automatically set to application/json
• the data variable will be processed through json_encode with default values for arguments.
• an error will be thrown if the JSON Extension is not available.

Form Requests (application/x-www-form-urlencoded)

A typical Form Request can be constructed using the Unirest\Request\Body::Form helper:

$headers = array('Accept' => 'application/json');
$data = array('name' => 'ahmad', 'company' => 'mashape');

$body = Unirest\Request\Body::form($data);

$response = Unirest\Request::post('http://mockbin.com/request', $headers, $body);

Notes:

• Content-Type headers will be automatically set to application/x-www-form-urlencoded
• the final data array will be processed through http_build_query with default values for arguments.

Multipart Requests (multipart/form-data)

A Multipart Request can be constructed using the Unirest\Request\Body::Multipart helper:

$headers = array('Accept' => 'application/json');
$data = array('name' => 'ahmad', 'company' => 'mashape');

$body = Unirest\Request\Body::multipart($data);

$response = Unirest\Request::post('http://mockbin.com/request', $headers, $body);

Notes:

• Content-Type headers will be automatically set to multipart/form-data.
• an auto-generated --boundary will be set.

Multipart File Upload

simply add an array of files as the second argument to to the Multipart helper:

$headers = array('Accept' => 'application/json');
$data = array('name' => 'ahmad', 'company' => 'mashape');
$files = array('bio' => '/path/to/bio.txt', 'avatar' => '/path/to/avatar.jpg');

$body = Unirest\Request\Body::multipart($data, $files);

$response = Unirest\Request::post('http://mockbin.com/request', $headers, $body);

If you wish to further customize the properties of files uploaded you can do so with the Unirest\Request\Body::File helper:

$headers = array('Accept' => 'application/json');
$body = array(
    'name' => 'ahmad', 
    'company' => 'mashape'
    'bio' => Unirest\Request\Body::file('/path/to/bio.txt', 'text/plain'),
    'avatar' => Unirest\Request\Body::file('/path/to/my_avatar.jpg', 'text/plain', 'avatar.jpg')
);

$response = Unirest\Request::post('http://mockbin.com/request', $headers, $body);

Note: we did not use the Unirest\Request\Body::multipart helper in this example, it is not needed when manually adding files.

Custom Body

Sending a custom body such rather than using the Unirest\Request\Body helpers is also possible, for example, using a serialize body string with a custom Content-Type:

$headers = array('Accept' => 'application/json', 'Content-Type' => 'application/x-php-serialized');
$body = serialize((array('foo' => 'hello', 'bar' => 'world'));

$response = Unirest\Request::post('http://mockbin.com/request', $headers, $body);

Authentication

First, if you are using [Mashape][mashape-url]:

// Mashape auth
Unirest\Request::setMashapeKey('');

Otherwise, passing a username, password (optional), defaults to Basic Authentication:

// basic auth
Unirest\Request::auth('username', 'password');

The third parameter, which is a bitmask, will Unirest which HTTP authentication method(s) you want it to use for your proxy authentication.

If more than one bit is set, Unirest (at PHP's libcurl level) will first query the site to see what authentication methods it supports and then pick the best one you allow it to use. For some methods, this will induce an extra network round-trip.

Supported Methods

// custom auth method
Unirest\Request::proxyAuth('username', 'password', CURLAUTH_DIGEST);

Previous versions of Unirest support Basic Authentication by providing the username and password arguments:

$response = Unirest\Request::get('http://mockbin.com/request', null, null, 'username', 'password');

This has been deprecated, and will be completely removed in v.3.0.0 please use the Unirest\Request::auth() method instead

Cookies

Set a cookie string to specify the contents of a cookie header. Multiple cookies are separated with a semicolon followed by a space (e.g., "fruit=apple; colour=red")

Unirest\Request::cookie($cookie)

Set a cookie file path for enabling cookie reading and storing cookies across multiple sequence of requests.

Unirest\Request::cookieFile($cookieFile)

$cookieFile must be a correct path with write permission.

Request Object

Unirest\Request::get($url, $headers = array(), $parameters = null)
Unirest\Request::post($url, $headers = array(), $body = null)
Unirest\Request::put($url, $headers = array(), $body = null)
Unirest\Request::patch($url, $headers = array(), $body = null)
Unirest\Request::delete($url, $headers = array(), $body = 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

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 fl