Merge pull request #81 from gabrielzerbib/master

phpdoc return type for ::post

.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

@@ -62,7 +62,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 
@@ -275,7 +275,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(
@@ -290,6 +290,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:

src/Unirest/Request.php

@@ -9,11 +9,13 @@ 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 $socketTimeout = null;
     private static $verifyPeer = true;
+    private static $verifyHost = true;
 
     private static $auth = array (
         'user' => '',
@@ -55,6 +57,16 @@ class Request
         return self::$verifyPeer = $enabled;
     }
     
+    /**
+     * Verify SSL host
+     *
+     * @param bool $enabled enable SSL host verification, by default is true
+     */
+    public static function verifyHost($enabled)
+    {
+        return self::$verifyHost = $enabled;
+    }
+
     /**
      * Set a timeout
      *
@@ -72,11 +84,7 @@ class Request
      */
     public static function defaultHeaders($headers)
     {
-        foreach ($headers as $name => $value) {
+        return array_merge(self::$defaultHeaders, $headers);
-            self::$defaultHeaders[$name] = $value;
-        }
-
-        return $headers;
     }
 
     /**
@@ -90,6 +98,43 @@ class Request
         return self::$defaultHeaders[$name] = $value;
     }
 
+    /**
+     * Clear all the default headers
+     */
+    public static function clearDefaultHeaders()
+    {
+        return self::$defaultHeaders = array();
+    }
+
+    /**
+     * Set curl options to send on every request
+     *
+     * @param array $options options array
+     */
+    public static function curlOpts($opts)
+    {
+        return array_merge(self::$curlOpts, $opts);
+    }
+
+    /**
+     * Set a new default header to send on every request
+     *
+     * @param string $name header name
+     * @param string $value header value
+     */
+    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
@@ -126,14 +171,6 @@ class Request
         self::$cookieFile = $cookieFile;
     }
 
-    /**
-     * Clear all the default headers
-     */
-    public static function clearDefaultHeaders()
-    {
-        return self::$defaultHeaders = array();
-    }
-
     /**
      * Set authentication method to use
      *
@@ -187,7 +224,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)
     {
@@ -201,7 +238,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)
     {
@@ -215,7 +252,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)
     {
@@ -229,7 +266,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)
     {
@@ -243,7 +280,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)
     {
@@ -257,7 +294,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)
     {
@@ -271,7 +308,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)
     {
@@ -285,7 +322,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)
     {
@@ -299,7 +336,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)
     {
@@ -350,6 +387,9 @@ class Request
     {
         self::$handle = curl_init();
 
+        // start with default options
+        curl_setopt_array(self::$handle, self::$curlOpts);
+
         if ($method !== Method::GET) {
             curl_setopt(self::$handle, CURLOPT_CUSTOMREQUEST, $method);
 
@@ -376,6 +416,8 @@ 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 => ''
         ));
@@ -436,9 +478,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()

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,23 +34,11 @@ 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()
-    {
-        Unirest\Request::timeout(3);
-
-        $response = Unirest\Request::get('http://mockbin.com/delay/2000');
-        $this->assertEquals(200, $response->code);
-
-        Unirest\Request::timeout(null); // Cleaning timeout for the other tests
-    }
-*/
-
     public function testDefaultHeader()
     {
         Unirest\Request::defaultHeader('Hello', 'custom');