Compare commits
10 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
d5a7ad40bd | ||
|
|
8af870ff69 | ||
|
|
ae01978eb3 | ||
|
|
2074abf904 | ||
|
|
96cdf61101 | ||
|
|
002c175cd1 | ||
|
|
c5be546d1b | ||
|
|
5fa02336f9 | ||
|
|
23c3cb5b00 | ||
|
|
8ce5204c37 |
130
README.md
130
README.md
@@ -1,19 +1,20 @@
|
||||
# Unirest for PHP [![version][composer-image]][composer-url]
|
||||
# Unirest for PHP [![Build Status][travis-image]][travis-url] [![version][packagist-version]][packagist-url]
|
||||
|
||||
[![Build Status][travis-image]][travis-url]
|
||||
[![Code Climate][codeclimate-image]][codeclimate-url]
|
||||
[![Coverage Status][codecoverage-image]][codecoverage-url]
|
||||
[![Dependency Status][dependency-image]][dependency-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 is a set of lightweight HTTP libraries available in multiple languages, ideal for most applications:
|
||||
Unirest is a set of lightweight HTTP libraries available in [multiple languages](http://unirest.io).
|
||||
|
||||
## 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
|
||||
* 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
|
||||
@@ -109,29 +110,59 @@ $body = json_encode(array("foo" => "hellow", "bar" => "world"));
|
||||
$response = Unirest\Request::post("http://httpbin.org/post", $headers, $body);
|
||||
```
|
||||
|
||||
### Basic Authentication
|
||||
### Authentication
|
||||
|
||||
Authenticating the request with basic authentication can be done by providing the `username` and `password` arguments:
|
||||
Passing a username, password *(optional)*, defaults to Basic Authentication:
|
||||
|
||||
```php
|
||||
// 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 Method**
|
||||
|
||||
| Method | Description |
|
||||
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `CURLAUTH_BASIC` | HTTP Basic authentication. This is the default choice |
|
||||
| `CURLAUTH_DIGEST` | HTTP Digest authentication. as defined in [RFC 2617](http://www.ietf.org/rfc/rfc2617.txt) |
|
||||
| `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](http://www.ietf.org/rfc/rfc4559.txt) |
|
||||
| `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](http://curl.haxx.se/libcurl/c/CURLOPT_HTTPAUTH.html) 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. |
|
||||
|
||||
```php
|
||||
// custom auth method
|
||||
Unirest\Request::proxyAuth('username', 'password', CURLAUTH_DIGEST);
|
||||
```
|
||||
|
||||
Previous versions of **Unirest** support *Basic Authentication* by providing the `username` and `password` arguments:
|
||||
|
||||
```php
|
||||
$response = Unirest\Request::get("http://httpbin.org/get", 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**
|
||||
|
||||
### Request Object
|
||||
|
||||
```php
|
||||
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)
|
||||
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
|
||||
- `username` - Basic Authentication username
|
||||
- `password` - Basic Authentication password
|
||||
|
||||
You can send a request with any [standard](http://www.iana.org/assignments/http-methods/http-methods.xhtml) or custom HTTP Method:
|
||||
|
||||
@@ -173,6 +204,45 @@ 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](http://curl.haxx.se/libcurl/c/CURLOPT_PROXYTYPE.html) for more info*.
|
||||
|
||||
```php
|
||||
// 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:
|
||||
|
||||
```php
|
||||
// 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](#authentication) for more details on methods supported.
|
||||
|
||||
```php
|
||||
// basic auth
|
||||
Unirest\Request::proxyAuth('username', 'password', CURLAUTH_DIGEST);
|
||||
```
|
||||
|
||||
#### Default Request Headers
|
||||
|
||||
You can set default headers that will be sent on every request:
|
||||
@@ -207,26 +277,26 @@ Unirest\Request::verifyPeer(false); // Disables SSL cert validation
|
||||
|
||||
By default is `true`.
|
||||
|
||||
## License
|
||||
----
|
||||
|
||||
Licensed under [the MIT license](https://github.com/Mashape/unirest-php/blob/master/LICENSE).
|
||||
Made with ♥ from the [Mashape](https://www.mashape.com/) team
|
||||
|
||||
Created with love by [Mashape](https://www.mashape.com/).
|
||||
[license-url]: https://github.com/Mashape/unirest-php/blob/master/LICENSE
|
||||
|
||||
[gitter-url]: https://gitter.im/Mashape/unirest-php
|
||||
[gitter-image]: https://badges.gitter.im/Join%20Chat.svg
|
||||
|
||||
[composer-url]: http://badge.fury.io/ph/mashape%2Funirest-php
|
||||
[composer-image]: https://badge.fury.io/ph/mashape%2Funirest-php.svg
|
||||
[gitter-image]: https://img.shields.io/badge/Gitter-Join%20Chat-blue.svg?style=flat
|
||||
|
||||
[travis-url]: https://travis-ci.org/Mashape/unirest-php
|
||||
[travis-image]: https://travis-ci.org/Mashape/unirest-php.png?branch=master
|
||||
[travis-image]: https://img.shields.io/travis/Mashape/unirest-php.svg?style=flat
|
||||
|
||||
[packagist-url]: https://packagist.org/packages/Mashape/unirest-php
|
||||
[packagist-license]: https://img.shields.io/packagist/l/Mashape/unirest-php.svg?style=flat
|
||||
[packagist-version]: https://img.shields.io/packagist/v/Mashape/unirest-php.svg?style=flat
|
||||
[packagist-downloads]: https://img.shields.io/packagist/dm/Mashape/unirest-php.svg?style=flat
|
||||
|
||||
[codeclimate-url]: https://codeclimate.com/github/Mashape/unirest-php
|
||||
[codeclimate-image]: https://codeclimate.com/github/Mashape/unirest-php/badges/gpa.svg
|
||||
[codeclimate-quality]: https://img.shields.io/codeclimate/github/Mashape/unirest-php.svg?style=flat
|
||||
[codeclimate-coverage]: https://img.shields.io/codeclimate/coverage/github/Mashape/unirest-php.svg?style=flat
|
||||
|
||||
[codecoverage-url]: https://codeclimate.com/github/Mashape/unirest-php
|
||||
[codecoverage-image]: https://codeclimate.com/github/Mashape/unirest-php/badges/coverage.svg
|
||||
|
||||
[dependency-url]: https://www.versioneye.com/user/projects/54b702db050646ca5c00019d
|
||||
[dependency-image]: https://www.versioneye.com/user/projects/54b702db050646ca5c00019d/badge.svg?style=flat
|
||||
[versioneye-url]: https://www.versioneye.com/user/projects/54b82450050646ca5c0001f3
|
||||
[versioneye-image]: https://img.shields.io/versioneye/d/user/projects/54b82450050646ca5c0001f3.svg?style=flat
|
||||
|
||||
@@ -12,6 +12,24 @@ class Request
|
||||
private static $socketTimeout = null;
|
||||
private static $defaultHeaders = array();
|
||||
|
||||
private static $auth = array (
|
||||
'user' => '',
|
||||
'pass' => '',
|
||||
'method' => CURLAUTH_BASIC
|
||||
);
|
||||
|
||||
private static $proxy = array(
|
||||
'port' => false,
|
||||
'tunnel' => false,
|
||||
'address' => false,
|
||||
'type' => CURLPROXY_HTTP,
|
||||
'auth' => array (
|
||||
'user' => '',
|
||||
'pass' => '',
|
||||
'method' => CURLAUTH_BASIC
|
||||
)
|
||||
);
|
||||
|
||||
/**
|
||||
* Set JSON decode mode
|
||||
*
|
||||
@@ -77,14 +95,59 @@ class Request
|
||||
return self::$defaultHeaders = array();
|
||||
}
|
||||
|
||||
/**
|
||||
* Set authentication method to use
|
||||
*
|
||||
* @param string $username authentication username
|
||||
* @param string $password authentication password
|
||||
* @param string $method authentication method
|
||||
*/
|
||||
public static function auth($username = '', $password = '', $method = CURLAUTH_BASIC)
|
||||
{
|
||||
self::$auth['user'] = $username;
|
||||
self::$auth['pass'] = $password;
|
||||
self::$auth['method'] = $method;
|
||||
}
|
||||
|
||||
/**
|
||||
* Set proxy to use
|
||||
*
|
||||
* @param string $address proxy address
|
||||
* @param string $port proxy port
|
||||
* @param string $port proxy type (Available options for this are CURLPROXY_HTTP, CURLPROXY_HTTP_1_0 CURLPROXY_SOCKS4, CURLPROXY_SOCKS5, CURLPROXY_SOCKS4A and CURLPROXY_SOCKS5_HOSTNAME)
|
||||
* @param string $tunnel enable/disable tunneling
|
||||
*/
|
||||
public static function proxy($address, $port = 1080, $type = CURLPROXY_HTTP, $tunnel = false)
|
||||
{
|
||||
self::$proxy['type'] = $type;
|
||||
self::$proxy['port'] = $port;
|
||||
self::$proxy['tunnel'] = $tunnel;
|
||||
self::$proxy['address'] = $address;
|
||||
}
|
||||
|
||||
/**
|
||||
* Set proxy authentication method to use
|
||||
*
|
||||
* @param string $username authentication username
|
||||
* @param string $password authentication password
|
||||
* @param string $method authentication method
|
||||
* @param string $tunnel enable/disable tunneling
|
||||
*/
|
||||
public static function proxyAuth($username = '', $password = '', $method = CURLAUTH_BASIC)
|
||||
{
|
||||
self::$proxy['auth']['user'] = $username;
|
||||
self::$proxy['auth']['pass'] = $password;
|
||||
self::$proxy['auth']['method'] = $method;
|
||||
}
|
||||
|
||||
/**
|
||||
* Send a GET request to a URL
|
||||
*
|
||||
* @param string $url URL to send the GET request to
|
||||
* @param array $headers additional headers to send
|
||||
* @param mixed $parameters parameters to send in the querystring
|
||||
* @param string $username Basic Authentication username
|
||||
* @param string $password Basic Authentication password
|
||||
* @param string $username Authentication username (deprecated)
|
||||
* @param string $password Authentication password (deprecated)
|
||||
* @return string|stdObj response string or stdObj if response is json-decodable
|
||||
*/
|
||||
public static function get($url, $headers = array(), $parameters = null, $username = null, $password = null)
|
||||
@@ -97,8 +160,8 @@ class Request
|
||||
* @param string $url URL to send the HEAD request to
|
||||
* @param array $headers additional headers to send
|
||||
* @param mixed $parameters parameters to send in the querystring
|
||||
* @param string $username Basic Authentication username
|
||||
* @param string $password Basic Authentication password
|
||||
* @param string $username Basic Authentication username (deprecated)
|
||||
* @param string $password Basic Authentication password (deprecated)
|
||||
* @return string|stdObj response string or stdObj if response is json-decodable
|
||||
*/
|
||||
public static function head($url, $headers = array(), $parameters = null, $username = null, $password = null)
|
||||
@@ -125,8 +188,8 @@ class Request
|
||||
* @param string $url URL to send the CONNECT request to
|
||||
* @param array $headers additional headers to send
|
||||
* @param mixed $parameters parameters to send in the querystring
|
||||
* @param string $username Basic Authentication username
|
||||
* @param string $password Basic Authentication password
|
||||
* @param string $username Basic Authentication username (deprecated)
|
||||
* @param string $password Basic Authentication password (deprecated)
|
||||
* @return string|stdObj response string or stdObj if response is json-decodable
|
||||
*/
|
||||
public static function connect($url, $headers = array(), $parameters = null, $username = null, $password = null)
|
||||
@@ -139,8 +202,8 @@ class Request
|
||||
* @param string $url URL to send the POST request to
|
||||
* @param array $headers additional headers to send
|
||||
* @param mixed $body POST body data
|
||||
* @param string $username Basic Authentication username
|
||||
* @param string $password Basic Authentication password
|
||||
* @param string $username Basic Authentication username (deprecated)
|
||||
* @param string $password Basic Authentication password (deprecated)
|
||||
* @return string|stdObj response string or stdObj if response is json-decodable
|
||||
*/
|
||||
public static function post($url, $headers = array(), $body = null, $username = null, $password = null)
|
||||
@@ -153,8 +216,8 @@ class Request
|
||||
* @param string $url URL to send the DELETE request to
|
||||
* @param array $headers additional headers to send
|
||||
* @param mixed $body DELETE body data
|
||||
* @param string $username Basic Authentication username
|
||||
* @param string $password Basic Authentication password
|
||||
* @param string $username Basic Authentication username (deprecated)
|
||||
* @param string $password Basic Authentication password (deprecated)
|
||||
* @return string|stdObj response string or stdObj if response is json-decodable
|
||||
*/
|
||||
public static function delete($url, $headers = array(), $body = null, $username = null, $password = null)
|
||||
@@ -167,8 +230,8 @@ class Request
|
||||
* @param string $url URL to send the PUT request to
|
||||
* @param array $headers additional headers to send
|
||||
* @param mixed $body PUT body data
|
||||
* @param string $username Basic Authentication username
|
||||
* @param string $password Basic Authentication password
|
||||
* @param string $username Basic Authentication username (deprecated)
|
||||
* @param string $password Basic Authentication password (deprecated)
|
||||
* @return string|stdObj response string or stdObj if response is json-decodable
|
||||
*/
|
||||
public static function put($url, $headers = array(), $body = null, $username = null, $password = null)
|
||||
@@ -181,8 +244,8 @@ class Request
|
||||
* @param string $url URL to send the PATCH request to
|
||||
* @param array $headers additional headers to send
|
||||
* @param mixed $body PATCH body data
|
||||
* @param string $username Basic Authentication username
|
||||
* @param string $password Basic Authentication password
|
||||
* @param string $username Basic Authentication username (deprecated)
|
||||
* @param string $password Basic Authentication password (deprecated)
|
||||
* @return string|stdObj response string or stdObj if response is json-decodable
|
||||
*/
|
||||
public static function patch($url, $headers = array(), $body = null, $username = null, $password = null)
|
||||
@@ -195,8 +258,8 @@ class Request
|
||||
* @param string $url URL to send the TRACE request to
|
||||
* @param array $headers additional headers to send
|
||||
* @param mixed $body TRACE body data
|
||||
* @param string $username Basic Authentication username
|
||||
* @param string $password Basic Authentication password
|
||||
* @param string $username Basic Authentication username (deprecated)
|
||||
* @param string $password Basic Authentication password (deprecated)
|
||||
* @return string|stdObj response string or stdObj if response is json-decodable
|
||||
*/
|
||||
public static function trace($url, $headers = array(), $body = null, $username = null, $password = null)
|
||||
@@ -239,8 +302,8 @@ class Request
|
||||
* @param string $url URL to send the request to
|
||||
* @param mixed $body request body
|
||||
* @param array $headers additional headers to send
|
||||
* @param string $username Basic Authentication username
|
||||
* @param string $password Basic Authentication password
|
||||
* @param string $username Authentication username (deprecated)
|
||||
* @param string $password Authentication password (deprecated)
|
||||
* @throws Exception if a cURL error occurs
|
||||
* @return Unirest\Response
|
||||
*/
|
||||
@@ -279,8 +342,25 @@ class Request
|
||||
curl_setopt($ch, CURLOPT_TIMEOUT, self::$socketTimeout);
|
||||
}
|
||||
|
||||
// supporting deprecated http auth method
|
||||
if (!empty($username)) {
|
||||
curl_setopt($ch, CURLOPT_USERPWD, $username . ':' . ((empty($password)) ? '' : $password));
|
||||
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
|
||||
curl_setopt($ch, CURLOPT_USERPWD, $username . ':' . $password);
|
||||
}
|
||||
|
||||
if (!empty(self::$auth['user'])) {
|
||||
curl_setopt($ch, CURLOPT_HTTPAUTH, self::$auth['method']);
|
||||
curl_setopt($ch, CURLOPT_USERPWD, self::$auth['user'] . ':' . self::$auth['pass']);
|
||||
}
|
||||
|
||||
if (self::$proxy['address'] !== false) {
|
||||
curl_setopt($ch, CURLOPT_PROXYTYPE, self::$proxy['type']);
|
||||
curl_setopt($ch, CURLOPT_PROXY, self::$proxy['address']);
|
||||
curl_setopt($ch, CURLOPT_PROXYPORT, self::$proxy['port']);
|
||||
curl_setopt($ch, CURLOPT_HTTPPROXYTUNNEL, self::$proxy['tunnel']);
|
||||
|
||||
curl_setopt($ch, CURLOPT_PROXYAUTH, self::$proxy['auth']['method']);
|
||||
curl_setopt($ch, CURLOPT_PROXYUSERPWD, self::$proxy['auth']['user'] . ':' . self::$proxy['auth']['pass']);
|
||||
}
|
||||
|
||||
$response = curl_exec($ch);
|
||||
|
||||
@@ -71,13 +71,21 @@ class UnirestRequestTest extends \PHPUnit_Framework_TestCase
|
||||
$this->assertEquals(true, $args->gzipped);
|
||||
}
|
||||
|
||||
public function testBasicAuthentication()
|
||||
public function testBasicAuthenticationDeprecated()
|
||||
{
|
||||
$response = Unirest\Request::get('http://httpbin.org/get', array(), array(), 'user', 'password');
|
||||
$headers = $response->body->headers;
|
||||
$this->assertEquals('Basic dXNlcjpwYXNzd29yZA==', $headers->Authorization);
|
||||
}
|
||||
|
||||
public function testBasicAuthentication()
|
||||
{
|
||||
Unirest\Request::auth('user', 'password');
|
||||
$response = Unirest\Request::get('http://httpbin.org/get');
|
||||
|
||||
$this->assertEquals('Basic dXNlcjpwYXNzd29yZA==', $response->body->headers->Authorization);
|
||||
}
|
||||
|
||||
public function testCustomHeaders()
|
||||
{
|
||||
$response = Unirest\Request::get('http://httpbin.org/get', array(
|
||||
|
||||
Reference in New Issue
Block a user