Merge pull request #258 from opentok/dev

v4.5.0

Author: dragonmantank

README.md

@@ -53,6 +53,30 @@ use OpenTok\OpenTok;
 $opentok = new OpenTok($apiKey, $apiSecret);
 ```
 
+#### Initialization Options
+
+The `OpenTok\OpenTok` object just allow for some overrides of values when special needs arise, such as
+needing to point to a different datacenter or change the timeout of the underlying HTTP client. For
+these situations, you can pass an array of additional options as the third parameter.
+
+We allow the following options:
+* `apiUrl` - Change the domain that the SDK points to. Useful when needing to select a specific datacenter
+or point to a mock version of the API for testing
+* `client` - Custom API client that inherits from `OpenTok\Utils\Client`, useful for customizing an HTTP client
+* `timeout` - Change the default HTTP timeout, which defaults to forever. You can pass a number of seconds to change the timeout.
+
+```php
+use OpenTok\OpenTok;
+use MyCompany\CustomOpenTokClient;
+
+$options = [
+    'apiUrl' => 'https://custom.domain.com/',
+    'client' => new CustomOpenTokClient(),
+    'timeout' => 10,
+]
+$opentok = new OpenTok($apiKey, $apiSecret, $options);
+```
+
 ### Creating Sessions
 
 To create an OpenTok Session, use the `createSession($options)` method of the

src/OpenTok/OpenTok.php

@@ -41,19 +41,29 @@ class OpenTok {
     public function __construct($apiKey, $apiSecret, $options = array())
     {
         // unpack optional arguments (merging with default values) into named variables
-        $defaults = array('apiUrl' => 'https://api.opentok.com', 'client' => null);
+        $defaults = array(
+            'apiUrl' => 'https://api.opentok.com',
+            'client' => null,
+            'timeout' => null // In the future we should set this to 2
+        );
         $options = array_merge($defaults, array_intersect_key($options, $defaults));
-        list($apiUrl, $client) = array_values($options);
+        list($apiUrl, $client, $timeout) = array_values($options);
 
         // validate arguments
         Validators::validateApiKey($apiKey);
         Validators::validateApiSecret($apiSecret);
         Validators::validateApiUrl($apiUrl);
         Validators::validateClient($client);
+        Validators::validateDefaultTimeout($timeout);
 
         $this->client = isset($client) ? $client : new Client();
         if (!$this->client->isConfigured()) {
-            $this->client->configure($apiKey, $apiSecret, $apiUrl);
+            $this->client->configure(
+                $apiKey,
+                $apiSecret,
+                $apiUrl,
+                ['timeout' => $timeout]
+            );
         }
         $this->apiKey = $apiKey;
         $this->apiSecret = $apiSecret;

src/OpenTok/Util/Client.php

@@ -38,7 +38,7 @@
 
 // TODO: build this dynamically
 /** @internal */
-define('OPENTOK_SDK_VERSION', '4.4.1');
+define('OPENTOK_SDK_VERSION', '4.5.0');
 /** @internal */
 define('OPENTOK_SDK_USER_AGENT', 'OpenTok-PHP-SDK/' . OPENTOK_SDK_VERSION);
 
@@ -57,27 +57,31 @@ public function configure($apiKey, $apiSecret, $apiUrl, $options = array())
         $this->apiKey = $apiKey;
         $this->apiSecret = $apiSecret;
 
+        $clientOptions = [
+            'base_uri' => $apiUrl,
+            'headers' => [
+                'User-Agent' => OPENTOK_SDK_USER_AGENT . ' ' . \GuzzleHttp\default_user_agent(),
+            ],
+        ];
+
+        if (!empty($options['timeout'])) {
+            $clientOptions['timeout'] = $options['timeout'];
+        }
+
         if (empty($options['handler'])) {
             $handlerStack = HandlerStack::create();
         } else {
             $handlerStack = $options['handler'];
         }
+        $clientOptions['handler'] = $handlerStack;
 
         $handler = Middleware::mapRequest(function (RequestInterface $request) {
             $authHeader = $this->createAuthHeader();
             return $request->withHeader('X-OPENTOK-AUTH', $authHeader);
         });
         $handlerStack->push($handler);
 
-        $ua = OPENTOK_SDK_USER_AGENT . ' ' . \GuzzleHttp\default_user_agent();
-        $this->client = new \GuzzleHttp\Client([
-            'base_uri' => $apiUrl,
-            'handler' => $handlerStack,
-            'headers' => [
-                'User-Agent' => $ua
-            ]
-        ]);
-
+        $this->client = new \GuzzleHttp\Client($clientOptions);
         $this->configured = true;
     }
 

src/OpenTok/Util/Validators.php

@@ -310,6 +310,18 @@ public static function validateLayoutClassListItem($layoutClassList)
         }
     }
 
+    public static function validateDefaultTimeout($timeout)
+    {
+        // Guzzle defaults to "null" instead of 0, so allowing that through
+        if (is_null($timeout)) {
+            return;
+        }
+
+        if (!is_numeric($timeout) || ($timeout < 0)) {
+            throw new InvalidArgumentException('Default Timeout must be a number greater than zero');
+        }
+    }
+
     // Helpers
 
     // credit: http://stackoverflow.com/a/173479

tests/OpenTok/ArchiveTest.php

@@ -156,7 +156,7 @@ public function testStopsArchive()
         // TODO: test the dynamically built User Agent string
         $userAgent = $request->getHeaderLine('User-Agent');
         $this->assertNotEmpty($userAgent);
-        $this->assertStringStartsWith('OpenTok-PHP-SDK/4.4.1', $userAgent);
+        $this->assertStringStartsWith('OpenTok-PHP-SDK/4.5.0', $userAgent);
 
         // TODO: test the properties of the actual archive object
         $this->assertEquals('stopped', $this->archive->status);
@@ -195,7 +195,7 @@ public function testDeletesArchive()
         // TODO: test the dynamically built User Agent string
         $userAgent = $request->getHeaderLine('User-Agent');
         $this->assertNotEmpty($userAgent);
-        $this->assertStringStartsWith('OpenTok-PHP-SDK/4.4.1', $userAgent);
+        $this->assertStringStartsWith('OpenTok-PHP-SDK/4.5.0', $userAgent);
 
         $this->assertTrue($success);
         // TODO: assert that all properties of the archive object were cleared