Merge pull request #290 from montymxb/transport-layers

Adds switchable http clients with configuration options

Author: Benjamin Wilson Friedman

README.md

@@ -40,7 +40,7 @@ require 'autoload.php';
 Initialization
 ---------------
 
-After including the required files from the SDK, you need to initalize the ParseClient using your Parse API keys:
+After including the required files from the SDK, you need to initialize the ParseClient using your Parse API keys:
 
 ```php
 ParseClient::initialize( $app_id, $rest_key, $master_key );
@@ -63,6 +63,43 @@ For example if your parse server's url is `http://example.com:1337/parse` then y
 
 `ParseClient::setServerURL('https://example.com:1337','parse');`
 
+
+Http Clients
+------------
+
+This SDK has the ability to change the underlying http client at your convenience.
+The default is to use the curl http client if none is set, there is also a stream http client that can be used as well.
+
+Setting the http client can be done as follows:
+```php
+// set curl http client (default if none set)
+ParseClient::setHttpClient(new ParseCurlHttpClient());
+
+// set stream http client
+// ** requires 'allow_url_fopen' to be enabled in php.ini ** 
+ParseClient::setHttpClient(new ParseStreamHttpClient());
+```
+
+If you have a need for an additional http client you can request one by opening an issue or by submitting a PR.
+
+If you wish to build one yourself make sure your http client implements ```ParseHttpable``` for it be compatible with the SDK. Once you have a working http client that enhances the SDK feel free to submit it in a PR so we can look into adding it in.
+
+
+Alternate Certificate Authority File
+------------------------------------
+
+It is possible that your local setup may not be able to verify with peers over SSL/TLS. This may especially be the case if you do not have control over your local installation, such as for shared hosting.
+
+If this is the case you may need to specify a Certificate Authority bundle. You can download such a bundle from (http://curl.haxx.se/ca/cacert.pem)[http://curl.haxx.se/ca/cacert.pem] to use for this purpose. This one happens to be a Mozilla CA certificate store, you don't necessarily have to use this one but it's recommended.
+
+Once you have your bundle you can set it as follows:
+```php
+// ** Use an Absolute path for your file! **
+// holds one or more certificates to verify the peer with
+ParseClient::setCAFile(__DIR__ . '/certs/cacert.pem');
+```
+
+
 Usage
 -----
 

src/Parse/HttpClients/ParseCurl.php

@@ -0,0 +1,158 @@
+<?php
+/**
+ * ParseCurl - Wrapper for abstracted curl usage
+ *
+ * @author Ben Friedman <ben@axolsoft.com>
+ */
+
+namespace Parse\HttpClients;
+
+
+use Parse\ParseException;
+
+/**
+ * Class ParseCurl
+ * @package Parse\HttpClients
+ */
+class ParseCurl
+{
+    /**
+     * Curl handle
+     * @var resource
+     */
+    private $curl;
+
+    /**
+     * Sets up a new curl instance internally if needed
+     */
+    public function init()
+    {
+        if($this->curl === null) {
+            $this->curl = curl_init();
+
+        }
+
+    }
+
+    /**
+     * Executes this curl request
+     *
+     * @return mixed
+     * @throws ParseException
+     */
+    public function exec()
+    {
+        if(!isset($this->curl)) {
+            throw new ParseException('You must call ParseCurl::init first');
+
+        }
+
+        return curl_exec($this->curl);
+    }
+
+    /**
+     * Sets a curl option
+     *
+     * @param int   $option Option to set
+     * @param mixed $value  Value to set for this option
+     * @throws ParseException
+     */
+    public function setOption($option, $value)
+    {
+        if(!isset($this->curl)) {
+            throw new ParseException('You must call ParseCurl::init first');
+
+        }
+
+        curl_setopt($this->curl, $option, $value);
+
+    }
+
+    /**
+     * Sets multiple curl options
+     *
+     * @param array $options    Array of options to set
+     * @throws ParseException
+     */
+    public function setOptionsArray($options)
+    {
+        if(!isset($this->curl)) {
+            throw new ParseException('You must call ParseCurl::init first');
+
+        }
+
+        curl_setopt_array($this->curl, $options);
+
+    }
+
+    /**
+     * Gets info for this curl handle
+     *
+     * @param int $info Constatnt for info to get
+     * @return mixed
+     * @throws ParseException
+     */
+    public function getInfo($info)
+    {
+        if(!isset($this->curl)) {
+            throw new ParseException('You must call ParseCurl::init first');
+
+        }
+
+        return curl_getinfo($this->curl, $info);
+
+    }
+
+    /**
+     * Gets the curl error message
+     *
+     * @return string
+     * @throws ParseException
+     */
+    public function getError()
+    {
+        if(!isset($this->curl)) {
+            throw new ParseException('You must call ParseCurl::init first');
+
+        }
+
+        return curl_error($this->curl);
+
+    }
+
+    /**
+     * Gets the curl error code
+     *
+     * @return int
+     * @throws ParseException
+     */
+    public function getErrorCode()
+    {
+        if(!isset($this->curl)) {
+            throw new ParseException('You must call ParseCurl::init first');
+
+        }
+
+        return curl_errno($this->curl);
+
+    }
+
+    /**
+     * Closed our curl handle and disposes of it
+     */
+    public function close()
+    {
+        if(!isset($this->curl)) {
+            throw new ParseException('You must call ParseCurl::init first');
+
+        }
+
+        // close our handle
+        curl_close($this->curl);
+
+        // unset our curl handle
+        $this->curl = null;
+
+    }
+
+}