Merge pull request #296 from opentok/dev

Release merge for 4.10.0

Author: SecondeJK

.gitignore

@@ -6,4 +6,8 @@ vendor/
 phpunit.xml
 sample/*/vendor/
 sample/*/cache/
+docs/
+.phpdoc/
+phpDocumentor*
+.phpunit.result.cache
 .idea/*

DEVELOPING.md

@@ -20,6 +20,13 @@ This project's tests are written as PHPUnit test cases. Common tasks:
 
 *  `./vendor/bin/phing test` - run the test suite.
 
+### Building docs
+
+Install [PhpDocumentor](https://docs.phpdoc.org/). Add it to the project root directory.
+Then run `php phpDocumentor.phar --config phpdoc.dist.xml`.
+
+The current reference docs were built with PhpDocumentor 3.3.0.
+
 ### Releasing
 
 In order to create a release, the following should be completed in order.

README.md

@@ -4,13 +4,18 @@
 
 <img src="https://assets.tokbox.com/img/vonage/Vonage_VideoAPI_black.svg" height="48px" alt="Tokbox is now known as Vonage" />
 
-The OpenTok PHP SDK lets you generate [sessions](http://tokbox.com/developer/guides/create-session/) and
-[tokens](http://tokbox.com/developer/guides/create-token/) for [OpenTok](http://www.tokbox.com/)
-applications, and [archive](http://tokbox.com/developer/guides/archiving/) sessions.
-It also includes methods for working with OpenTok
-[archives](http://tokbox.com/developer/guides/archiving), working with OpenTok
-[SIP interconnect](http://tokbox.com/developer/guides/sip), and
-[disconnecting clients from sessions](http://tokbox.com/developer/guides/moderation/rest/).
+The OpenTok PHP SDK provides methods for:
+
+* Generating
+[sessions](https://tokbox.com/developer/guides/create-session/) and
+[tokens](https://tokbox.com/developer/guides/create-token/) for
+[OpenTok](https://www.tokbox.com/) applications that run on the .NET platform
+* Working with [OpenTok archives](https://tokbox.com/opentok/tutorials/archiving)
+* Working with [OpenTok live streaming broadcasts](https://tokbox.com/developer/guides/broadcast/live-streaming/)
+* Working with [OpenTok SIP interconnect](https://tokbox.com/developer/guides/sip)
+* [Sending signals to clients connected to a session](https://www.tokbox.com/developer/guides/signaling/)
+* [Disconnecting clients from sessions](https://tokbox.com/developer/guides/moderation/rest/)
+* [Forcing clients in a session to disconnect or mute published audio](https://tokbox.com/developer/guides/moderation/)
 
 ## Installation
 
@@ -370,6 +375,17 @@ use OpenTok\OpenTok;
 $opentok->forceDisconnect($sessionId, $connectionId);
 ```
 
+### Forcing clients in a session mute published audio
+
+You can force the publisher of a specific stream to stop publishing audio using the 
+`Opentok.forceMuteStream($sessionId, $stream)` method.
+
+You can force the publisher of all streams in a session (except for an optional list of streams)
+to stop publishing audio using the `Opentok.forceMuteAll($sessionId, $excludedStreamIds)` method.
+You can then disable the mute state of the session by calling the
+`Opentok.DisableForceMute(sessionId)` or `Opentok.DisableForceMuteAsync(sessionId)`
+method.
+
 ### Sending Signals
 
 Once a Session is created, you can send signals to everyone in the session or to a specific connection.
@@ -411,7 +427,7 @@ $opentok->signal($sessionId, $signalPayload);
 For more information, see the [OpenTok signaling developer
 guide](https://tokbox.com/developer/guides/signaling/).
 
-## Working with SIP Interconnect
+### Working with SIP Interconnect
 
 You can add an audio-only stream from an external third-party SIP gateway using the SIP
 Interconnect feature. This requires a SIP URI, the session ID you wish to add the audio-only
@@ -441,59 +457,6 @@ $opentok->dial($sessionId, $token, $sipUri, $options);
 For more information, see the [OpenTok SIP Interconnect developer
 guide](https://tokbox.com/developer/guides/sip/).
 
-## Force Disconnect
-
-Your application server can disconnect a client from an OpenTok session by calling the `forceDisconnect($sessionId, $connectionId)`
-method of the `OpenTok\OpenTok` class.
-
-```php
-use OpenTok\OpenTok;
-
-// Force disconnect a client connection
-$opentok->forceDisconnect($sessionId, $connectionId);
-```
-
-## Sending Signals
-
-Once a Session is created, you can send signals to everyone in the session or to a specific connection.
-You can send a signal by calling the `signal($sessionId, $payload, $connectionId)` method of the
-`OpenTok\OpenTok` class.
-
-The `$sessionId` parameter is the session ID of the session.
-
-The `$payload` parameter is an associative array used to set the
-following:
-
-- `data` (string) -- The data string for the signal. You can send a maximum of 8kB.
-
-- `type` (string) -- &mdash; (Optional) The type string for the signal. You can send a maximum of 128 characters, and only the following characters are allowed: A-Z, a-z, numbers (0-9), '-', '\_', and '~'.
-
-The `$connectionId` parameter is an optional string used to specify the connection ID of
-a client connected to the session. If you specify this value, the signal is sent to
-the specified client. Otherwise, the signal is sent to all clients connected to the session.
-
-```php
-use OpenTok\OpenTok;
-
-// Send a signal to a specific client
-$signalPayload = array(
-    'data' => 'some signal message',
-    'type' => 'signal type'
-);
-$connectionId = 'da9cb410-e29b-4c2d-ab9e-fe65bf83fcaf';
-$opentok->signal($sessionId, $signalPayload, $connectionId);
-
-// Send a signal to everyone in the session
-$signalPayload = array(
-    'data' => 'some signal message',
-    'type' => 'signal type'
-);
-$opentok->signal($sessionId, $signalPayload);
-```
-
-For more information, see the [OpenTok signaling developer
-guide](https://tokbox.com/developer/guides/signaling/).
-
 ## Samples
 
 There are three sample applications included in this repository. To get going as fast as possible, clone the whole

composer.json

@@ -32,7 +32,8 @@
         "ext-xml": "*",
         "johnstevenson/json-works": "~1.1",
         "firebase/php-jwt": "^5.0",
-        "guzzlehttp/guzzle": "~6.0|~7.0"
+        "guzzlehttp/guzzle": "~6.0|~7.0",
+      "ext-json": "*"
     },
     "require-dev": {
         "phpunit/phpunit": "^7.4|^8.0",

phpdoc.dist.xml

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<phpdocumentor
+        configVersion="3"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xmlns="https://www.phpdoc.org"
+        xsi:noNamespaceSchemaLocation="https://docs.phpdoc.org/latest/phpdoc.xsd"
+>
+    <paths>
+        <output>docs</output>
+    </paths>
+    <version number="latest">
+        <api>
+            <source dsn=".">
+                <path>src</path>
+            </source>
+            <ignore hidden="true" symlinks="true">
+              <path>src/OpenTok/Util</path>
+            </ignore>
+        </api>
+    </version>
+</phpdocumentor>

src/OpenTok/Archive.php

@@ -14,7 +14,7 @@
 * The time at which the archive was created, in milliseconds since the UNIX epoch.
 *
 * @property string $duration
-* The duration of the archive, in milliseconds.
+* The duration of the archive, in seconds.
 *
 * @property bool $hasVideo
 * Whether the archive has a video track (<code>true</code>) or not (<code>false</code>).
@@ -49,6 +49,17 @@
 * @property string $size
 * The size of the MP4 file. For archives that have not been generated, this value is set to 0.
 *
+* @property string $streamMode
+* Whether streams included in the archive are selected automatically (<code>StreamMode.AUTO</code>) or
+* manually (<code>StreamMode.MANUAL</code>). When streams are selected automatically (<code>StreamMode.AUTO</code>),
+* all streams in the session can be included in the archive. When streams are selected manually
+* (<code>StreamMode.MANUAL</code>), you specify streams to be included based on calls to the
+* <code>Archive.addStreamToArchive()</code> and <code>Archive.removeStreamFromArchive()</code> methods.
+* With manual mode, you can specify whether a stream's audio, video, or both are included in the
+* archive. In both automatic and manual modes, the archive composer includes streams based on
+* <a href="https://tokbox.com/developer/guides/archive-broadcast-layout/#stream-prioritization-rules">stream
+* prioritization rules</a>.
+*
 * @property string $status
 * The status of the archive, which can be one of the following:
 *
@@ -95,14 +106,16 @@ public function __construct($archiveData, $options = array())
             'apiKey' => null,
             'apiSecret' => null,
             'apiUrl' => 'https://api.opentok.com',
-            'client' => null
+            'client' => null,
+            'streamMode' => StreamMode::AUTO
         );
         $options = array_merge($defaults, array_intersect_key($options, $defaults));
-        list($apiKey, $apiSecret, $apiUrl, $client) = array_values($options);
+        list($apiKey, $apiSecret, $apiUrl, $client, $streamMode) = array_values($options);
 
         // validate params
         Validators::validateArchiveData($archiveData);
         Validators::validateClient($client);
+        Validators::validateHasStreamMode($streamMode);
 
         $this->data = $archiveData;
 
@@ -137,6 +150,7 @@ public function __get($name)
             case 'hasAudio':
             case 'outputMode':
             case 'resolution':
+            case 'streamMode':
                 return $this->data[$name];
             default:
                 return null;
@@ -202,6 +216,65 @@ public function toJson()
         return json_encode($this->jsonSerialize());
     }
 
+    /**
+     * Adds a stream to a currently running archive that was started with the
+     * the streamMode set to StreamMode.Manual. You can call the method
+     * repeatedly with the same stream ID, to toggle the stream's audio or video in the archive.
+     * 
+     * @param String $streamId The stream ID.
+     * @param Boolean $hasAudio Whether the archive should include the stream's audio (true, the default)
+     * or not (false).
+     * @param Boolean $hasVideo Whether the archive should include the stream's video (true, the default)
+     * or not (false).
+     *
+     * @return Boolean Returns true on success.
+     */
+    public function addStreamToArchive(string $streamId, bool $hasAudio, bool $hasVideo): bool
+    {
+        if ($this->streamMode === StreamMode::AUTO) {
+            throw new InvalidArgumentException('Cannot add stream to an Archive in auto stream mode');
+        }
+
+        if ($hasAudio === false && $hasVideo === false) {
+            throw new InvalidArgumentException('Both hasAudio and hasVideo cannot be false');
+        }
+
+        if ($this->client->addStreamToArchive(
+            $this->data['id'],
+            $streamId,
+            $hasVideo,
+            $hasVideo
+        )) {
+            return true;
+        }
+
+        return false;
+    }
+
+    /**
+     * Removes a stream from a currently running archive that was started with the
+     * the streamMode set to StreamMode.Manual.
+     * 
+     * @param String $streamId The stream ID.
+     *
+     * @return Boolean Returns true on success.
+     */
+    public function removeStreamFromArchive(string $streamId): bool
+    {
+        if ($this->streamMode === StreamMode::AUTO) {
+            throw new InvalidArgumentException('Cannot remove stream to an Archive in auto stream mode');
+        }
+
+        if ($this->client->removeStreamFromArchive(
+            $this->data['id'],
+            $streamId
+        )) {
+            return true;
+        }
+
+        return false;
+    }
+
     /**
      * Returns an associative array representation of this Archive object.
      * @deprecated 3.0.0 A more standard name for this method is supplied by JsonSerializable

src/OpenTok/ArchiveList.php

@@ -67,6 +67,8 @@ public function totalCount()
 
     /**
      * Returns an array of Archive objects.
+     *
+     * @return Archive[]
      */
     public function getItems()
     {

src/OpenTok/ArchiveMode.php

@@ -17,10 +17,10 @@ abstract class ArchiveMode extends BasicEnum
      * The session is not archived automatically. To archive the session, you can call the
      * \OpenTok\OpenTok->startArchive() method.
      */
-    const MANUAL = 'manual';
+    public const MANUAL = 'manual';
     /**
-     * The session is archived automatically (as soon as there are clients publishing streams
+     * The session is archived automatically (as soon as there are clients connected
      * to the session).
      */
-    const ALWAYS = 'always';
+    public const ALWAYS = 'always';
 }