feat: Add list connections route

src/OpenTok/Connection.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace OpenTok;
+
+/**
+* Represents a connection in an OpenTok session.
+* <p>
+* See <a href="OpenTok.OpenTok.html#method_listConnections">OpenTok.listConnections()</a>.
+*
+* @property String $connectionId
+* The connection ID.
+*
+* @property String $connectionState
+* The state of the connection (either "Connecting" or "Connected").
+*
+* @property String $createdAt
+* The timestamp for when the connection was created, expressed in milliseconds since the Unix epoch.
+*/
+
+class Connection
+{
+
+    private $data;
+
+    public function __construct($connectionData)
+    {
+
+        $this->data = $connectionData;
+    }
+
+    /** @ignore */
+    public function __get($name)
+    {
+        switch ($name) {
+            case 'connectionId':
+            case 'connectionState':
+            case 'createdAt':
+                return $this->data[$name];
+            default:
+                return null;
+        }
+    }
+
+    public function jsonSerialize()
+    {
+        return $this->data;
+    }
+}

src/OpenTok/ConnectionList.php

@@ -0,0 +1,131 @@
+<?php
+
+namespace OpenTok;
+
+/**
+ * An object, returned by the <a href="OpenTok.OpenTok.html#method_listConnections">OpenTok.listConnections()</a>
+ * method, representing a list of connections in an OpenTok session.
+ */
+class ConnectionList implements \Iterator
+{
+    /** @ignore */
+    private $data;
+
+    /** @ignore */
+    private $items;
+
+    /** @ignore */
+    private $position = 0;
+
+    /** @ignore */
+    public function __construct($connectionListData)
+    {
+        $this->data = $connectionListData;
+        $this->position = 0;
+    }
+
+    /**
+     * Returns the number of total connections for the session ID.
+     *
+     * @return int
+     */
+    public function totalCount()
+    {
+        return $this->data['count'];
+    }
+
+    /**
+     * Returns the project ID (Application ID).
+     *
+     * @return string
+     */
+    public function getProjectId()
+    {
+        return $this->data['projectId'];
+    }
+
+    /**
+     * Returns the session ID.
+     *
+     * @return string
+     */
+    public function getSessionId()
+    {
+        return $this->data['sessionId'];
+    }
+
+    /**
+     * Returns an array of Connection objects.
+     *
+     * @return Connection[]
+     */
+    public function getItems()
+    {
+        if (!is_array($this->items)) {
+            $items = array();
+            foreach ($this->data['items'] as $connectionData) {
+                $items[] = new Connection($connectionData);
+            }
+            $this->items = $items;
+        }
+        return $this->items;
+    }
+
+    /**
+     * @return array
+     */
+    public function jsonSerialize()
+    {
+        return $this->data;
+    }
+
+    // Iterator interface methods
+
+    /**
+     * Rewind the Iterator to the first element
+     */
+    public function rewind(): void
+    {
+        $this->position = 0;
+    }
+
+    /**
+     * Return the current element
+     * 
+     * @return Connection
+     */
+    public function current(): Connection
+    {
+        $items = $this->getItems();
+        return $items[$this->position];
+    }
+
+    /**
+     * Return the key of the current element
+     * 
+     * @return int
+     */
+    public function key(): int
+    {
+        return $this->position;
+    }
+
+    /**
+     * Move forward to next element
+     */
+    public function next(): void
+    {
+        ++$this->position;
+    }
+
+    /**
+     * Checks if current position is valid
+     * 
+     * @return bool
+     */
+    public function valid(): bool
+    {
+        $items = $this->getItems();
+        return isset($items[$this->position]);
+    }
+}

src/OpenTok/OpenTok.php

@@ -1140,6 +1140,25 @@ public function listStreams($sessionId)
         return new StreamList($streamListData);
     }
 
+    /**
+     * Returns a ConnectionList object for the given session ID.
+     *
+     * Use this method to list the connections from an OpenTok session associated with an application.
+     *
+     * @param String $sessionId The session ID.
+     *
+     * @return ConnectionList A ConnectionList object. Call the getItems() method of the ConnectionList object
+     * to return an array of Connection objects.
+     */
+    public function listConnections($sessionId)
+    {
+        Validators::validateSessionIdBelongsToKey($sessionId, $this->apiKey);
+
+        // make API call
+        $connectionListData = $this->client->listConnections($sessionId);
+        return new ConnectionList($connectionListData);
+    }
+
     /**
      * Initiates an outgoing SIP call.
      * <p>

src/OpenTok/Util/Client.php

@@ -670,6 +670,24 @@ public function listStreams($sessionId)
         return $streamListJson;
     }
 
+    public function listConnections($sessionId)
+    {
+        $request = new Request(
+            'GET',
+            '/v2/project/' . $this->apiKey . '/session/' . $sessionId . '/connection/'
+        );
+        try {
+            $response = $this->client->send($request, [
+                'debug' => $this->isDebug(),
+            ]);
+            $connectionListJson = json_decode($response->getBody(), true);
+        } catch (\Exception $e) {
+            $this->handleException($e);
+            return;
+        }
+        return $connectionListJson;
+    }
+
     public function setStreamClassLists($sessionId, $payload)
     {
         $itemsPayload = array(

tests/OpenTokTest/OpenTokTest.php

@@ -2926,6 +2926,98 @@ public function testListStreams(): void
         $this->assertInstanceOf('OpenTok\StreamList', $streamList);
     }
 
+    public function testListConnections(): void
+    {
+        // Arrange
+        $this->setupOTWithMocks([[
+            'code' => 200,
+            'headers' => [
+                'Content-Type' => 'application/json'
+            ],
+            'path' => '/v2/project/APIKEY/session/SESSIONID/connection/get'
+        ]]);
+
+        $sessionId = '1_MX4xMjM0NTY3OH4-VGh1IEZlYiAyNyAwNDozODozMSBQU1QgMjAxNH4wLjI0NDgyMjI';
+
+        // Act
+        $connectionList = $this->opentok->listConnections($sessionId);
+
+        // Assert
+        $this->assertCount(1, $this->historyContainer);
+
+        $request = $this->historyContainer[0]['request'];
+        $this->assertEquals('GET', strtoupper($request->getMethod()));
+        $this->assertEquals('/v2/project/' . $this->API_KEY . '/session/' . $sessionId . '/connection/', $request->getUri()->getPath());
+        $this->assertEquals('api.opentok.com', $request->getUri()->getHost());
+        $this->assertEquals('https', $request->getUri()->getScheme());
+
+        $authString = $request->getHeaderLine('X-OPENTOK-AUTH');
+        $this->assertEquals(true, TestHelpers::validateOpenTokAuthHeader($this->API_KEY, $this->API_SECRET, $authString));
+
+        $this->assertInstanceOf('OpenTok\ConnectionList', $connectionList);
+        $this->assertEquals(3, $connectionList->totalCount());
+        $this->assertEquals('e9f8c166-6c67-440d-994a-04fb6dfed007', $connectionList->getProjectId());
+        $this->assertEquals('b40ef09b-3811-4726-b508-e41a0f96c68f', $connectionList->getSessionId());
+
+        $connections = $connectionList->getItems();
+        $this->assertCount(3, $connections);
+        $this->assertInstanceOf('OpenTok\Connection', $connections[0]);
+        $this->assertEquals('8b732909-0a06-46a2-8ea8-074e64d43422', $connections[0]->connectionId);
+        $this->assertEquals('Connected', $connections[0]->connectionState);
+        $this->assertEquals('1384221730000', $connections[0]->createdAt);
+    }
+
+    public function testListConnectionsWithInvalidSessionId(): void
+    {
+        // Arrange
+        $this->setupOT();
+
+        // Assert
+        $this->expectException('OpenTok\Exception\InvalidArgumentException');
+
+        // Act
+        $this->opentok->listConnections('invalid-session-id');
+    }
+
+    public function testListConnectionsIteration(): void
+    {
+        // Arrange
+        $this->setupOTWithMocks([[
+            'code' => 200,
+            'headers' => [
+                'Content-Type' => 'application/json'
+            ],
+            'path' => '/v2/project/APIKEY/session/SESSIONID/connection/get'
+        ]]);
+
+        $sessionId = '1_MX4xMjM0NTY3OH4-VGh1IEZlYiAyNyAwNDozODozMSBQU1QgMjAxNH4wLjI0NDgyMjI';
+
+        // Act
+        $connectionList = $this->opentok->listConnections($sessionId);
+
+        // Assert - Test direct iteration over ConnectionList
+        $iteratedConnections = [];
+        foreach ($connectionList as $index => $connection) {
+            $iteratedConnections[$index] = $connection;
+            $this->assertInstanceOf('OpenTok\Connection', $connection);
+        }
+
+        $this->assertCount(3, $iteratedConnections);
+        $this->assertEquals('8b732909-0a06-46a2-8ea8-074e64d43422', $iteratedConnections[0]->connectionId);
+        $this->assertEquals('Connected', $iteratedConnections[0]->connectionState);
+        $this->assertEquals('ab732909-0a06-46a2-8ea8-074e64d43412', $iteratedConnections[1]->connectionId);
+        $this->assertEquals('Connecting', $iteratedConnections[1]->connectionState);
+        $this->assertEquals('cd732909-0a06-46a2-8ea8-074e64d43433', $iteratedConnections[2]->connectionId);
+        $this->assertEquals('Connected', $iteratedConnections[2]->connectionState);
+
+        // Assert - Test that getItems() still works as before
+        $itemsConnections = $connectionList->getItems();
+        $this->assertCount(3, $itemsConnections);
+        $this->assertEquals($iteratedConnections[0]->connectionId, $itemsConnections[0]->connectionId);
+        $this->assertEquals($iteratedConnections[1]->connectionId, $itemsConnections[1]->connectionId);
+        $this->assertEquals($iteratedConnections[2]->connectionId, $itemsConnections[2]->connectionId);
+    }
+
     public function testsSetArchiveLayoutWithPredefined(): void
     {
         // Arrange

tests/mock/v2/project/APIKEY/session/SESSIONID/connection/get

@@ -0,0 +1,22 @@
+{
+  "count": 3,
+  "projectId": "e9f8c166-6c67-440d-994a-04fb6dfed007",
+  "sessionId": "b40ef09b-3811-4726-b508-e41a0f96c68f",
+  "items": [
+    {
+      "connectionId": "8b732909-0a06-46a2-8ea8-074e64d43422",
+      "connectionState": "Connected",
+      "createdAt": "1384221730000"
+    },
+    {
+      "connectionId": "ab732909-0a06-46a2-8ea8-074e64d43412",
+      "connectionState": "Connecting",
+      "createdAt": "1384221735000"
+    },
+    {
+      "connectionId": "cd732909-0a06-46a2-8ea8-074e64d43433",
+      "connectionState": "Connected",
+      "createdAt": "1384221740000"
+    }
+  ]
+}