For developers that have been following the recent roadmap of the Vonage PHP Server SDK, this release should look much as expected. In our previous significant release, former maintainer Chris Tankersley explained the goal of simplifying the library, and I have continued that work.
This major release does, however, take into consideration a change in team and therefore ownership of the SDK and therefore does not remove every deprecation. Coming in fresh to these libraries brings various challenges, such as understanding approaches previously taken as well as needing to meet the needs of our developers when it comes to the evolution of the SDK. Some of the more complex 'under the hood' behaviour has been left as is, with the notices still present. These will still be removed, but at a later time.
From this release onwards, the library will track the PHP language release lifecycle. As such, PHP8.1 is now supported, and support for versions 7.2 and 7.3 have been dropped.
Although the majority of end-users will not be affected by this change, it significantly alters how the repository is structured for those that wish to contribute to this open-source library. The new workflow, designed to fall into line with other Vonage Server SDKs, looks like the following:
mainbranch (renamed from version branches such as
- Pull requests are taken off
main, and merged to
devas the target
- merges from
mainare considered release merges, and therefore will result in a git tag that will push to Packagist.
The biggest code change to the library is almost all array accessors, which were marked as deprecated, have now been removed. Previously all entities used the
ArrayAccess interface to implement various core PHP functions like
offsetSet($offset, value). These caused unnecessary complexity, especially as some entities actually proxied the value into a
Now that these have been removed, you use getters and setters instead. For example:
Previous ```php?start_inline=1 $balance = new Vonage\Account\Balance('12.99', false); $balanceValue = $balance['balance']
New ```php?start_inline=1 $balance = new Vonage\Account\Balance('12.99', false); $balanceValue = $balance->getBalance();
If there are getters or setters missing, you can add some extra code to make your code backward compatible - all entities implement the
ArrayHydrateInterface. This means you can still access objects as arrays cast to new variables by using the
fromArray() methods. For example:
// this will error $balance = new Vonage\Account\Balance('12.99', false); $balanceValue = $balance['balance'] // this will fix it $balance = new Vonage\Account\Balance('12.99', false); $balanceArray = $balance->toArray(); $balanceValue = $balanceArray['balance']
Almost all of the entities also used the
jsonUnserialize interfaces. Most of these have been removed, as the original thinking to be able to customise what data structures are serialized and unserialized are not required. To unserialize an object, the
ArrayHydrateInterface methods are used instead.
Vonage\Call client was already marked for removal, so this has now happened. This functionality has been replaced with the
Vonage\Voice client and its associated entities, the usage of which is already documented with examples in the Readme.
Here is a "before and after example" of its use:
// old $call = new Vonage\Call\Call(); $call->setTo('14843331234') ->setFrom('14843335555') ->setWebhook(Vonage\Call\Call::WEBHOOK_ANSWER, 'https://example.com/answer') ->setWebhook(Vonage\Call\Call::WEBHOOK_EVENT, 'https://example.com/event'); $client->call()->create($call); // new $outboundCall = new \Vonage\Voice\OutboundCall( new \Vonage\Voice\Endpoint\Phone('14843331234'), new \Vonage\Voice\Endpoint\Phone('14843335555') ); $outboundCall ->setAnswerWebhook( new \Vonage\Voice\Webhook('https://example.com/answer') ) ->setEventWebhook( new \Vonage\Voice\Webhook('https://example.com/event') ) ; $response = $client->voice()->createOutboundCall($outboundCall);
The library originally had an incomplete implementation of a feature that was in the beta stage of the release cycle. This feature has now been dropped, and therefore the library has dropped support for it. There is no alternative functionality to replace this if it has been used, but as it was incomplete and marked for removal there should not be any impact in terms of using the SDK.
These are changes that are very much "under the hood", behind the service layer of the library that is designed to be developer-facing. For transparency, I'm going to document a few of these changes.
A number of tests were marked as incomplete or skipped, with given reasons. Given the change of maintainer, and some historical context/domain knowledge lost as the code changes hands, I have made the decision to clean the code by deleting them. There are two justifications for this: 1. The code being tested might have changed context or state i.e. a feature that now behaves differently in our APIs. 2. We have an aim to increase code coverage to near 100% this year, and as such nothing will be left out that these tests might have set out to cover.
For continuously released, modern PHP Frameworks such as Laravel and Symfony, PSR-11 support for v2.0 of the service container has been added with no impact.
Previously this method would return an integer. This value is stored as a string from the API response made to populate it, and could possibly contain special characters. Given this, it has been changed to return a string.
Vonage\Client\Credentials\Keypair() object has a new method,
getKey(), to get the
key. This was added to support some additional testing of the JWT functionality.
Similar to the support version bump for the container,
psr/log v.2.0 is now supported.
When creating an
Application\Client, a shim exists for backward compatibility that allows the object to be created without an implementable
HydratorInterface object. This shim has now been removed.
My thanks go to Daniel Miedzik, Github user
iceleo-com, and Fabien Salathe for contributions towards this release. There will be noticeable changes, some of which we've already begun to implement, with regards to the maintenance of this library, such as keeping the issues list documented with appropriate labelling and speeding up response times. Our aim is to also move to more regular releases, in line with a more "CI" approach.
When we have removed the final marked deprecations in a future release, we're going to take steps to simplify the library further to encourage contributions from outside Vonage. After all, our libraries are Open Source!