Merge pull request #282 from opentok/feature/devx-4270-archive-layout-options

Adding Screenshare Layout options

Author: dragonmantank

README.md

@@ -317,7 +317,7 @@ You can set change the layout dynamically, using the
 ```php
 use OpenTok\OpenTok;
 
-$layout Layout::getPIP(); // Or use another get method of the Layout class.
+$layout = Layout::getPIP(); // Or use another get method of the Layout class.
 $opentok->updateBroadcastLayout($broadcastId, $layout);
 ```
 
@@ -338,6 +338,13 @@ $layoutType = Layout::createCustom($options);
 $opentok->setArchiveLayout($archiveId, $layoutType);
 ```
 
+You can also set the Screenshare Layout by calling the `setScreenshareType()` method on a layout object.
+
+```php
+$layout = Layout::getBestFit(); // Other types are not currently supported
+$layout->setScreenshareType(Layout::LAYOUT_VERTICAL);
+```
+
 You can set the initial layout class for a client's streams by setting the `layout` option when
 you create the token for the client, using the `OpenTok->generateToken()` method or the
 `Session->generateToken()` method. And you can change the layout classes for a stream

src/OpenTok/Layout.php

@@ -19,61 +19,40 @@
  * <a href="https://tokbox.com/developer/guides/broadcast/live-streaming/#configuring-video-layout-for-opentok-live-streaming-broadcasts">Configuring
  * video layout for OpenTok live streaming broadcasts</a>.
  */
-class Layout
+class Layout implements \JsonSerializable
 {
-    // NOTE: after PHP 5.3.0 support is dropped, the class can implement JsonSerializable
-
-    /** @ignore */
-    private static $bestFit;
-    /** @ignore */
-    private static $pip;
-    /** @ignore */
-    private static $verticalPresentation;
-    /** @ignore */
-    private static $horizontalPresentation;
+    public const LAYOUT_BESTFIT = 'bestFit';
+    public const LAYOUT_CUSTOM = 'custom';
+    public const LAYOUT_HORIZONTAL = 'horizontalPresentation';
+    public const LAYOUT_PIP = 'pip';
+    public const LAYOUT_VERTICAL = 'verticalPresentation';
 
     /**
-     * Returns a Layout object defining the "best fit" predefined layout type.
-     */
-    public static function getBestFit()
-    {
-        if (is_null(self::$bestFit)) {
-            self::$bestFit = new Layout('bestFit');
-        }
-        return self::$bestFit;
-    }
+     * Type of layout that we are sending
+     * @var string
+     * @ignore
+     * */
+    private $type;
 
     /**
-     * Returns a Layout object defining the "picture-in-picture" predefined layout type.
+     * Type of layout to use for screen sharing
+     * @var string
+     * @ignore
      */
-    public static function getPIP()
-    {
-        if (is_null(self::$pip)) {
-            self::$pip = new Layout('pip');
-        }
-        return self::$pip;
-    }
+    private $screenshareType;
 
     /**
-     * Returns a Layout object defining the "vertical presentation" predefined layout type.
+     * Custom stylesheet if our type is 'custom'
+     * @var string
+     * @ignore
      */
-    public static function getVerticalPresentation()
-    {
-        if (is_null(self::$verticalPresentation)) {
-            self::$verticalPresentation = new Layout('verticalPresentation');
-        }
-        return self::$verticalPresentation;
-    }
+    private $stylesheet;
 
-    /**
-     * Returns a Layout object defining the "horizontal presentation" predefined layout type.
-     */
-    public static function getHorizontalPresentation()
+    /** @ignore */
+    private function __construct(string $type, ?string $stylesheet = null)
     {
-        if (is_null(self::$horizontalPresentation)) {
-            self::$horizontalPresentation = new Layout('horizontalPresentation');
-        }
-        return self::$horizontalPresentation;
+        $this->type = $type;
+        $this->stylesheet = $stylesheet;
     }
 
     /**
@@ -82,45 +61,99 @@ public static function getHorizontalPresentation()
      * @param array $options An array containing one property: <code>$stylesheet<code>,
      * which is a string containing the stylesheet to be used for the layout.
      */
-    public static function createCustom($options)
+    public static function createCustom(array $options): Layout
     {
         // 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);
+        $defaults = ['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);
+        return new Layout(static::LAYOUT_CUSTOM, $stylesheet);
     }
 
     /** @ignore */
-    public static function fromData($layoutData)
+    public static function fromData(array $layoutData): Layout
     {
         if (array_key_exists('stylesheet', $layoutData)) {
             return new Layout($layoutData['type'], $layoutData['stylesheet']);
-        } else {
-            return new Layout($layoutData['type']);
         }
+
+        return new Layout($layoutData['type']);
     }
 
-    /** @ignore */
-    private $type;
-    /** @ignore */
-    private $stylesheet;
+    /**
+     * Returns a Layout object defining the "best fit" predefined layout type.
+     */
+    public static function getBestFit(): Layout
+    {
+        return new Layout(static::LAYOUT_BESTFIT);
+    }
 
-    /** @ignore */
-    private function __construct($type, $stylesheet = null)
+    /**
+     * Returns a Layout object defining the "picture-in-picture" predefined layout type.
+     */
+    public static function getPIP(): Layout
     {
-        $this->type = $type;
-        $this->stylesheet = $stylesheet;
+        return new Layout(static::LAYOUT_PIP);
+    }
+
+    /**
+     * Returns a Layout object defining the "vertical presentation" predefined layout type.
+     */
+    public static function getVerticalPresentation(): Layout
+    {
+        return new Layout(static::LAYOUT_VERTICAL);
+    }
+
+    /**
+     * Returns a Layout object defining the "horizontal presentation" predefined layout type.
+     */
+    public static function getHorizontalPresentation(): Layout
+    {
+        return new Layout(static::LAYOUT_HORIZONTAL);
+    }
+
+    public function setScreenshareType(string $screenshareType): Layout
+    {
+        if ($this->type === Layout::LAYOUT_BESTFIT) {
+            $layouts = [
+                Layout::LAYOUT_BESTFIT,
+                Layout::LAYOUT_HORIZONTAL,
+                Layout::LAYOUT_PIP,
+                Layout::LAYOUT_VERTICAL
+            ];
+
+            if (!in_array($screenshareType, $layouts)) {
+                throw new \RuntimeException('Screenshare type must be of a valid layout type');
+            }
+
+            $this->screenshareType = $screenshareType;
+            return $this;
+        }
+
+        throw new \RuntimeException('Screenshare type cannot be set on a layout type other than bestFit');
     }
 
     public function jsonSerialize()
+    {
+        return $this->toArray();
+    }
+
+    /**
+     * Return a json-encoded string representation of the layout
+     */
+    public function toJson(): string
+    {
+        return json_encode($this->jsonSerialize());
+    }
+
+    public function toArray(): array
     {
         $data = array(
             'type' => $this->type
@@ -130,11 +163,12 @@ public function jsonSerialize()
         if (isset($this->stylesheet)) {
             $data['stylesheet'] = $this->stylesheet;
         }
-        return $data;
-    }
 
-    public function toJson()
-    {
-        return json_encode($this->jsonSerialize());
+        // omit 'screenshareType' property unless it is explicitly defined
+        if (isset($this->screenshareType)) {
+            $data['screenshareType'] = $this->screenshareType;
+        }
+
+        return $data;
     }
 }

src/OpenTok/OpenTok.php

@@ -2,10 +2,11 @@
 
 namespace OpenTok;
 
+use OpenTok\Layout;
 use OpenTok\Util\Client;
 use OpenTok\Util\Validators;
-use OpenTok\Exception\UnexpectedValueException;
 use OpenTok\Exception\InvalidArgumentException;
+use OpenTok\Exception\UnexpectedValueException;
 
 /**
 * Contains methods for creating OpenTok sessions, generating tokens, and working with archives.
@@ -296,13 +297,17 @@ public function createSession($options = array())
      * @return Archive The Archive object, which includes properties defining the archive, including
      * the archive ID.
      */
-    public function startArchive($sessionId, $options = array())
+    public function startArchive(string $sessionId, $options = []): Archive
     {
         // support for deprecated method signature, remove in v3.0.0 (not before)
         if (!is_array($options)) {
+            trigger_error(
+                'Archive options passed as a string is deprecated, please pass an array with a name key',
+                E_USER_DEPRECATED
+            );
             $options = array('name' => $options);
         }
-        
+
         // unpack optional arguments (merging with default values) into named variables
         $defaults = array(
             'name' => null,
@@ -425,17 +430,11 @@ public function listArchives($offset = 0, $count = null, $sessionId = null)
 
     /**
      * Updates the stream layout in an OpenTok Archive.
-     *
-     * @param string $archiveId The OpenTok archive ID.
-     *
-     * @param string $layout The connectionId of the connection in a session.
      */
-
-    public function setArchiveLayout($archiveId, $layoutType)
+    public function setArchiveLayout(string $archiveId, Layout $layoutType): void
     {
         Validators::validateArchiveId($archiveId);
-        Validators::validateLayout($layoutType);
-        
+
         $this->client->setArchiveLayout($archiveId, $layoutType);
     }
 
@@ -497,7 +496,7 @@ public function forceDisconnect($sessionId, $connectionId)
      *
      * @return Broadcast An object with properties defining the broadcast.
      */
-    public function startBroadcast($sessionId, $options = array())
+    public function startBroadcast(string $sessionId, array $options = []): Broadcast
     {
         // unpack optional arguments (merging with default values) into named variables
         // NOTE: although the server can be authoritative about the default value of layout, its
@@ -571,14 +570,9 @@ public function getBroadcast($broadcastId)
      *
      * @param Layout $layout An object defining the layout type for the broadcast.
      */
-    public function updateBroadcastLayout($broadcastId, $layout)
+    public function updateBroadcastLayout(string $broadcastId, Layout $layout): void
     {
         Validators::validateBroadcastId($broadcastId);
-        Validators::validateLayout($layout);
-
-        // TODO: platform implementation does not meet API Review spec
-        // $layoutData = $this->client->updateLayout($broadcastId, $layout, 'broadcast');
-        // return Layout::fromData($layoutData);
 
         $this->client->updateLayout($broadcastId, $layout, 'broadcast');
     }