Merge branch 'master' into bklima-ss-patch-1

Author: aiham

README.md

@@ -16,7 +16,7 @@ Add this package (`opentok/opentok`) to your `composer.json` file, or just run t
 command line:
 
 ```
-$ ./composer.phar require opentok/opentok 2.3.x
+$ ./composer.phar require opentok/opentok 2.4.x
 ```
 
 ## Manually:
@@ -52,7 +52,7 @@ $opentok = new OpenTok($apiKey, $apiSecret);
 To create an OpenTok Session, use the `createSession($options)` method of the
 `OpenTok\OpenTok` class. The `$options` parameter is an optional array used to specify the following:
 
-* Setting whether the session will use the OpenTok Media Router or attempt send streams directly
+* Setting whether the session will use the OpenTok Media Router or attempt to send streams directly
   between clients.
 
 * Setting whether the session will automatically create archives (implies use of routed session)
@@ -141,7 +141,7 @@ $archive = $opentok->startArchive($sessionId, $archiveOptions);
 $archiveId = $archive->id;
 ```
 
-Setting the output mode to `OutputMode::INDIVIDUAL` setting causes each stream in the archive to be recorded to its own individual file. The `OutputMode::COMPOSED` setting (the default) causes all streams in the archive are recorded to a single (composed) file.
+Setting the output mode to `OutputMode::INDIVIDUAL` setting causes each stream in the archive to be recorded to its own individual file. The `OutputMode::COMPOSED` setting (the default) causes all streams in the archive to be recorded to a single (composed) file.
 
 You can stop the recording of a started Archive using the `stopArchive($archiveId)` method of the
 `OpenTok\OpenTok` object. You can also do this using the `stop()` method of the

composer.json

@@ -35,7 +35,7 @@
     },
     "require-dev": {
         "phpunit/phpunit": "~4.1",
-        "phing/phing": "dev-master"
+        "phing/phing": "~2.15.2"
     },
     "autoload": {
         "psr-4": {

sample/SipCall/README.md

@@ -27,8 +27,7 @@ Finally, start the PHP CLI development server (requires PHP >= 5.4) using the `r
 $ ./run-demo
 ```
 
-Visit <http://localhost:8080> in your browser. Open it again in a second window. Smile! You've just
-set up a group chat. You can
+Visit <http://localhost:8080> in your browser.
 
 ## Walkthrough
 

src/OpenTok/Archive.php

@@ -38,9 +38,8 @@
 * The API key associated with the archive.
 *
 * @property string $reason
-* For archives with the status "stopped", this can be set to "maximum duration
-* exceeded", "maximum idle time exceeded", "session ended", "user initiated". For archives with
-* the status "failed", this can be set to "failure".
+* For archives with the status "stopped" or "failed", this string describes the reason
+* the archive stopped (such as "maximum duration exceeded") or failed.
 *
 * @property string $sessionId
 * The session ID of the OpenTok session associated with this archive.
@@ -76,6 +75,7 @@
 * 10 minutes. To generate a new URL, call the Archive.listArchives() or OpenTok.getArchive() method.
 */
 class Archive {
+    // NOTE: after PHP 5.3.0 support is dropped, the class can implement JsonSerializable
 
     /** @internal */
     private $data;
@@ -196,16 +196,23 @@ public function delete()
      */
     public function toJson()
     {
-        return json_encode($this->data);
+        return json_encode($this->jsonSerialize());
     }
 
     /**
      * Returns an associative array representation of this Archive object.
+     * @deprecated 3.0.0 A more standard name for this method is supplied by JsonSerializable
+     * @see Archive::jsonSerialize() for a method with the same behavior
      */
     public function toArray()
     {
         return $this->data;
     }
+
+    public function jsonSerialize()
+    {
+        return $this->data;
+    }
 }
 
 /* vim: set ts=4 sw=4 tw=100 sts=4 et :*/

src/OpenTok/Broadcast.php

@@ -0,0 +1,110 @@
+<?php
+
+namespace OpenTok;
+
+use OpenTok\Exception\BroadcastDomainException;
+use OpenTok\Exception\BroadcastUnexpectedValueException;
+use OpenTok\Util\Validators;
+
+class Broadcast {
+    // NOTE: after PHP 5.3.0 support is dropped, the class can implement JsonSerializable
+
+    private $data;
+    private $isStopped = false;
+    private $client;
+
+    public function __construct($broadcastData, $options = array()) {
+        // unpack optional arguments (merging with default values) into named variables
+        $defaults = array(
+            'apiKey' => null,
+            'apiSecret' => null,
+            'apiUrl' => 'https://api.opentok.com',
+            'client' => null,
+            'isStopped' => false
+        );
+        $options = array_merge($defaults, array_intersect_key($options, $defaults));
+        list($apiKey, $apiSecret, $apiUrl, $client, $isStopped) = array_values($options);
+
+        // validate params
+        Validators::validateBroadcastData($broadcastData);
+        Validators::validateClient($client);
+
+        $this->data = $broadcastData;
+
+        $this->isStopped = $isStopped;
+
+        $this->client = isset($client) ? $client : new Client();
+        if (!$this->client->isConfigured()) {
+            Validators::validateApiKey($apiKey);
+            Validators::validateApiSecret($apiSecret);
+            Validators::validateApiUrl($apiUrl);
+
+            $this->client->configure($apiKey, $apiSecret, $apiUrl);
+        }
+    }
+
+    public function __get($name)
+    {
+        switch ($name) {
+            case 'createdAt':
+            case 'updatedAt':
+            case 'id':
+            case 'partnerId':
+            case 'sessionId':
+            case 'broadcastUrls':
+                return $this->data[$name];
+                break;
+            case 'hlsUrl':
+                return $this->data['broadcastUrls']['hls'];
+                break;
+            case 'isStopped':
+                return $this->isStopped;
+                break;
+            default:
+                return null;
+        }
+    }
+
+    public function stop()
+    {
+        if ($this->isStopped) {
+            throw new BroadcastDomainException(
+                'You cannot stop a broadcast which is already stopped.'
+            );
+        }
+
+        $broadcastData = $this->client->stopBroadcast($this->data['id']);
+
+        try {
+            Validators::validateBroadcastData($broadcastData);
+        } catch (InvalidArgumentException $e) {
+            throw new BroadcastUnexpectedValueException('The broadcast JSON returned after stopping was not valid', null, $e);
+        }
+
+        $this->data = $broadcastData;
+        return $this;
+    }
+
+    // TODO: not yet implemented by the platform
+    // public function getLayout()
+    // {
+    //     $layoutData = $this->client->getLayout($this->id, 'broadcast');
+    //     return Layout::fromData($layoutData);
+    // }
+
+    public function updateLayout($layout)
+    {
+        Validators::validateLayout($layout);
+
+        // TODO: platform implementation did not meet API review spec
+        // $layoutData = $this->client->updateLayout($this->id, $layout, 'broadcast');
+        // return Layout::fromData($layoutData);
+
+        $this->client->updateLayout($this->id, $layout, 'broadcast');
+    }
+
+    public function jsonSerialize()
+    {
+        return $this->data;
+    }
+}

src/OpenTok/Exception/BroadcastAuthenticationException.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace OpenTok\Exception;
+
+/**
+ * Defines the exception thrown when you use an invalid API or secret and call a broadcast method.
+ */
+class BroadcastAuthenticationException extends \OpenTok\Exception\AuthenticationException implements \OpenTok\Exception\BroadcastException
+{
+}
+/* vim: set ts=4 sw=4 tw=100 sts=4 et :*/

src/OpenTok/Exception/BroadcastDomainException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace OpenTok\Exception;
+
+// TODO: this kind of exception has a detailed message from the HTTP response, use it.
+/**
+* Defines an exception thrown when a call to a broadcast method results in an error response from
+* the server.
+*/
+class BroadcastDomainException extends \OpenTok\Exception\DomainException implements \OpenTok\Exception\BroadcastException
+{
+}
+/* vim: set ts=4 sw=4 tw=100 sts=4 et :*/

src/OpenTok/Exception/BroadcastException.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace OpenTok\Exception;
+
+/**
+* The interface used by all exceptions resulting from calls to the broadcast API.
+*/
+interface BroadcastException
+{
+}
+/* vim: set ts=4 sw=4 tw=100 sts=4 et :*/

src/OpenTok/Exception/BroadcastUnexpectedValueException.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace OpenTok\Exception;
+
+/**
+* Defines an exception thrown when a call to a broadcast method results in an error due to an
+* unexpected value.
+*/
+class BroadcastUnexpectedValueException extends \OpenTok\Exception\UnexpectedValueException implements \OpenTok\Exception\BroadcastException
+{
+}
+/* vim: set ts=4 sw=4 tw=100 sts=4 et :*/

src/OpenTok/Layout.php

@@ -0,0 +1,98 @@
+<?php
+
+namespace OpenTok;
+
+use OpenTok\Util\Validators;
+
+class Layout {
+    // NOTE: after PHP 5.3.0 support is dropped, the class can implement JsonSerializable
+
+    private static $bestFit = null;
+    private static $pip = null;
+    private static $verticalPresentation = null;
+    private static $horizontalPresentaton = null;
+
+    public static function getBestFit()
+    {
+        if (is_null(self::$bestFit)) {
+            self::$bestFit = new Layout('bestFit');
+        }
+        return self::$bestFit;
+    }
+
+    public static function getPIP()
+    {
+        if (is_null(self::$pip)) {
+            self::$pip = new Layout('pip');
+        }
+        return self::$pip;
+    }
+
+    public static function getVerticalPresentation()
+    {
+        if (is_null(self::$verticalPresentation)) {
+            self::$verticalPresentation = new Layout('verticalPresentation');
+        }
+        return self::$verticalPresentation;
+    }
+
+    public static function getHorizontalPresentation()
+    {
+        if (is_null(self::$horizontalPresentaton)) {
+            self::$horizontalPresentaton = new Layout('horizontalPresentaton');
+        }
+        return self::$horizontalPresentaton;
+    }
+
+    public static function createCustom($options)
+    {
+        // unpack optional arguments (merging with default values) into named variables
+        // NOTE: the default value of stylesheet=null will not pass validation, this essentially
+        //       means that stylesheet is not optional. its still purposely left as part of the
+        //       $options argument so that it can become truly optional in the future.
+        $defaults = array('stylesheet' => null);
+        $options = array_merge($defaults, array_intersect_key($options, $defaults));
+        list($stylesheet) = array_values($options);
+
+        // validate arguments
+        Validators::validateLayoutStylesheet($stylesheet);
+
+        return new Layout('custom', $stylesheet);
+    }
+
+
+    public static function fromData($layoutData)
+    {
+        if (array_key_exists('stylesheet', $layoutData)) {
+            return new Layout($layoutData['type'], $layoutData['stylesheet']);
+        } else {
+            return new Layout($layoutData['type']);
+        }
+    }
+
+    private $type;
+    private $stylesheet;
+
+    private function __construct($type, $stylesheet = null)
+    {
+        $this->type = $type;
+        $this->stylesheet = $stylesheet;
+    }
+
+    public function jsonSerialize() {
+        $data = array(
+            'type' => $this->type
+        );
+
+        // omit 'stylesheet' property unless it is explicitly defined
+        if (isset($this->stylesheet)) {
+            $data['stylesheet'] = $this->stylesheet;
+        }
+        return $data;
+    }
+
+    public function toJson()
+    {
+        return json_encode($this->jsonSerialize());
+    }
+}