apimatic / unirest-php
Unirest PHP
Installs: 2 540 284
Dependents: 55
Suggesters: 0
Security: 0
Stars: 19
Watchers: 7
Forks: 12
Open Issues: 0
Requires
- php: ^7.2 || ^8.0
- ext-curl: *
- ext-json: *
- apimatic/core-interfaces: ^0.1.0
Requires (Dev)
- phan/phan: 5.4.2
- phpunit/phpunit: ^7.5 || ^8.5 || ^9.5
- squizlabs/php_codesniffer: ^3.5
This package is auto-updated.
Last update: 2024-11-04 05:49:36 UTC
README
Unirest is a set of lightweight HTTP libraries available in multiple languages.
This fork is maintained by APIMatic for its Code Generator as a Service.
Features
- Request class to create custom requests
- Simple HttpClientInterface to execute a Request
- Automatic JSON parsing into a native object for JSON responses
- Response data class to store http response information
- Supports form parameters, file uploads and custom body entities
- Supports gzip
- Supports Basic, Digest, Negotiate, NTLM Authentication natively
- Configuration class manage all the HttpClient's configurations
- Customizable timeout
- Customizable retries and backoff
- Customizable default headers for every request (DRY)
Supported PHP Versions
- PHP 7.2
- PHP 7.4
- PHP 8.0
- PHP 8.1
- PHP 8.2
Installation
To install apimatic/unirest-php
with Composer, just add the following to your composer.json
file:
{ "require": { "apimatic/unirest-php": "^4.0.0" } }
or by running the following command:
composer require apimatic/unirest-php
Usage
Creating a HttpClient with Default Configurations
You can create a variable at class level and instantiate it with an instance of HttpClient
, like:
private $httpClient = new \Unirest\HttpClient();
Creating a HttpClient with Custom Configurations
To create a client with custom configurations you first required an instance of Configuration
, and then add it to the HttpClient during its initialization, like:
$configurations = \Unirest\Configuration::init() ->timeout(10) ->enableRetries(true) ->retryInterval(2.5); $httpClient = new \Unirest\HttpClient($configurations);
This Configuration
instance can further be customized by setting properties like: maximumRetryWaitTime
, verifyPeer
, defaultHeaders
, etc. Check out Advanced Configuration for more information.
Creating a Request
After the initialization of HttpClient, you will be needing an instance of Request
that is required to be exchanged as Response
.
$request = new \Unirest\Request\Request( 'http://mockbin.com/request', RequestMethod::GET, ['headerKey' => 'headerValue'], Unirest\Request\Body::json(["key" => "value"]'), RetryOption::ENABLE_RETRY );
Let's look at a working example of sending the above request:
$headers = array('Accept' => 'application/json'); $query = array('foo' => 'hello', 'bar' => 'world'); $response = $this->httpClient->execute($request); $response->getStatusCode(); // HTTP Status code $response->getHeaders(); // Headers $response->getBody(); // Parsed body $response->getRawBody(); // 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); $request = new \Unirest\Request\Request( 'http://mockbin.com/request', RequestMethod::POST, $headers, $body ); $response = $this->httpClient->execute($request);
Notes:
Content-Type
headers will be automatically set toapplication/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); $request = new \Unirest\Request\Request( 'http://mockbin.com/request', RequestMethod::POST, $headers, $body ); $response = $this->httpClient->execute($request);
Notes:
Content-Type
headers will be automatically set toapplication/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); $request = new \Unirest\Request\Request( 'http://mockbin.com/request', RequestMethod::POST, $headers, $body ); $response = $this->httpClient->execute($request);
Notes:
Content-Type
headers will be automatically set tomultipart/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); $request = new \Unirest\Request\Request( 'http://mockbin.com/request', RequestMethod::POST, $headers, $body ); $response = $this->httpClient->execute($request);
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') ); $request = new \Unirest\Request\Request( 'http://mockbin.com/request', RequestMethod::POST, $headers, $body ); $response = $this->httpClient->execute($request);
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')); $request = new \Unirest\Request\Request( 'http://mockbin.com/request', RequestMethod::POST, $headers, $body ); $response = $this->httpClient->execute($request);
Authentication
For Authentication you need httpClient instance with custom configurations, So, create Configuration
instance like:
// Basic auth $configuration = Configuration::init() ->auth('username', 'password', CURLAUTH_BASIC);
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 $configuration = Configuration::init() ->proxyAuth('username', 'password', CURLAUTH_DIGEST);
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")
$configuration = Configuration::init() ->cookie($cookie);
Set a cookie file path for enabling cookie reading and storing cookies across multiple sequence of requests.
$this->request->cookieFile($cookieFile)
$cookieFile
must be a correct path with write permission.
Response Object
Upon receiving 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.
getStatusCode()
- HTTP Response Status Code (Example200
)getHeaders()
- HTTP Response HeadersgetBody()
- Parsed response body where applicable, for example JSON responses are parsed to Objects / Associative Arrays.getRawBody()
- 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:
$configuration = Configuration::init() ->jsonOpts(true, 512, JSON_NUMERIC_CHECK & JSON_FORCE_OBJECT & JSON_UNESCAPED_SLASHES);
Timeout
You can set a custom timeout value (in seconds):
$configuration = Configuration::init() ->timeout(5); // 5s timeout
Retries Related
$configuration = Configuration::init() ->enableRetries(true) // To enable retries feature ->maxNumberOfRetries(10) // To set max number of retries ->retryOnTimeout(false) // Should we retry on timeout ->retryInterval(20) // Initial retry interval in seconds ->maximumRetryWaitTime(30) // Maximum retry wait time ->backoffFactor(1.1) // Backoff factor to be used to increase retry interval ->httpStatusCodesToRetry([400,401]) // Http status codes to retry against ->httpMethodsToRetry(['POST']) // Http methods to retry against
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 $configuration = Configuration::init() ->proxy('10.10.10.1'); // custom port and proxy type $configuration = Configuration::init() ->proxy('10.10.10.1', 8080, CURLPROXY_HTTP); // enable tunneling $configuration = Configuration::init() ->proxy('10.10.10.1', 8080, CURLPROXY_HTTP, true);
Proxy Authentication
Passing a username, password (optional), defaults to Basic Authentication:
// basic auth $configuration = Configuration::init() ->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 $configuration = Configuration::init() ->proxyAuth('username', 'password', CURLAUTH_DIGEST);
Default Request Headers
You can set default headers that will be sent on every request:
$configuration = Configuration::init() ->defaultHeader('Header1', 'Value1') ->defaultHeader('Header2', 'Value2');
You can set default headers in bulk by passing an array:
$configuration = Configuration::init() ->defaultHeaders([ 'Header1' => 'Value1', 'Header2' => 'Value2' ]);
You can clear the default headers anytime with:
$configuration = Configuration::init() ->clearDefaultHeaders();
Default cURL Options
You can set default cURL options that will be sent on every request:
$configuration = Configuration::init() ->curlOpt(CURLOPT_COOKIE, 'foo=bar');
You can set options bulk by passing an array:
$configuration = Configuration::init() ->curlOpts(array( CURLOPT_COOKIE => 'foo=bar' ));
You can clear the default options anytime with:
$configuration = Configuration::init() ->clearCurlOpts();
SSL validation
You can explicitly enable or disable SSL certificate validation when consuming an SSL protected endpoint:
$configuration = Configuration::init() ->verifyPeer(false); // Disables SSL cert validation
By default is true
.
Utility Methods
// alias for `curl_getinfo` $httpClient->getInfo();