Repository files navigation

Unirest is a set of lightweight HTTP libraries available in multiple languages, built and maintained byMashape, who also maintain the open-source API GatewayKong.

• Utility methods to callGET,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

• cURL
• PHP 5.4+

To install unirest-php with Composer, just add the following to yourcomposer.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 onPackagist.

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

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

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

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

A JSON Request can be constructed using theUnirest\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 toapplication/json
• the data variable will be processed throughjson_encode with default values for arguments.
• an error will be thrown if theJSON Extension is not available.

A typical Form Request can be constructed using theUnirest\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 toapplication/x-www-form-urlencoded
• the final data array will be processed throughhttp_build_query with default values for arguments.

A Multipart Request can be constructed using theUnirest\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 tomultipart/form-data.
• an auto-generated--boundary will be set.

simply add an array of files as the second argument to to theMultipart 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 theUnirest\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 theUnirest\Request\Body::multipart helper in this example, it is not needed when manually adding files.

Sending a custom body such rather than using theUnirest\Request\Body helpers is also possible, for example, using aserialize body string with a customContent-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);

First, if you are usingMashape:

// Mashape authUnirest\Request::setMashapeKey('<mashape_key>');

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

// basic authUnirest\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 methodUnirest\Request::proxyAuth('username','password',CURLAUTH_DIGEST);

Previous versions ofUnirest supportBasic Authentication by providing theusername andpassword arguments:

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

This has been deprecated, and will be completely removed inv.3.0.0 please use theUnirest\Request::auth() method instead

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.

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 anystandard or custom HTTP Method:

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

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 (Example200)
• 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

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

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

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

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

You can set a custom timeout value (inseconds):

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

Set the proxy to use for the upcoming request.

you can also set the proxy type to be one ofCURLPROXY_HTTP,CURLPROXY_HTTP_1_0,CURLPROXY_SOCKS4,CURLPROXY_SOCKS5,CURLPROXY_SOCKS4A, andCURLPROXY_SOCKS5_HOSTNAME.

check thecURL docs for more info.

// quick setup with default port: 1080Unirest\Request::proxy('10.10.10.1');// custom port and proxy typeUnirest\Request::proxy('10.10.10.1',8080,CURLPROXY_HTTP);// enable tunnelingUnirest\Request::proxy('10.10.10.1',8080,CURLPROXY_HTTP,true);

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

// basic authUnirest\Request::proxyAuth('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.

SeeAuthentication for more details on methods supported.

// basic authUnirest\Request::proxyAuth('username','password',CURLAUTH_DIGEST);

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

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

You can set default headers in bulk by passing an array:

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

You can clear the default headers anytime with:

Unirest\Request::clearDefaultHeaders();

You can set defaultcURL options that will be sent on every request:

Unirest\Request::curlOpt(CURLOPT_COOKIE,'foo=bar');

You can set options bulk by passing an array:

Unirest\Request::curlOpts(array(CURLOPT_COOKIE =>'foo=bar'));

You can clear the default options anytime with:

Unirest\Request::clearCurlOpts();

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 istrue.

// alias for `curl_getinfo`Unirest\Request::getInfo()// returns internal cURL handleUnirest\Request::getCurlHandle()

Made with ♥ from theMashape team