Merge pull request #228 from opentok/dev

v4.3.0

Author: Manik Sachdeva

README.md

@@ -2,34 +2,38 @@
 
 [![Build Status](https://travis-ci.org/opentok/OpenTok-PHP-SDK.svg)](https://travis-ci.org/opentok/OpenTok-PHP-SDK)
 
-The OpenTok PHP SDK lets you generate [sessions](http://tokbox.com/opentok/tutorials/create-session/) and
-[tokens](http://tokbox.com/opentok/tutorials/create-token/) for [OpenTok](http://www.tokbox.com/)
-applications, and [archive](http://tokbox.com/opentok/tutorials/archiving/) sessions.
+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/).
 
-# Installation
+## Installation
 
-## Composer (recommended):
+### Composer (recommended):
 
 Composer helps manage dependencies for PHP projects. Find more info here: <http://getcomposer.org>
 
 Add this package (`opentok/opentok`) to your `composer.json` file, or just run the following at the
 command line:
 
 ```
-$ ./composer.phar require opentok/opentok 4.2.x
+$ ./composer.phar require opentok/opentok 4.3.x
 ```
 
-## Manually:
+### Manually:
 
 Download the `opentok.phar` file for the latest release from the [Releases](https://github.com/opentok/opentok-php-sdk/releases)
 page.
 
 Place `opentok.phar` in the [include_path](http://www.php.net/manual/en/ini.core.php#ini.include-path) OR
 require it in any script which uses the `OpenTok\*` classes.
 
-# Usage
+## Usage
 
-## Initializing
+### Initializing
 
 This package follows the [PSR-4](http://www.php-fig.org/psr/psr-4/) autoloading standard. If you are
 using composer to install, you just require the generated autoloader:
@@ -47,7 +51,7 @@ use OpenTok\OpenTok;
 $opentok = new OpenTok($apiKey, $apiSecret);
 ```
 
-## Creating Sessions
+### Creating Sessions
 
 To create an OpenTok Session, use the `createSession($options)` method of the
 `OpenTok\OpenTok` class. The `$options` parameter is an optional array used to specify the following:
@@ -87,13 +91,14 @@ $session = $opentok->createSession($sessionOptions);
 $sessionId = $session->getSessionId();
 ```
 
-## Generating Tokens
+### Generating Tokens
 
 Once a Session is created, you can start generating Tokens for clients to use when connecting to it.
 You can generate a token either by calling the `generateToken($sessionId, $options)` method of the
 `OpenTok\OpenTok` class, or by calling the `generateToken($options)` method on the `OpenTok\Session`
 instance after creating it. The `$options` parameter is an optional array used to set the role,
-expire time, and connection data of the Token.
+expire time, and connection data of the Token. For layout control in archives and broadcasts, 
+the initial layout class list of streams published from connections using this token can be set as well.
 
 ```php
 use OpenTok\Session;
@@ -108,11 +113,12 @@ $token = $session->generateToken();
 $token = $session->generateToken(array(
     'role'       => Role::MODERATOR,
     'expireTime' => time()+(7 * 24 * 60 * 60), // in one week
-    'data'       => 'name=Johnny'
+    'data'       => 'name=Johnny',
+    'initialLayoutClassList' => array('focus')
 ));
 ```
 
-## Working with Streams
+### Working with Streams
 
 You can get information about a stream by calling the `getStream($sessionId, $streamId)` method of the
 `OpenTok\OpenTok` class.
@@ -142,7 +148,7 @@ $streamList = $opentok->listStreams($sessionId);
 $streamList->totalCount(); // total count
 ```
 
-## Working with Archives
+### Working with Archives
 
 You can only archive sessions that use the OpenTok Media Router
 (sessions with the media mode set to routed).
@@ -160,11 +166,11 @@ $archive = $opentok->startArchive($sessionId);
 
 // Create an archive using custom options
 $archiveOptions = array(
-    'name' => 'Important Presentation',      // default: null
-    'hasAudio' => true,                      // default: true
-    'hasVideo' => true,                      // default: true
-    'outputMode' => OutputMode::COMPOSED,    // default: OutputMode::COMPOSED
-    'resolution' => '1280x720'               // default: '640x480'
+    'name' => 'Important Presentation',     // default: null
+    'hasAudio' => true,                     // default: true
+    'hasVideo' => true,                     // default: true
+    'outputMode' => OutputMode::COMPOSED,   // default: OutputMode::COMPOSED
+    'resolution' => '1280x720'              // default: '640x480'
 );
 $archive = $opentok->startArchive($sessionId, $archiveOptions);
 
@@ -174,7 +180,11 @@ $archiveId = $archive->id;
 
 If you set the `outputMode` option to `OutputMode::INDIVIDUAL`, it causes each stream in the archive to be recorded to its own individual file. Please note that you cannot specify the resolution when you set the `outputMode` option to `OutputMode::INDIVIDUAL`. The `OutputMode::COMPOSED` setting (the default) causes all streams in the archive to be recorded to a single (composed) file.
 
-You can stop the recording of a started Archive using the `stopArchive($archiveId)` method of the
+Note that you can also create an automatically archived session, by passing in `ArchiveMode::ALWAYS`
+as the `archiveMode` key of the `options` parameter passed into the `OpenTok->createSession()`
+method (see "Creating Sessions," above).
+
+You can stop the recording of a started archive using the `stopArchive($archiveId)` method of the
 `OpenTok\OpenTok` object. You can also do this using the `stop()` method of the
 `OpenTok\Archive` instance.
 
@@ -186,7 +196,7 @@ $archive->stop();
 ```
 
 To get an `OpenTok\Archive` instance (and all the information about it) from an archive ID, use the
-`getArchvie($archiveId)` method of the `OpenTok\OpenTok` class.
+`getArchive($archiveId)` method of the `OpenTok\OpenTok` class.
 
 ```php
 $archive = $opentok->getArchive($archiveId);
@@ -216,12 +226,192 @@ $archives = $archiveList->getItems();
 $totalCount = $archiveList->totalCount();
 ```
 
-Note that you can also create an automatically archived session, by passing in `ArchiveMode::ALWAYS`
-as the `archiveMode` key of the `options` parameter passed into the `OpenTok->createSession()`
-method (see "Creating Sessions," above).
+For composed archives, you can change the layout dynamically, using the `updateArchiveLayout($archiveId, $layoutType)` method:
+
+```php
+use OpenTok\OpenTok;
+
+$layout Layout::getPIP(); // Or use another get method of the Layout class.
+$opentok->updateArchiveLayout($archiveId, $layout);
+```
+
+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
+by calling the `OpenTok->updateStream()` method.
+
+Setting the layout of composed archives is optional. By default, composed archives use the
+"best fit" layout (see [Customizing the video layout for composed
+archives](https://tokbox.com/developer/guides/archiving/layout-control.html)).
 
 For more information on archiving, see the
-[OpenTok archiving](https://tokbox.com/opentok/tutorials/archiving/) programming guide.
+[OpenTok archiving](https://tokbox.com/developer/guides/archiving/) developer guide.
+
+### Working with Broadcasts
+
+You can only start live streaming broadcasts for sessions that use the OpenTok Media Router
+(sessions with the media mode set to routed).
+
+Start the live streaming broadcast of an OpenTok Session using the
+`startBroadcast($sessionId, $options)` method of the `OpenTok\OpenTok` class.
+This will return an `OpenTok\Broadcast` instance. The `$options` parameter is
+an optional array used to assign a layout type for the broadcast.
+
+```php
+// Start a live streaming broadcast of a session
+$broadcast = $opentok->startBroadcast($sessionId);
+
+
+// Start a live streaming broadcast of a session, setting a layout type
+$options = array(
+    'layout' => Layout::getBestFit()
+);
+$broadcast = $opentok->startBroadcast($sessionId, $options);
+
+// Store the broadcast ID in the database for later use
+$broadcastId = $broadcast->id;
+```
+
+You can stop the live streaming broadcast using the `stopBroadcast($broadcastId)` method of the
+`OpenTok\OpenTok` object. You can also do this using the `stop()` method of the
+`OpenTok\Broadcast` instance.
+
+```php
+// Stop a broadcast from an broadcast ID (fetched from database)
+$opentok->stopBroadcast($broadcastId);
+
+// Stop a broadcast from an Broadcast instance (returned from startBroadcast)
+$broadcast->stop();
+```
+
+To get an `OpenTok\Broadcast` instance (and all the information about it) from a broadcast ID,
+use the `getBroadcast($broadcastId)` method of the `OpenTok\OpenTok` class.
+
+```php
+$broadcast = $opentok->getBroadcast($broadcastId);
+```
+
+You can set change the layout dynamically, using the
+`OpenTok->updateBroadcastLayout($broadcastId, $layout)` method:
+
+```php
+use OpenTok\OpenTok;
+
+$layout Layout::getPIP(); // Or use another get method of the Layout class.
+$opentok->updateBroadcastLayout($broadcastId, $layout);
+```
+You can use the `Layout` class to set the layout types:
+`Layout::getHorizontalPresentation()`, `Layout::getVerticalPresentation()`,  `Layout::getPIP()`,
+`Layout::getBestFit()`, `Layout::createCustom()`.
+
+```php
+$layoutType = Layout::getHorizontalPresentation();
+$opentok->setArchiveLayout($archiveId, $layoutType);
+
+// For custom Layouts, you can do the following
+$options = array(
+    'stylesheet' => 'stream.instructor {position: absolute; width: 100%;  height:50%;}'
+);
+
+$layoutType = Layout::createCustom($options);
+$opentok->setArchiveLayout($archiveId, $layoutType);
+```
+
+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
+by calling the `OpenTok->updateStream()` method.
+
+Setting the layout of live streaming broadcasts is optional. By default, broadcasts use the
+"best fit" layout (see [Configuring video layout for OpenTok live streaming
+broadcasts](https://tokbox.com/developer/guides/broadcast/live-streaming/#configuring-video-layout-for-opentok-live-streaming-broadcasts)).
+
+For more information on live streaming broadcasts, see the
+[OpenTok live streaming broadcasts](https://tokbox.com/developer/guides/broadcast/live-streaming/)
+developer guide.
+
+### Force a Client to 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/).
+
+## 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
+stream to, and a token to connect to that session ID.
+
+To initiate a SIP call, call the `dial($sessionId, $token, $sipUri, $options)` method of the
+`OpenTok\OpenTok` class:
+
+```php
+$sipUri = 'sip:[email protected];transport=tls';
+
+$options = array(
+  'headers' =>  array(
+    'X-CUSTOM-HEADER' => 'headerValue'
+  ),
+  'auth' => array(
+    'username' => 'username',
+    'password' => 'password'
+  ),
+  'secure' => true,
+  'from' => '[email protected]'
+);
+
+$opentok->dial($sessionId, $token, $sipUri, $options);
+```
+
+For more information, see the [OpenTok SIP Interconnect developer
+guide](https://tokbox.com/developer/guides/sip/).
 
 ## Force Disconnect
 
@@ -276,20 +466,21 @@ $opentok->signal($sessionId, $signalPayload);
 For more information, see the [OpenTok signaling developer
 guide](https://tokbox.com/developer/guides/signaling/).
 
-# Samples
+## Samples
 
-There are two sample applications included in this repository. To get going as fast as possible, clone the whole
+There are three sample applications included in this repository. To get going as fast as possible, clone the whole
 repository and follow the Walkthroughs:
 
 *  [HelloWorld](sample/HelloWorld/README.md)
 *  [Archiving](sample/Archiving/README.md)
+*  [SipCall](sample/SipCall/README.md)
 
-# Documentation
+## Documentation
 
 Reference documentation is available at
 <https://tokbox.com/developer/sdks/php/reference/index.html>.
 
-# Requirements
+## Requirements
 
 You need an OpenTok API key and API secret, which you can obtain by logging into your
 [TokBox account](https://tokbox.com/account).
@@ -298,12 +489,12 @@ The OpenTok PHP SDK requires PHP 5.6+ or PHP 7+
 
 For PHP 5.5 and lower please use PHP SDK v2.5
 
-# Release Notes
+## Release Notes
 
 See the [Releases](https://github.com/opentok/opentok-php-sdk/releases) page for details
 about each release.
 
-# Important changes since v2.2.0
+## Important changes since v2.2.0
 
 **Changes in v2.2.1:**
 
@@ -332,12 +523,12 @@ See the reference documentation
 <http://www.tokbox.com/opentok/libraries/server/php/reference/index.html> and in the
 docs directory of the SDK.
 
-# Development and Contributing
+## Development and Contributing
 
 Interested in contributing? We :heart: pull requests! See the [Development](DEVELOPING.md) and
 [Contribution](CONTRIBUTING.md) guidelines.
 
-# Support
+## Support
 
 See <https://support.tokbox.com> for all our support options.