Unirest for PHP 
Unirest is a set of lightweight HTTP libraries available in multiple languages, built and maintained by Mashape, who also maintain the open-source API Gateway Kong.
Features
- Utility methods to call
GET,HEAD,POST,PUT,DELETE,CONNECT,OPTIONS,TRACE,PATCHrequests - 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-Typeheaders will be automatically set toapplication/json- the data variable will be processed through
json_encodewith 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-Typeheaders will be automatically set toapplication/x-www-form-urlencoded- the final data array will be processed through
http_build_querywith 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-Typeheaders will be automatically set tomultipart/form-data.- an auto-generated
--boundarywill 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 auth
Unirest\Request::setMashapeKey('<mashape_key>');
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
| Method | Description |
|---|---|
CURLAUTH_BASIC |
HTTP Basic authentication. This is the default choice |
CURLAUTH_DIGEST |
HTTP Digest authentication. as defined in RFC 2617 |
CURLAUTH_DIGEST_IE |
HTTP Digest authentication with an IE flavor. The IE flavor is simply that libcurl will use a special "quirk" that IE is known to have used before version 7 and that some servers require the client to use. |
CURLAUTH_NEGOTIATE |
HTTP Negotiate (SPNEGO) authentication. as defined in RFC 4559 |
CURLAUTH_NTLM |
HTTP NTLM authentication. A proprietary protocol invented and used by Microsoft. |
CURLAUTH_NTLM_WB |
NTLM delegating to winbind helper. Authentication is performed by a separate binary application. see libcurl docs for more info |
CURLAUTH_ANY |
This is a convenience macro that sets all bits and thus makes libcurl pick any it finds suitable. libcurl will automatically select the one it finds most secure. |
CURLAUTH_ANYSAFE |
This is a convenience macro that sets all bits except Basic and thus makes libcurl pick any it finds suitable. libcurl will automatically select the one it finds most secure. |
CURLAUTH_ONLY |
This is a meta symbol. OR this value together with a single specific auth value to force libcurl to probe for un-restricted auth and if not, only that single auth algorithm is acceptable. |
// 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 objectbody- 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 (Example200)headers- HTTP Response Headersbody- 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);
// enable tunneling
Unirest\Request::proxy('10.10.10.1', 8080, CURLPROXY_HTTP, true);
Proxy Authenticaton
Passing a username, password (optional), defaults to Basic Authentication:
// basic auth
Unirest\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.
See Authentication for more details on methods supported.
// basic auth
Unirest\Request::proxyAuth('username', 'password', CURLAUTH_DIGEST);
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 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();
Default cURL Options
You can set default cURL 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();
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.
Utility Methods
// alias for `curl_getinfo`
Unirest\Request::getInfo()
// returns internal cURL handle
Unirest\Request::getCurlHandle()
Made with
14 Oct 26, 2022
1.9k Jan 4, 2023
3 Aug 26, 2022
22.3k Jan 2, 2023
1.7k Dec 21, 2022
2.4k Dec 30, 2022
101 Dec 1, 2022
15 Nov 17, 2022
3 Jan 17, 2022
641 Dec 19, 2022
15 Sep 5, 2022
640 Dec 29, 2022
3.5k Dec 31, 2022
1.9k Dec 26, 2022
5 Sep 14, 2022
5 Aug 19, 2022