4.99 beta by dragonmantank · Pull Request #555 · Vonage/vonage-php-sdk-core

dragonmantank · 2026-04-25T02:08:05Z

Description

This would be the final prep release to help people migrate to 5.0.0. This includes some additional deprecation notices that are based on 5.0.0 work, and some code to make it easier to start migrating right away.

This also includes a first draft of a migration guide, which can eventually be posted to the documentation site, but can also be shipped with the 4.x release.

Motivation and Context

Major migrations are always hard, and Symfony has set a precedent to help people move from Major to Major by making sure the code is properly signposted (and when possible) back-ported to help people start to migrate before the Major release. This preps that for Vonage users.

This should be merged before the 5.0.0-beta branch, so that it can be properly updated to handle the backports properly.

How Has This Been Tested?

Unit tests

Example Output or Screenshots (if appropriate):

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

My code follows the code style of this project.
My change requires a change to the documentation.
I have updated the documentation accordingly.
I have read the CONTRIBUTING document.
I have added tests to cover my changes.
All new and existing tests passed.

Co-authored-by: Copilot <copilot@github.com>

codecov-commenter · 2026-04-25T02:08:47Z

⚠️ JUnit XML file not found

The CLI was unable to find any JUnit XML files to upload.
For more help, visit our troubleshooting guide.

Copilot

Pull request overview

Prepares the 4.99 beta as a migration stepping stone toward 5.0 by adding runtime deprecation notices, introducing new “replacement” APIs (notably for Verify v1), and drafting an initial 5.0 upgrade guide.

Changes:

Added E_USER_DEPRECATED trigger points across many legacy APIs (clients, interfaces/traits, credentials, factory/container helpers).
Introduced new Verify v1 request/value objects (StartVerification, StartPSD2, CheckAttempt) and new Verify\Client methods (startVerification, startPsd2Verification, triggerNextEvent).
Updated tests and added an initial UPGRADE-5.0.md migration guide draft.

Reviewed changes

Copilot reviewed 70 out of 70 changed files in this pull request and generated 34 comments.

Show a summary per file

File	Description
test/Voice/ClientFactoryTest.php	Adjusts assertions around client factory wiring (now uses reflection to inspect APIResource).
test/Verify2/ClientFactoryTest.php	Updates Verify2 factory test to inspect APIResource via reflection.
test/Verify/VerificationTest.php	Updates Verify v1 tests; suppresses deprecations on deprecated getters.
test/Verify/RequestTest.php	Suppresses deprecations from deprecated `Verify\Request` constructor in tests.
test/Verify/ClientTest.php	Adds tests for new Verify v1 methods and suppresses deprecations for legacy APIs.
test/Verify/ClientFactoryTest.php	Updates Verify factory test to inspect APIResource via reflection.
test/Verify/CheckAttemptTest.php	Adds unit tests for new `CheckAttempt` value object.
test/Users/ClientFactoryTest.php	Updates Users factory test to inspect APIResource via reflection.
test/SimSwap/ClientTest.php	Suppresses deprecation when instantiating deprecated SimSwap client.
test/SimSwap/ClientIntegrationTest.php	Suppresses deprecations around deprecated GNP credentials / SimSwap access.
test/SimSwap/ClientFactoryTest.php	Suppresses deprecations during SimSwap client factory invocation.
test/Secrets/ClientFactoryTest.php	Updates Secrets factory test to inspect APIResource via reflection.
test/SMS/ClientFactoryTest.php	Updates SMS factory test to inspect APIResource via reflection.
test/Redact/ClientFactoryTest.php	Updates Redact factory test to inspect APIResource via reflection.
test/ProactiveConnect/ClientFactoryTest.php	Suppresses deprecations during factory invocation; inspects APIResource via reflection.
test/Numbers/ClientFactoryTest.php	Fixes service key and inspects APIResource via reflection.
test/NumberVerification/ClientTest.php	Suppresses deprecation when instantiating deprecated NumberVerification client.
test/NumberVerification/ClientFactoryTest.php	Suppresses deprecations during factory invocation.
test/Messages/ClientFactoryTest.php	Updates Messages factory test to inspect APIResource via reflection.
test/Insights/ClientFactoryTest.php	Updates Insights factory test to inspect APIResource via reflection.
test/Conversion/ClientFactoryTest.php	Updates Conversion factory test to inspect APIResource via reflection.
test/Conversation/ClientFactoryTest.php	Updates Conversation factory test to inspect APIResource via reflection.
test/Client/Factory/MapFactoryTest.php	Suppresses deprecations for deprecated `hasApi/getApi` in tests.
test/Client/Credentials/KeypairTest.php	Suppresses deprecation for deprecated `Keypair::getKey()` in tests.
test/Client/Credentials/Handler/GnpHandlerTest.php	Suppresses deprecations around deprecated GNP credentials in handler tests.
test/Application/ClientFactoryTest.php	Updates Application factory test to inspect APIResource via reflection.
test/Account/ClientFactoryTest.php	Updates Account factory test to inspect APIResource via reflection.
src/Voice/Client.php	Deprecates `getAPIResource()` and removes internal usage in favor of injected APIResource.
src/Voice/Call/Inbound.php	Deprecates legacy class and emits runtime deprecation on instantiation.
src/Voice/Call/Call.php	Deprecates legacy request class and emits runtime deprecation on instantiation.
src/Verify2/Client.php	Deprecates `getAPIResource()` and removes internal usage in favor of injected APIResource.
src/Verify/VerificationInterface.php	Deprecates legacy interface slated for removal.
src/Verify/StartVerification.php	Adds new Verify v1 request value object for starting verifications.
src/Verify/StartPSD2.php	Adds new Verify v1 request value object for starting PSD2 verifications.
src/Verify/RequestPSD2.php	Deprecates legacy PSD2 request and emits runtime deprecation.
src/Verify/Request.php	Deprecates legacy request and emits runtime deprecation.
src/Verify/Client.php	Adds new Verify v1 entrypoints; deprecates legacy entrypoints and adjusts APIResource handling.
src/Verify/CheckAttempt.php	Introduces new (readonly) value object replacing `Check` getters.
src/Verify/Check.php	Deprecates constants/getters in favor of `CheckAttempt`.
src/Users/Client.php	Deprecates `getApiResource()` and emits runtime deprecation.
src/Subaccount/Client.php	Deprecates `getAPIResource()` and emits runtime deprecation.
src/SimSwap/Client.php	Deprecates SimSwap client and emits runtime deprecations; updates internal APIResource usage.
src/Secrets/Client.php	Deprecates `getAPIResource()` and emits runtime deprecation.
src/SMS/Client.php	Deprecates `getAPIResource()` and emits runtime deprecation.
src/Redact/Client.php	Deprecates `getApiResource()` and avoids internal use by introducing `resolveApi()`.
src/ProactiveConnect/Client.php	Documents deprecation and avoids mutating shared APIResource via cloning in list retrieval.
src/Numbers/Client.php	Deprecates `getApiResource()` and avoids calling it internally.
src/NumberVerification/Client.php	Deprecates NumberVerification client and emits runtime deprecations; updates internal APIResource usage.
src/Messages/Client.php	Deprecates `getAPIResource()` and avoids internal usage by using injected APIResource directly.
src/Meetings/Client.php	Documents deprecation and avoids mutating shared APIResource via cloning for room operations.
src/Insights/Client.php	Deprecates `getApiResource()` and avoids internal use by cloning the injected APIResource directly.
src/Entity/IterableAPICollection.php	Deprecates `getApiResource()` and switches internal logic to use `$this->api` directly.
src/Entity/HasEntityTrait.php	Deprecates trait as part of entity layer removal.
src/Entity/EntityInterface.php	Deprecates interface as part of entity layer removal.
src/Conversion/Client.php	Deprecates `getAPIResource()` and avoids internal usage by using injected APIResource directly.
src/Conversation/Client.php	Deprecates `getAPIResource()` and avoids internal usage by using injected APIResource directly.
src/Client/Factory/MapFactory.php	Deprecates `hasApi()` and `getApi()` in favor of PSR container methods.
src/Client/Credentials/Keypair.php	Deprecates `getKey()` in favor of `getKeyRaw()`.
src/Client/Credentials/Handler/SimSwapGnpHandler.php	Documents deprecation of SimSwap credential handler.
src/Client/Credentials/Handler/NumberVerificationGnpHandler.php	Documents deprecation of NumberVerification credential handler.
src/Client/Credentials/Handler/GnpKeypairHandler.php	Deprecates GNP keypair handler.
src/Client/Credentials/Gnp.php	Deprecates GNP credentials and emits runtime deprecation on construction.
src/Client/ClientAwareTrait.php	Deprecates client-aware trait in favor of constructor injection.
src/Client/ClientAwareInterface.php	Deprecates client-aware interface in favor of constructor injection.
src/Client/APIClient.php	Deprecates `APIClient` interface for removal.
src/Client.php	Deprecates `generateJwt()`, `send()`, and `serialize()` and emits runtime deprecations.
src/Application/Client.php	Deprecates `getApiResource()` and avoids internal usage by using injected APIResource directly.
src/Application/ApplicationInterface.php	Deprecates application interface for removal.
src/Account/Client.php	Deprecates `getAPIResource()` and avoids internal usage by cloning the injected APIResource directly.
UPGRADE-5.0.md	Adds initial 5.0 migration guide draft.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-25T02:17:18Z

+     * @throws ClientExceptionInterface
+     * @throws ClientException\Exception
+     * @throws ClientException\Request
+     * @throws ClientException\Server
+     */


The @throws annotations reference ClientException\Request and ClientException\Server, but the exception classes in Vonage\Client\Exception are RequestException and ServerException. Update the docblocks so they refer to real types.

The exceptions are correct

Copilot · 2026-04-25T02:17:18Z

        $this->handlerClient->getCredentials()->willReturn(
-            new Client\Credentials\Container(new Client\Credentials\Gnp(
+            new Client\Credentials\Container(@new Client\Credentials\Gnp(
                'tel:+447700900000',
                $this->key,
                $this->application


@new ...Gnp(...) suppresses the deprecation emitted by the deprecated credential constructor. Since PHPUnit converts deprecations to exceptions, prefer asserting the deprecation explicitly (or migrating the test away from deprecated credentials) rather than silencing it.

Copilot · 2026-04-25T02:17:24Z

+        if ($client !== null) {
+            $this->client = $client;
+            $this->api->setClient($client);
+        }


ClientAwareTrait::setClient() does not propagate the client into $this->api. If a consumer uses the legacy pattern $verifyClient->setClient($vonageClient) (still supported per the upgrade guide), $this->api will never have a client set and API calls may fail. Consider overriding setClient() in this class (or otherwise syncing $this->api->setClient($client)) to preserve legacy behavior.

Copilot · 2026-04-25T02:17:24Z

+        $api = @$this->factory->getApi('test');
        $this->assertSame($this->client, $api->client);


Using @ on calls to the now-deprecated getApi()/hasApi() suppresses deprecation exceptions (phpunit.xml converts deprecations to exceptions) and can mask other failures. Prefer asserting the expected deprecation explicitly, or migrate this test to get()/has() for non-deprecated behavior.

Copilot · 2026-04-25T02:17:24Z

+        $request = @new RequestPSD2('14845551212', 'Test Verify', '5.25');
        $response = @$this->client->requestPSD2($request);
    }


This uses @ to suppress deprecation exceptions triggered by RequestPSD2 and requestPSD2(). Since PHPUnit converts deprecations to exceptions, please assert the expected deprecations explicitly (or migrate the test to StartPSD2/startPsd2Verification). Silencing with @ makes the test less trustworthy.

Co-authored-by: Copilot <copilot@github.com>

@throws

- Fix @throws docblocks in Verify/Client: startVerification(), startPsd2Verification(), triggerNextEvent() were using ClientException\Request / ClientException\Server; correct class names are RequestException / ServerException - Fix error message in StartVerification::setNextEventWait() and StartPSD2::setNextEventWait(): validation already allowed up to 3600s but message incorrectly said 900s - Fix UPGRADE-5.0.md: CheckAttempt property mapped as $date; actual name is $dateReceived - Remove duplicate $mockClient creation in Conversion/ClientFactoryTest Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

dragonmantank and others added 3 commits April 24, 2026 21:33

Stopgap before checking Verify backports

42924d1

Checked and cleaned up some of the Verify backports

a9f1da1

Co-authored-by: Copilot <copilot@github.com>

Updated migration guide

d68c860

dragonmantank requested review from SecondeJK, Copilot and manchuck April 25, 2026 02:08

Copilot started reviewing on behalf of dragonmantank April 25, 2026 02:08

View session

Removed readonly class from CheckAttempt

1c0534c

Copilot AI reviewed Apr 25, 2026

View reviewed changes

Fixes for phpstan

26ec0a2

Co-authored-by: Copilot <copilot@github.com>

manchuck approved these changes Apr 27, 2026

View reviewed changes

manchuck approved these changes May 26, 2026

View reviewed changes

manchuck approved these changes Jun 4, 2026

View reviewed changes

dragonmantank merged commit 565b55d into main Jul 15, 2026
12 checks passed

dragonmantank deleted the 4.99-beta branch July 15, 2026 04:23

Navigation Menu

Repository navigation

4.99 beta - #555

4.99 beta#555
dragonmantank merged 6 commits into
mainfrom
4.99-beta

dragonmantank commented Apr 25, 2026

Uh oh!

codecov-commenter commented Apr 25, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI Apr 25, 2026

Uh oh!

manchuck Jun 4, 2026

Uh oh!

Copilot AI Apr 25, 2026

Uh oh!

Uh oh!

Copilot AI Apr 25, 2026

Uh oh!

Copilot AI Apr 25, 2026

Uh oh!

Copilot AI Apr 25, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		$api = @$this->factory->getApi('test');
		$this->assertSame($this->client, $api->client);

Conversation

dragonmantank commented Apr 25, 2026

Description

Motivation and Context

How Has This Been Tested?

Example Output or Screenshots (if appropriate):

Types of changes

Checklist:

Uh oh!

codecov-commenter commented Apr 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ JUnit XML file not found

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

Uh oh!

manchuck Jun 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

codecov-commenter commented Apr 25, 2026 •

edited

Loading