Let merchant override cURL options

README.md

@@ -1,6 +1,6 @@
 # Scanpay PHP Client
 
-PHP client library for the Scanpay API. You can always e-mail us at [help@scanpay.dk](mailto:help@scanpay.dk) or chat with us on IRC: `irc.scanpay.dk:6697` or `#scanpay` at Freenode ([webchat](https://webchat.freenode.net?randomnick=1&channels=scanpay&prompt=1))
+PHP client library for the Scanpay API. You can always e-mail us at [help@scanpay.dk](mailto:help@scanpay.dk) or chat with us on `irc.scanpay.dk:6697` or `#scanpay` at Freenode ([webchat](https://webchat.freenode.net?randomnick=1&channels=scanpay&prompt=1))
 
 ## Installation
 
@@ -15,7 +15,7 @@ And initiate it in your project with:
 $scanpay = new Scanpay\Scanpay(' API-key ');
 ```
 
-### Manual install
+### Manual installation
 
 If you do not wish to use Composer, you can download the [latest release](https://github.com/scanpaydk/php-scanpay/releases) and include in into your project:
 
@@ -26,14 +26,9 @@ $scanpay = new Scanpay\Scanpay(' API-key ');
 
 ## Methods
 
-All methods, except `handlePing`, accept an optional per-request `options` object. You can use this to:
-
-* Set the API key for this request ([example](tests/newURL.php#L14))
-* Set HTTP headers, e.g. the highly recommended `X-Cardholder-IP` ([example](tests/newURL.php#L15))
-* Change the hostname to use our test environment `api.test.scanpay.dk` ([example](tests/newURL.php#L12))
-* Enable debugging mode ([example](tests/newURL.php#L17))
+Please note that all methods accept an optional per-request `options` object. You can read more about this [here](#options).
 
-### newURL(Object, Object)
+#### newURL(Object, Object)
 
 Create a payment link by passing the order details ([spec](https://docs.scanpay.dk/payment-link#request-fields)) through `newURL`:
 
@@ -42,15 +37,14 @@ $order = [
     'items' => [
         [
             'name'     => 'Pink Floyd: The Dark Side Of The Moon',
-            'quantity' => 2,
             'total'    => '199.99 DKK'
         ]
     ]
 ];
 print_r ($URL = $scanpay->newURL($order, $options)); // returns String
 ```
 
-### seq(Int, Object)
+#### seq(Int, Object)
 
 Get an array with a number of changes since the supplied sequence number:
 
@@ -61,7 +55,7 @@ print_r (obj.changes);
 print_r ('New local seq after applying all changes: ' . obj.seq);
 ```
 
-### handlePing(Object)
+#### handlePing(Object)
 
 Securely and efficiently validate pings. This method accepts an optional object with the following arguments:
 
@@ -74,6 +68,16 @@ print_r ($json = $scanpay->handlePing());
 print_r ($json.seq);
 ```
 
+## Options
+
+All methods, except `handlePing`, accept an optional per-request `options` object. You can use this to:
+
+* Set the API key for this request ([example](tests/newURL.php#L14))
+* Set HTTP headers, e.g. the highly recommended `X-Cardholder-IP` ([example](tests/newURL.php#L15))
+* Change the hostname to use our test environment `api.test.scanpay.dk` ([example](tests/newURL.php#L12))
+* Enable debugging mode ([example](tests/seq.php#L13))
+* Override cURL options with [`CURLOPT_*`](http://php.net/manual/en/function.curl-setopt.php) parameters ([example](tests/newURL.php#L17-L21)).
+
 ## Compatibility table
 
 | Feature                                   | Version |

lib/Scanpay.php

@@ -12,20 +12,9 @@ public function __construct($apikey = '') {
 
         // Public cURL handle (we want to reuse connections)
         $this->ch = curl_init();
-        curl_setopt_array($this->ch, [
-            CURLOPT_RETURNTRANSFER => 1,
-            CURLOPT_CONNECTTIMEOUT => 20,
-            CURLOPT_TIMEOUT => 20,
-            CURLOPT_USE_SSL => CURLUSESSL_ALL,
-            CURLOPT_SSLVERSION => 6, // TLSv1.2
-        ]);
-        // TODO: Expose CURLOPT
-        // curl_setopt($this->ch, CURLOPT_TCP_FASTOPEN, 1);
-        // curl_setopt($this->ch, CURLOPT_SSL_FALSESTART, 1);
-
         $this->headers = [
             'Authorization' => 'Basic ' . base64_encode($apikey),
-            'X-SDK' => 'PHP-1.3.0/'. PHP_VERSION,
+            'X-SDK' => 'PHP-1.3.1/'. PHP_VERSION,
             'Content-Type' => 'application/json',
             'Expect' => '', // Prevent 'Expect: 100-continue' on POSTs >1024b.
         ];
@@ -51,14 +40,23 @@ protected function httpHeaders($o=[]) {
 
     protected function request($path, $opts=[], $data=null) {
         $hostname = (isset($opts['hostname'])) ? $opts['hostname'] : 'api.scanpay.dk';
-
-        curl_setopt_array($this->ch, [
+        $curlopts = [
             CURLOPT_URL => 'https://' . $hostname . $path,
             CURLOPT_HTTPHEADER => $this->httpHeaders($opts),
             CURLOPT_CUSTOMREQUEST => ($data === null) ? 'GET' : 'POST',
             CURLOPT_POSTFIELDS => ($data === null) ? null : json_encode($data, JSON_UNESCAPED_SLASHES),
             CURLOPT_VERBOSE => isset($opts['debug']) ? $opts['debug'] : 0,
-        ]);
+            CURLOPT_RETURNTRANSFER => 1,
+            CURLOPT_CONNECTTIMEOUT => 20,
+            CURLOPT_TIMEOUT => 20,
+            CURLOPT_USE_SSL => CURLUSESSL_ALL,
+            CURLOPT_SSLVERSION => 6, // TLSv1.2
+        ];
+        // Let the merchant override $curlopts.
+        if (isset($opts['curl'])) {
+            foreach($opts['curl'] as $key => &$val) { $curlopts[$key] = $val; }
+        }
+        curl_setopt_array($this->ch, $curlopts);
 
         $result = curl_exec($this->ch);
         if (!$result) {

tests/newURL.php

@@ -14,13 +14,17 @@
         'Authorization' => 'Basic ' . base64_encode($apikey),
         'X-Cardholder-IP' => '192.168.1.1',
     ],
-    //'debug' => true,
+    'curl' => [
+        CURLOPT_TIMEOUT => 10,
+        CURLOPT_SSL_FALSESTART => 1,
+        CURLOPT_TCP_FASTOPEN => 1,
+    ],
 ];
 
 $order = [
     'orderid'    => 'a766409',
     'language'   => 'da',
-    'successurl' => 'https://insertyoursuccesspage.dk',
+    'successurl' => 'https://docs.scanpay.dk/payment-link',
     'items'    => [
         [
             'name'     => 'Pink Floyd: The Dark Side Of The Moon',