Added Screenshare type to layout object

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

@@ -22,9 +22,10 @@
 class Layout implements \JsonSerializable
 {
     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';
-    public const LAYOUT_HORIZONTAL = 'horizontalPresentation';
 
     /**
      * Type of layout that we are sending
@@ -33,6 +34,13 @@ class Layout implements \JsonSerializable
      * */
     private $type;
 
+    /**
+     * Type of layout to use for screen sharing
+     * @var string
+     * @ignore
+     */
+    private $screenshareType;
+
     /**
      * Custom stylesheet if our type is 'custom'
      * @var string
@@ -59,14 +67,14 @@ public static function createCustom(array $options): Layout
         // 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 */
@@ -111,6 +119,27 @@ 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();
@@ -134,6 +163,12 @@ public function toArray(): array
         if (isset($this->stylesheet)) {
             $data['stylesheet'] = $this->stylesheet;
         }
+
+        // omit 'screenshareType' property unless it is explicitly defined
+        if (isset($this->screenshareType)) {
+            $data['screenshareType'] = $this->screenshareType;
+        }
+
         return $data;
     }
 }

tests/OpenTokTest/LayoutTest.php

@@ -0,0 +1,61 @@
+<?php
+
+namespace OpenTokTest;
+
+use OpenTok\Layout;
+use PHPStan\Testing\TestCase;
+
+class LayoutTest extends TestCase
+{
+    public function testStylesheetIsNotInSerializedArrayIfNotCustom()
+    {
+        $layouts = [
+            Layout::LAYOUT_BESTFIT => Layout::getBestFit(),
+            Layout::LAYOUT_HORIZONTAL => Layout::getHorizontalPresentation(),
+            Layout::LAYOUT_PIP => Layout::getPIP(),
+            Layout::LAYOUT_VERTICAL => Layout::getVerticalPresentation(),
+        ];
+
+        foreach ($layouts as $type => $object) {
+            $this->assertSame(['type' => $type], $object->toArray());
+        }
+    }
+
+    public function testStylesheetIsInSerializedArrayIfCustom()
+    {
+        $layout = Layout::createCustom(['stylesheet' => 'foo']);
+
+        $this->assertSame(['type' => LAYOUT::LAYOUT_CUSTOM, 'stylesheet' => 'foo'], $layout->toArray());
+    }
+
+    public function testScreenshareTypeSerializesProperly()
+    {
+        $layout = Layout::getBestFit();
+        $layout->setScreenshareType(Layout::LAYOUT_PIP);
+
+        $expected = [
+            'type' => 'bestFit',
+            'screenshareType' => 'pip'
+        ];
+
+        $this->assertSame($expected, $layout->toArray());
+    }
+
+    public function testScreenshareTypeCannotBeSetToInvalidValue()
+    {
+        $this->expectException(\RuntimeException::class);
+        $this->expectExceptionMessage('Screenshare type must be of a valid layout type');
+
+        $layout = Layout::getBestFit();
+        $layout->setScreenshareType('bar');
+    }
+
+    public function testScreenshareTypeCannotBeSetOnInvalidLayoutType()
+    {
+        $this->expectException(\RuntimeException::class);
+        $this->expectExceptionMessage('Screenshare type cannot be set on a layout type other than bestFit');
+
+        $layout = Layout::createCustom(['stylesheet' => 'foo']);
+        $layout->setScreenshareType(Layout::LAYOUT_PIP);
+    }
+}