Implement breakout rooms groups in create API (#155)

* Implement breakout rooms groups in create API

* Code cleanup, add comments, type hints

* Fix cs

* Fixed missing type hints

* Fixed CS

---------

Co-authored-by: Felix Jacobi <felix@jacobi-hamburg.net>

Author: samuelwei

src/Core/Meeting.php

@@ -61,12 +61,12 @@ class Meeting
     private $dialNumber;
 
     /**
-     * @var string
+     * @var string|null
      */
     private $attendeePassword;
 
     /**
-     * @var string
+     * @var string|null
      */
     private $moderatorPassword;
 

src/Parameters/CreateMeetingParameters.php

@@ -373,6 +373,11 @@ class CreateMeetingParameters extends MetaParameters
      */
     protected $userCameraCap;
 
+    /**
+     * @var array<array{id: string, name: string|null, roster: array}>
+     */
+    private $breakoutRoomsGroups = [];
+
     /**
      * @var array
      */
@@ -487,6 +492,24 @@ public function addPresentation(string $nameOrUrl, string $content = null, strin
         return $this;
     }
 
+    /**
+     * @return array<array{id: string, name: string|null, roster: array}>
+     */
+    public function getBreakoutRoomsGroups(): array
+    {
+        return $this->breakoutRoomsGroups;
+    }
+
+    /**
+     * @return $this
+     */
+    public function addBreakoutRoomsGroup(string $id, ?string $name, array $roster): self
+    {
+        $this->breakoutRoomsGroups[] = ['id' => $id, 'name' => $name, 'roster' => $roster];
+
+        return $this;
+    }
+
     public function getPresentations(): array
     {
         return $this->presentations;
@@ -524,6 +547,13 @@ public function getHTTPQuery(): string
     {
         $queries = $this->getHTTPQueryArray();
 
+        // Pre-defined groups to automatically assign the students to a given breakout room
+        if (!empty($this->breakoutRoomsGroups)) {
+            $queries = array_merge($queries, [
+                'groups' => json_encode($this->breakoutRoomsGroups),
+            ]);
+        }
+
         if ($this->isBreakout()) {
             if ($this->parentMeetingID === null || $this->sequence === null) {
                 throw new \RuntimeException('Breakout rooms require a parentMeetingID and sequence number.');

tests/TestCase.php

@@ -120,9 +120,24 @@ protected function generateCreateParams()
             'allowRequestsWithoutSession' => $this->faker->boolean(50),
             'virtualBackgroundsDisabled' => $this->faker->boolean(50),
             'userCameraCap' => $this->faker->numberBetween(1, 5),
+            'groups' => $this->generateBreakoutRoomsGroups(),
         ];
     }
 
+    /**
+     * @return array<array{id: string, name: string, roster: array}>
+     */
+    protected function generateBreakoutRoomsGroups(): array
+    {
+        $br = $this->faker->numberBetween(0, 8);
+        $groups = [];
+        for ($i = 0; $i <= $br; ++$i) {
+            $groups[] = ['id' => $this->faker->uuid, 'name' => $this->faker->name, 'roster' => $this->faker->randomElements];
+        }
+
+        return $groups;
+    }
+
     /**
      * @return array
      */
@@ -145,6 +160,10 @@ protected function getCreateMock($params)
     {
         $createMeetingParams = new CreateMeetingParameters($params['meetingID'], $params['name']);
 
+        foreach ($params['groups'] as $group) {
+            $createMeetingParams->addBreakoutRoomsGroup($group['id'], $group['name'], $group['roster']);
+        }
+
         return $createMeetingParams->setAttendeePW($params['attendeePW'])
             ->setModeratorPW($params['moderatorPW'])
             ->setDialNumber($params['dialNumber'])
@@ -339,4 +358,19 @@ public function assertEachGetterValueIsBoolean($obj, $getters)
             $this->assertIsBool($obj->$getterName(), 'Got a '.\gettype($obj->$getterName()).' instead of a boolean for property -> '.$getterName);
         }
     }
+
+    public function assertUrlContainsAllRequestParameters(string $url, array $parameters): void
+    {
+        foreach ($parameters as $parameter) {
+            if (\is_bool($parameter)) {
+                $parameter = $parameter ? 'true' : 'false';
+            }
+
+            if (!\is_array($parameter)) {
+                $this->assertStringContainsString($parameter, urldecode($url));
+            } else {
+                $this->assertUrlContainsAllRequestParameters($url, $parameter);
+            }
+        }
+    }
 }

tests/unit/BigBlueButtonTest.php

@@ -163,12 +163,8 @@ public function testCreateMeetingUrl()
     {
         $params = $this->generateCreateParams();
         $url = $this->bbb->getCreateMeetingUrl($this->getCreateMock($params));
-        foreach ($params as $key => $value) {
-            if (\is_bool($value)) {
-                $value = $value ? 'true' : 'false';
-            }
-            $this->assertStringContainsString(rawurlencode($key).'='.rawurlencode($value), $url);
-        }
+
+        $this->assertUrlContainsAllRequestParameters($url, $params);
     }
 
     /* Join Meeting */

tests/unit/Parameters/CreateMeetingParametersTest.php

@@ -89,6 +89,7 @@ public function testCreateMeetingParameters()
         $this->assertEquals($params['breakoutRoomsRecord'], $createMeetingParams->isBreakoutRoomsRecord());
         $this->assertEquals($params['allowRequestsWithoutSession'], $createMeetingParams->isAllowRequestsWithoutSession());
         $this->assertEquals($params['virtualBackgroundsDisabled'], $createMeetingParams->isVirtualBackgroundsDisabled());
+        $this->assertEquals(json_encode($params['groups']), json_encode($createMeetingParams->getBreakoutRoomsGroups()));
 
         // Check values are empty of this is not a breakout room
         $this->assertNull($createMeetingParams->isBreakout());