Merge pull request #90 from Furgas/fix-phpdoc

Fix PHPDoc

.gitignore

@@ -1,3 +1,4 @@
+.idea
 .DS_Store
 build
 vendor

.travis.yml

@@ -26,3 +26,11 @@ matrix:
   fast_finish: true
   allow_failures:
     - php: hhvm
+
+notifications:
+  webhooks:
+    urls:
+      - https://webhooks.gitter.im/e/d4319553d0aecfd5b9ac
+    on_success: always
+    on_failure: always
+    on_start: false

README.md

@@ -7,7 +7,11 @@
 [![Gitter][gitter-image]][gitter-url]
 [![License][packagist-license]][license-url]
 
-Unirest is a set of lightweight HTTP libraries available in [multiple languages](http://unirest.io).
+![][unirest-logo]
+
+
+[Unirest](http://unirest.io) is a set of lightweight HTTP libraries available in multiple languages, built and maintained by [Mashape](https://github.com/Mashape), who also maintain the open-source API Gateway [Kong](https://github.com/Mashape/kong). 
+
 
 ## Features
 
@@ -22,6 +26,7 @@ Unirest is a set of lightweight HTTP libraries available in [multiple languages]
 ## Requirements
 
 - [cURL](http://php.net/manual/en/book.curl.php)
+- PHP 5.4+
 
 ## Installation
 
@@ -46,7 +51,7 @@ 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:
 
 ```shell
-composer require mashape/php-test-reporter:@dev-master
+composer require mashape/php-test-reporter dev-master
 ```
 
 Composer installs autoloader at `./vendor/autoloader.php`. to include the library in your script, add:
@@ -61,7 +66,7 @@ If you use Symfony2, autoloader has to be detected automatically.
 
 ### Install from source
 
-Unirest-PHP requires PHP `v5.4+`. Download the PHP library from Github, then include `Unirest.php` in your script:
+Download the PHP library from Github, then include `Unirest.php` in your script:
 
 ```shell
 git clone git@github.com:Mashape/unirest-php.git 
@@ -156,6 +161,22 @@ $response = Unirest\Request::get("http://mockbin.com/request", null, null, "user
 
 **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")
+
+```php
+Unirest\Request::cookie($cookie)
+```
+
+Set a cookie file path for enabling cookie reading and storing cookies across multiple sequence of requests.
+
+```php
+Unirest\Request::cookieFile($cookieFile)
+```
+
+`$cookieFile` must be a correct path with write permission.
+
 ### Request Object
 
 ```php
@@ -258,7 +279,7 @@ Unirest\Request::defaultHeader("Header1", "Value1");
 Unirest\Request::defaultHeader("Header2", "Value2");
 ```
 
-You can do set default headers in bulk:
+You can set default headers in bulk by passing an array:
 
 ```php
 Unirest\Request::defaultHeaders(array(
@@ -273,6 +294,28 @@ You can clear the default headers anytime with:
 Unirest\Request::clearDefaultHeaders();
 ```
 
+#### Default cURL Options
+
+You can set default [cURL options](http://php.net/manual/en/function.curl-setopt.php) that will be sent on every request:
+
+```php
+Unirest\Request::curlOpt(CURLOPT_COOKIE, "foo=bar");
+```
+
+You can set options bulk by passing an array:
+
+```php
+Unirest\Request::curlOpts(array(
+    CURLOPT_COOKIE => "foo=bar"
+));
+```
+
+You can clear the default options anytime with:
+
+```php
+Unirest\Request::clearCurlOpts();
+```
+
 #### SSL validation
 
 You can explicitly enable or disable SSL certificate validation when consuming an SSL protected endpoint:
@@ -297,6 +340,9 @@ Unirest\Request::getCurlHandle()
 
 Made with ♥ from the [Mashape][mashape-url] team
 
+[unirest-logo]: http://cl.ly/image/2P373Y090s2O/Image%202015-10-12%20at%209.48.06%20PM.png
+
+
 [mashape-url]: https://www.mashape.com/
 
 [license-url]: https://github.com/Mashape/unirest-php/blob/master/LICENSE

src/Unirest/File.php

@@ -6,7 +6,10 @@ class File
 {
     /**
      * Prepares a file for upload. To be used inside the parameters declaration for a request.
-     * @param string $path The file path
+     * @param string $filename The file path
+     * @param string $mimetype MIME type
+     * @param string $postname the file name
+     * @return string|\CURLFile
      */
     public static function add($filename, $mimetype = '', $postname = '')
     {

src/Unirest/Request.php

@@ -2,16 +2,17 @@
 
 namespace Unirest;
 
-use Unirest\Method;
-use Unirest\Response;
-
 class Request
 {
+    private static $cookie = null;
+    private static $cookieFile = null;
+    private static $curlOpts = array();
+    private static $defaultHeaders = array();
     private static $handle = null;
     private static $jsonOpts = array();
-    private static $verifyPeer = true;
     private static $socketTimeout = null;
-    private static $defaultHeaders = array();
+    private static $verifyPeer = true;
+    private static $verifyHost = true;
 
     private static $auth = array (
         'user' => '',
@@ -35,8 +36,9 @@ class Request
      * Set JSON decode mode
      *
      * @param bool $assoc When TRUE, returned objects will be converted into associative arrays.
-     * @param bool $depth User specified recursion depth.
-     * @param bool $options Bitmask of JSON decode options. Currently only JSON_BIGINT_AS_STRING is supported (default is to cast large integers as floats)
+     * @param integer $depth User specified recursion depth.
+     * @param integer $options Bitmask of JSON decode options. Currently only JSON_BIGINT_AS_STRING is supported (default is to cast large integers as floats)
+     * @return array
      */
     public static function jsonOpts($assoc = false, $depth = 512, $options = 0)
     {
@@ -47,16 +49,29 @@ class Request
      * Verify SSL peer
      *
      * @param bool $enabled enable SSL verification, by default is true
+     * @return bool
      */
     public static function verifyPeer($enabled)
     {
         return self::$verifyPeer = $enabled;
     }
 
+    /**
+     * Verify SSL host
+     *
+     * @param bool $enabled enable SSL host verification, by default is true
+     * @return bool
+     */
+    public static function verifyHost($enabled)
+    {
+        return self::$verifyHost = $enabled;
+    }
+
     /**
      * Set a timeout
      *
      * @param integer $seconds timeout value in seconds
+     * @return integer
      */
     public static function timeout($seconds)
     {
@@ -70,11 +85,7 @@ class Request
      */
     public static function defaultHeaders($headers)
     {
-        foreach ($headers as $name => $value) {
-            self::$defaultHeaders[$name] = $value;
-        }
-
-        return $headers;
+        return self::$defaultHeaders = array_merge(self::$defaultHeaders, $headers);
     }
 
     /**
@@ -82,26 +93,13 @@ class Request
      *
      * @param string $name header name
      * @param string $value header value
+     * @return string
      */
     public static function defaultHeader($name, $value)
     {
         return self::$defaultHeaders[$name] = $value;
     }
 
-    /**
-     * Set a Mashape key to send on every request as a header
-     * Obtain your Mashape key by browsing one of your Mashape applications on https://www.mashape.com
-     *
-     * Note: Mashape provides 2 keys for each application: a 'Testing' and a 'Production' one.
-     *       Be aware of which key you are using and do not share your Production key.
-     *
-     * @param string $key Mashape key
-     */
-    public static function setMashapeKey($key)
-    {
-        return self::defaultHeader('X-Mashape-Key', $key);
-    }
-
     /**
      * Clear all the default headers
      */
@@ -110,12 +108,80 @@ class Request
         return self::$defaultHeaders = array();
     }
 
+    /**
+     * Set curl options to send on every request
+     *
+     * @param array $options options array
+     * @return array
+     */
+    public static function curlOpts($options)
+    {
+        return self::mergeCurlOptions(self::$curlOpts, $options);
+    }
+
+    /**
+     * Set a new default header to send on every request
+     *
+     * @param string $name header name
+     * @param string $value header value
+     * @return string
+     */
+    public static function curlOpt($name, $value)
+    {
+        return self::$curlOpts[$name] = $value;
+    }
+
+    /**
+     * Clear all the default headers
+     */
+    public static function clearCurlOpts()
+    {
+        return self::$curlOpts = array();
+    }
+
+    /**
+     * Set a Mashape key to send on every request as a header
+     * Obtain your Mashape key by browsing one of your Mashape applications on https://www.mashape.com
+     *
+     * Note: Mashape provides 2 keys for each application: a 'Testing' and a 'Production' one.
+     *       Be aware of which key you are using and do not share your Production key.
+     *
+     * @param string $key Mashape key
+     * @return string
+     */
+    public static function setMashapeKey($key)
+    {
+        return self::defaultHeader('X-Mashape-Key', $key);
+    }
+
+    /**
+     * Set a coockie string for enabling coockie handling
+     *
+     * @param string $cookie
+     */
+    public static function cookie($cookie)
+    {
+        self::$cookie = $cookie;
+    }
+
+    /**
+     * Set a coockie file path for enabling coockie handling
+     *
+     * $cookieFile must be a correct path with write permission
+     *
+     * @param string $cookieFile - path to file for saving cookie
+     */
+    public static function cookieFile($cookieFile)
+    {
+        self::$cookieFile = $cookieFile;
+    }
+
     /**
      * Set authentication method to use
      *
      * @param string $username authentication username
      * @param string $password authentication password
-     * @param string $method authentication method
+     * @param integer $method authentication method
      */
     public static function auth($username = '', $password = '', $method = CURLAUTH_BASIC)
     {
@@ -128,9 +194,9 @@ class Request
      * 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
+     * @param integer $port proxy port
+     * @param integer $type (Available options for this are CURLPROXY_HTTP, CURLPROXY_HTTP_1_0 CURLPROXY_SOCKS4, CURLPROXY_SOCKS5, CURLPROXY_SOCKS4A and CURLPROXY_SOCKS5_HOSTNAME)
+     * @param bool $tunnel enable/disable tunneling
      */
     public static function proxy($address, $port = 1080, $type = CURLPROXY_HTTP, $tunnel = false)
     {
@@ -145,8 +211,7 @@ class Request
      *
      * @param string $username authentication username
      * @param string $password authentication password
-     * @param string $method authentication method
-     * @param string $tunnel enable/disable tunneling
+     * @param integer $method authentication method
      */
     public static function proxyAuth($username = '', $password = '', $method = CURLAUTH_BASIC)
     {
@@ -163,7 +228,7 @@ class Request
      * @param mixed $parameters parameters to send in the querystring
      * @param string $username Authentication username (deprecated)
      * @param string $password Authentication password (deprecated)
-     * @return string|stdObj response string or stdObj if response is json-decodable
+     * @return \Unirest\Response
      */
     public static function get($url, $headers = array(), $parameters = null, $username = null, $password = null)
     {
@@ -177,7 +242,7 @@ class Request
      * @param mixed $parameters parameters to send in the querystring
      * @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
+     * @return \Unirest\Response
      */
     public static function head($url, $headers = array(), $parameters = null, $username = null, $password = null)
     {
@@ -191,7 +256,7 @@ class Request
      * @param mixed $parameters parameters to send in the querystring
      * @param string $username Basic Authentication username
      * @param string $password Basic Authentication password
-     * @return string|stdObj response string or stdObj if response is json-decodable
+     * @return \Unirest\Response
      */
     public static function options($url, $headers = array(), $parameters = null, $username = null, $password = null)
     {
@@ -205,7 +270,7 @@ class Request
      * @param mixed $parameters parameters to send in the querystring
      * @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
+     * @return \Unirest\Response
      */
     public static function connect($url, $headers = array(), $parameters = null, $username = null, $password = null)
     {
@@ -219,7 +284,7 @@ class Request
      * @param mixed $body POST body data
      * @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
+     * @return \Unirest\Response response
      */
     public static function post($url, $headers = array(), $body = null, $username = null, $password = null)
     {
@@ -233,7 +298,7 @@ class Request
      * @param mixed $body DELETE body data
      * @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
+     * @return \Unirest\Response
      */
     public static function delete($url, $headers = array(), $body = null, $username = null, $password = null)
     {
@@ -247,7 +312,7 @@ class Request
      * @param mixed $body PUT body data
      * @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
+     * @return \Unirest\Response
      */
     public static function put($url, $headers = array(), $body = null, $username = null, $password = null)
     {
@@ -261,7 +326,7 @@ class Request
      * @param mixed $body PATCH body data
      * @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
+     * @return \Unirest\Response
      */
     public static function patch($url, $headers = array(), $body = null, $username = null, $password = null)
     {
@@ -275,7 +340,7 @@ class Request
      * @param mixed $body TRACE body data
      * @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
+     * @return \Unirest\Response
      */
     public static function trace($url, $headers = array(), $body = null, $username = null, $password = null)
     {
@@ -285,6 +350,9 @@ class Request
     /**
      * This function is useful for serializing multidimensional arrays, and avoid getting
      * the 'Array to string conversion' notice
+     * @param array|object $data array to flatten.
+     * @param bool|string $parent parent key or false if no parent
+     * @return array
      */
     public static function buildHTTPCurlQuery($data, $parent = false)
     {
@@ -313,14 +381,14 @@ class Request
 
     /**
      * Send a cURL request
-     * @param Unirest\Method $method HTTP method to use
+     * @param \Unirest\Method|string $method HTTP method to use
      * @param string $url URL to send the request to
      * @param mixed $body request body
      * @param array $headers additional headers to send
      * @param string $username Authentication username (deprecated)
      * @param string $password Authentication password (deprecated)
-     * @throws Exception if a cURL error occurs
-     * @return Unirest\Response
+     * @throws \Exception if a cURL error occurs
+     * @return \Unirest\Response
      */
     public static function send($method, $url, $body = null, $headers = array(), $username = null, $password = null)
     {
@@ -344,7 +412,7 @@ class Request
             $url .= urldecode(http_build_query(self::buildHTTPCurlQuery($body)));
         }
 
-        curl_setopt_array(self::$handle, array(
+        $curl_base_options = [
             CURLOPT_URL => self::encodeUrl($url),
             CURLOPT_RETURNTRANSFER => true,
             CURLOPT_FOLLOWLOCATION => true,
@@ -352,14 +420,27 @@ class Request
             CURLOPT_HTTPHEADER => self::getFormattedHeaders($headers),
             CURLOPT_HEADER => true,
             CURLOPT_SSL_VERIFYPEER => self::$verifyPeer,
+            //CURLOPT_SSL_VERIFYHOST accepts only 0 (false) or 2 (true). Future versions of libcurl will treat values 1 and 2 as equals
+            CURLOPT_SSL_VERIFYHOST => self::$verifyHost === false ? 0 : 2,
             // If an empty string, '', is set, a header containing all supported encoding types is sent
             CURLOPT_ENCODING => ''
-        ));
+        ];
+
+        curl_setopt_array(self::$handle, self::mergeCurlOptions($curl_base_options, self::$curlOpts));
 
         if (self::$socketTimeout !== null) {
             curl_setopt(self::$handle, CURLOPT_TIMEOUT, self::$socketTimeout);
         }
 
+        if (self::$cookie) {
+            curl_setopt(self::$handle, CURLOPT_COOKIE, self::$cookie);
+        }
+
+        if (self::$cookieFile) {
+            curl_setopt(self::$handle, CURLOPT_COOKIEFILE, self::$cookieFile);
+            curl_setopt(self::$handle, CURLOPT_COOKIEJAR, self::$cookieFile);
+        }
+
         // supporting deprecated http auth method
         if (!empty($username)) {
             curl_setopt_array(self::$handle, array(
@@ -403,9 +484,15 @@ class Request
         return new Response($httpCode, $body, $header, self::$jsonOpts);
     }
 
-    public static function getInfo()
+    public static function getInfo($opt = false)
     {
-        return curl_getinfo(self::$handle);
+        if ($opt) {
+            $info = curl_getinfo(self::$handle, $opt);
+        } else {
+            $info = curl_getinfo(self::$handle);
+        }
+
+        return $info;
     }
 
     public static function getCurlHandle()
@@ -477,4 +564,15 @@ class Request
         $key = trim(strtolower($key));
         return $key . ': ' . $val;
     }
+
+    /**
+     * @param array $existing_options
+     * @param array $new_options
+     * @return array
+     */
+    private static function mergeCurlOptions(&$existing_options, $new_options)
+    {
+        $existing_options = $new_options + $existing_options;
+        return $existing_options;
+    }
 }

src/Unirest/Response.php

@@ -37,6 +37,8 @@ class Response
      *
      * thanks to ricardovermeltfoort@gmail.com
      * http://php.net/manual/en/function.http-parse-headers.php#112986
+     * @param string $raw_headers raw headers
+     * @return array
      */
     private function parseHeaders($raw_headers)
     {

tests/Unirest/RequestTest.php

@@ -16,6 +16,17 @@ class UnirestRequestTest extends \PHPUnit_Framework_TestCase
         $this->assertEquals($result['file'], $file);
     }
 
+    public function testCurlOpts()
+    {
+        Unirest\Request::curlOpt(CURLOPT_COOKIE, 'foo=bar');
+
+        $response = Unirest\Request::get('http://mockbin.com/request');
+
+        $this->assertTrue(property_exists($response->body->cookies, 'foo'));
+
+        Unirest\Request::clearCurlOpts();
+    }
+
     /**
      * @expectedException Exception
      */
@@ -23,22 +34,35 @@ class UnirestRequestTest extends \PHPUnit_Framework_TestCase
     {
         Unirest\Request::timeout(1);
 
-        Unirest\Request::get('http://mockbin.com/delay/3000');
+        Unirest\Request::get('http://mockbin.com/delay/1000');
 
         Unirest\Request::timeout(null); // Cleaning timeout for the other tests
     }
 
-/*
-    public function testTimeoutSuccess()
+    public function testDefaultHeaders()
     {
-        Unirest\Request::timeout(3);
+        $defaultHeaders = array(
+            'header1' => 'Hello',
+            'header2' => 'world'
+        );
+        Unirest\Request::defaultHeaders($defaultHeaders);
+
+        $response = Unirest\Request::get('http://mockbin.com/request');
 
-        $response = Unirest\Request::get('http://mockbin.com/delay/2000');
         $this->assertEquals(200, $response->code);
+        $this->assertObjectHasAttribute('header1', $response->body->headers);
+        $this->assertEquals('Hello', $response->body->headers->header1);
+        $this->assertObjectHasAttribute('header2', $response->body->headers);
+        $this->assertEquals('world', $response->body->headers->header2);
 
-        Unirest\Request::timeout(null); // Cleaning timeout for the other tests
+        Unirest\Request::clearDefaultHeaders();
+
+        $response = Unirest\Request::get('http://mockbin.com/request');
+
+        $this->assertEquals(200, $response->code);
+        $this->assertObjectNotHasAttribute('header1', $response->body->headers);
+        $this->assertObjectNotHasAttribute('header2', $response->body->headers);
     }
-*/
 
     public function testDefaultHeader()
     {