VAPI-3160: Add <Refer> BXML Verb Support by s-aher · Pull Request #88 · Bandwidth/php-sdk

s-aher · 2026-05-28T12:21:03Z

Summary

Adds support for the new <Refer> BXML verb to the PHP SDK, enabling SIP REFER functionality.

Changes

src/Voice/Bxml/Refer.php — New BXML verb class with builder methods for referCompleteUrl, referCompleteMethod, tag, and nested <SipUri> child element
tests/BxmlTest.php — Added unit tests for <Refer> XML serialization (with all attributes and minimal/no optional attributes)
README.md — Added BXML example and failure-recovery example (no "continue after success" pattern, since the call terminates on success)

Usage Example

<Response>
  <Refer referCompleteUrl="https://example.com/handleRefer" referCompleteMethod="POST">
    <SipUri>sip:alice@atlanta.example.com</SipUri>
  </Refer>
</Response>

Important Notes

Critical asymmetry vs <Transfer>: On success, the call is terminated — the remote SIP endpoint redirects away from Bandwidth entirely. referCompleteUrl should only be used for failure recovery.
ReferCompleteCallback webhook model will be auto-generated from the OpenAPI spec once api-specs PR #2142 is merged.
tag attribute included (pending final confirmation via VAPI-2916).

Checklist

Refer verb model class with builder methods
Nested <SipUri> child element serializes correctly
Unit tests for <Refer> verb XML round-trip
README includes BXML example and failure-recovery example
No "continue after success" examples
SDK does not ship before api-specs PR #2142 is merged

bwappsec · 2026-05-28T12:21:24Z

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

stampercasey

Review from Claude Code — see inline comments for individual findings. Two blockers.

stampercasey · 2026-06-22T14:02:42Z

+
+    /**
+     * @todo Write general description for this property
+     * @var string|null $referSipResponseCode public property


[BLOCKER] referSipResponseCode typed as string|null — should be int|null

SIP response codes are integers (202, 405, 503, etc.). Deserializing a real server payload into this class will leave the value as a string, breaking any comparison like === 202. Every other SDK types this correctly: C# uses int?, Python uses Optional[StrictInt].

Fix:

/** @var int|null $referSipResponseCode The SIP response code for the REFER request (e.g. 202, 405). */ public $referSipResponseCode;

Same issue applies to notifySipResponseCode on line 95.

stampercasey · 2026-06-22T14:02:42Z

+
+    /**
+     * @todo Write general description for this property
+     * @var string|null $notifySipResponseCode public property


[BLOCKER] notifySipResponseCode typed as string|null — should be int|null

Same issue as referSipResponseCode above. The SIP code reported via NOTIFY (e.g. 200, 404, 503) is an integer.

/** @var int|null $notifySipResponseCode The SIP response code from the NOTIFY (e.g. 200, 404). */ public $notifySipResponseCode;

stampercasey · 2026-06-22T14:02:42Z

@@ -236,8 +236,6 @@ public function testSyncTnLookup() {
        $body->phoneNumbers = [getenv("USER_NUMBER")];


[BLOCKER] Two assertions silently removed from testSyncTnLookup — unrelated to this PR

The deleted lines:

$this->assertIsArray($response->getResult()->links); $this->assertInstanceOf(BandwidthLib\PhoneNumberLookup\Models\Link::class, $response->getResult()->links[0]);

…have nothing to do with <Refer>. Removing assertions from an existing integration test to make it pass is a hidden regression. What broke here? If links no longer exists on the response model, that should be a separate PR with an explanation.

stampercasey · 2026-06-22T14:02:42Z

+/*
+ * BandwidthLib
+ *
+ * This file was automatically generated by APIMATIC v3.0 ( https://www.apimatic.io ).


[MINOR] File claims to be auto-generated but is hand-written

The APIMATIC v3.0 header is misleading — this file was written by hand. api-specs#2142 has now merged, so the actual regen job should be run to produce the real generated file (with correct types, proper docstrings, and the APIMATIC serialization scaffolding that matches the rest of the codebase). This placeholder should be replaced by regen output before merge.

stampercasey · 2026-06-22T14:02:42Z

+class ReferCompleteCallback implements \JsonSerializable
+{
+    /**
+     * @todo Write general description for this property


[MINOR] All property docstrings are @todo placeholders

Every property has @todo Write general description for this property. These should describe the field — at minimum mirror the spec language used in the other SDKs (e.g. The outcome of the REFER operation. Either "success" or "failure". for referCallStatus). If this file will be replaced by regen, the stubs are fine as a temporary state, but that should be called out explicitly.

stampercasey · 2026-06-22T14:02:42Z

+     *
+     * @param SipUri $sipUri The SipUri destination for the REFER
+     */
+    public function sipUri(SipUri $sipUri): Refer {


[MINOR] SipUri carries Transfer-specific attributes

The SipUri class exposes transferAnswerUrl, transferAnswerFallbackUrl, uui, username, password, etc. as setters. Any of those set on a SipUri passed here will serialize into the <SipUri> element inside <Refer>, producing malformed BXML — with no warning.

Python introduced ReferSipUri (accepts only uri); C# uses a nested Refer.SipUri class. PHP should follow the same pattern to prevent misuse.

stampercasey · 2026-06-22T14:02:42Z

+            $element->setAttribute("tag", $this->tag);
+        }
+
+        if(isset($this->sipUri)) {


[MINOR] No guard for missing SipUri — produces invalid BXML silently

<SipUri> is required by the spec ("exactly one"). With the current builder pattern, (new Refer())->toBxml($doc) produces <Refer/> — valid PHP, invalid BXML. Consider throwing in toBxml() when $this->sipUri is not set:

if (!isset($this->sipUri)) { throw new \InvalidArgumentException('Refer requires a SipUri child element.'); }

stampercasey · 2026-06-22T14:02:42Z

+        $responseXml = $response->toBxml();
+        $this->assertEquals($expectedXml, $responseXml);
+    }
 }


[MINOR] No tests for ReferCompleteCallback and no test for Refer without SipUri

Two gaps:

ReferCompleteCallback has no test coverage at all — no round-trip JSON test, no scenario tests for the four outcomes (success, REFER rejected, destination unreachable, NOTIFY timeout). Every other SDK has these (Python, Ruby).

No test documenting what (new Refer())->toBxml($doc) produces when SipUri is not set. If a guard is added (see Refer.php comment), this becomes a expectException test.

VAPI-3160: Add Refer BXML implementation and related tests

8b592e0

VAPI-3160: Add Refer BXML implementation and related tests

dfe1f42

s-aher marked this pull request as ready for review June 22, 2026 07:11

s-aher requested review from a team as code owners June 22, 2026 07:11

Copilot started work on behalf of s-aher June 22, 2026 13:13 View session

Fix testSyncTnLookup: remove assertion on empty links array

abf5392

Copilot finished work on behalf of s-aher June 22, 2026 13:14

stampercasey reviewed Jun 22, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

VAPI-3160: Add <Refer> BXML Verb Support#88

VAPI-3160: Add <Refer> BXML Verb Support#88
s-aher wants to merge 3 commits into
mainfrom
VAPI-3160

s-aher commented May 28, 2026 •

edited

Loading

Uh oh!

bwappsec commented May 28, 2026 •

edited

Loading

Uh oh!

stampercasey left a comment

Uh oh!

stampercasey Jun 22, 2026

Uh oh!

stampercasey Jun 22, 2026

Uh oh!

stampercasey Jun 22, 2026

Uh oh!

stampercasey Jun 22, 2026

Uh oh!

stampercasey Jun 22, 2026

Uh oh!

stampercasey Jun 22, 2026

Uh oh!

stampercasey Jun 22, 2026

Uh oh!

stampercasey Jun 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		@@ -236,8 +236,6 @@ public function testSyncTnLookup() {
		$body->phoneNumbers = [getenv("USER_NUMBER")];

Conversation

s-aher commented May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Usage Example

Important Notes

Related

Checklist

Uh oh!

bwappsec commented May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Snyk checks have passed. No issues have been found so far.

Uh oh!

stampercasey left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

s-aher commented May 28, 2026 •

edited

Loading

bwappsec commented May 28, 2026 •

edited

Loading