Vonage Video Transition Guide for PHP

Transitioning from `opentok/opentok` to `vonage/video`

Introduction

Purpose

The OpenTok PHP SDK is in maintenance mode, as we have transitioned to a new Video SDK where Vonage credentials can be used in our Node SDK across all APIs.

Scope

As vonage/video uses the vonage/client-core library, the minimum requirements to use it are PHP8.1. This doesn't, however, mean that any version below 8.1 will not work. It does mean that parsing errors from lower versions might occour, especially since the core library uses a lot of constructor property promotion.

Assumptions

To be able to successfully migrate, you will need a firm grasp of how PHP's de-facto package manager, Composer works and how PHP's namespaces work as this will have the biggest impact.

Resources

Vonage Video SDK Source Code Source Code on Packagist Vonage PHP SDK (required for Video to work)Vonage Video API Documentation Vonage Video API Specifications

Planning Your Migration

Evaluate Impact

To lessen the impact, almost all of the function signatures have remained the same in the Vonage Video SDK. Therefore, while the function calls and arguments can remain the same, the most impact will be client creation, usage of the client and checking that your application's logic consumes responses in the correct way.

The biggest impact that will dictate whether or not you can migrate is if you are using unsupported methods. Right now, the supported functionality is:

Session Creation Signaling Force Mute Archiving

The current functionality not supported is:

Custom S3/Azure Buckets SIP Interconnect Live Streaming Broadcast Experience Composer Account Management

If you are using any of the above, you will not be able to migrate.

Timeline

The time needed really depends on the amount of usage within your application. If you are creating an OpenTok client for every API call you need to make, it's likely to take longer. The method of creating the OpenTok client will also push time on depending - hard-coded credentials will cause more refactoring for instance.

If your application mainly does not use options being passed into your video methods, migration could take up to a couple of hours at most. However, if you have more complex requirements where you are passing in configuration into your functions, it will take manual refactoring to correct them. For this reason, we recommend allocating more time depending on how many calls your application makes.

Package Update

To update the video packages, run the following in Composer:

composer update

The Video and Core SDK libraries use the SemVer versioning system, so when one of these libraries reaches a major version, you will need to specify that major version in the composer.json and run composer update to pull all changes upstream.

Authentication Changes

The Vonage Video SDK provides the ability to use your Vonage credentials instead of your OpenTok ones. They are, however, backwards compatible. The difference is how you handle credentials in the new Client - all auth is now handled by value objects that clearly define what they are, instead of string arguments for ApiKey and ApiSecret. For your migration, you will want to use a Vonage\Client\Credentials\Basic::class object with your API Key and Secret.

Method Changes

Function signatures have been coded with value objects which will need to be created. For example, the createSession method has changed from this:

To this:

You can see that options is no longer an array, but also will default to null. If you do not pass an argument in, the object is created for you within the method. However, if you currently pass in options, they will need to be migrated. Value objects within the SDK ship with the convenient fromArray() function, so if you have an existing array of options, you can pass them in like so:

Migration Strategies

Migration via Find-and-Replace

This is broken down into two steps.

You will need to install the necessary new packages. In your command line, install the following two packages using Composer:

composer install vonage/client-corecomposer install vonage/video

Using your IDE, use a global find and replace. An example of client creation would be the following:

Providing that you use the same line of code to create the client, your find and replace should look like the following:

We're using Fully Qualified namespaces here for compatibility - you can refactor the code after the migrations to import the namespaces.

The important part to add here is the calling of ->video() chained on the end. If you replace $client with a Vonage Client(), your function calls will not be backwards compatible. Calling ->video() returns the Video Client which is the same class entry point that is backwards compatible with OpenTok.

For each method signature change, you will need to hand code the migration from arrays or strings into the correct value object.

Wrapper/Adapter Pattern

One of the easiest migration circumstances is if you use a popular PHP Web Application Framework such as Symfony or Laravel. In this situation, you might already be using a Service Container to bootstrap the client. In this case, you'll only need to replace the client within the service. If you do not have a service container, it would be a good opportunity during the migration to create one.

Without one of the major frameworks, you can still do this yourself. Have a look at Ryan Chandler's excellent write up here on how to implement a PSR-11 interface.

Testing Recommendations

If you have an existing test suite, you'll want to check that your assertions are still valid. Creating a Session, for instance, will be slightly different because you will want to assert that you have created a \Vonage\Video\Session object rather than an OpenTok\Session one. Accessing data from the value object will also be by method rather than through an array, so you'll need to change assertions for anything that was previously an array return.

We recommend adding unit and integration tests for each part of your application that uses the Video Client. Integration tests should include live calls to the API and run as part of your production pipeline, but unit tests can mock out the response to make sure no calls are made, but your application is parsing responses from the SDK correctly.

For a headstart in how to mock out the responses, have a look at the existing test suite for the SDK itself which tests the functionality you will want to incorporate into your own test suite.

Support Channels

Direct Support via. Slack: Vonage Developer Slack

Raise a ticket in Github: https://github.com/Vonage/vonage-php-sdk-video