Ankündigung der Veröffentlichung von PHP Server SDK Version 2.2.0

Ich freue mich, Ihnen die Veröffentlichung von Version 2.2.0 unseres PHP-Server-SDK für die Vonage APIs bekannt zu geben.

Obwohl es sich um eine kleinere Version des SDK handelt, ist sie vollgepackt mit neuen Funktionen der kommenden Version 3.0.0, die wir in Kürze veröffentlichen werden. Sie können viele der neuen Funktionen sofort nutzen, während Sie weiterhin Zugriff auf die bestehenden Funktionen des SDK haben.

Unser erstes Upgrade-Release

Es wurde viel Arbeit in die Überarbeitung vieler interner Funktionen des PHP SDK gesteckt, aber mit dieser Überarbeitung werden sich auch viele der öffentlichen APIs des SDK in Version 3.0.0 ändern.

Ich weiß auch, wie schmerzhaft es ist, mit einer bestehenden Codebasis arbeiten zu müssen, und es kann schwierig sein, Zeit für ein Upgrade zu finden. Mit dieser Version werden so viele nicht abwärtskompatible Änderungen wie möglich zurückportiert, einschließlich der neuen Schnittstelle für die Arbeit mit unserer alten SMS API und unserer Voice API. Mehr Informationen über diese neuen Namespaces in einem Moment.

Mit Version 3.0.0 werden auch mehrere Funktionen veraltet sein, darunter viele der Möglichkeiten, mit denen auf Daten über viele unserer APIs zugegriffen wird.

Alle diese Verwerfungen sind im Quellcode mit @deprecated Annotationen gekennzeichnet, aber wir sind noch einen Schritt weiter gegangen und haben es Ihnen ermöglicht, in Echtzeitprotokollen zu sehen, welche Verwerfungen Sie verwenden.

Dies ist eine Opt-in-Funktion, so dass Sie sich keine Sorgen über einen Haufen von Meldungen in Ihren Produktionsprotokollen machen müssen. Es handelt sich auch um eine Entwicklungsfunktion, die Sie aktivieren können, um Dinge wie Änderungen der Methodensignatur, Hinweise auf neue Methoden oder zu verwendende Klassen und mehr anzuzeigen. Alles was Sie tun müssen, ist die Option show_deprecations Option zu aktivieren, wenn Sie den Nexmo Client erstellen.

$creds = new \Nexmo\Client\Credentials\Basic(NEXMO_API_KEY, NEXMO_API_SECRET);
$client = new \Nexmo\Client($creds, [
    'show_deprecations' => true
]);

Sobald dies aktiviert ist, können Sie Ihre Anwendung lokal ausführen und sehen, welche Verwerfungshinweise erscheinen! Je nach der API, auf die Sie zugreifen, können Sie eine große Anzahl von Verwerfungen sehen, aber alle Verwerfungshinweise sollten Sie auf die entsprechende Korrektur hinweisen. Sobald alle Verwerfungshinweise beseitigt sind, sollten Sie auch vollständig kompatibel mit Version 3.0.0 sein, und das Upgrade sollte nahtlos erfolgen!

Eine vollständigere Liste der Verwerfungen findet sich in den aktuellen Versionshinweisen auf Githubaber das ist nur ein kurzer Überblick:

• Der Array-Zugriff ist in allen Dienstschichten veraltet, z. B. messages(), voice(), applications()usw. Diese werden alle durch echte Suchmethoden ersetzt.

• Die Übergabe eines Suchfilters an eine Dienstebene, wie applications()ist veraltet. Bitte verwenden Sie die speziellen Such-/Get-Funktionen für jede Schicht.

• Die meisten Entitäten sind nicht mehr als Array zugänglich und sollten auf die Getter-Methoden umgestellt werden.

• Die meisten Methoden nehmen aus Gründen der Typsicherheit keine rohen PHP-Arrays mehr an. Die Hinweise zur Abschaffung der Arrays weisen Sie auf die entsprechenden Objekte hin, die Sie verwenden sollten.

• Die conversation() und user() sind veraltet und werden in Version 3.0.0 vollständig entfernt.

• Die alte Text-to-Speech Voice-Ebene ist veraltet und wird in Version 3.0.0 vollständig entfernt.

• Die SMS-Suche ist veraltet und wird in Version 3.0.0 vollständig entfernt werden.

Bessere Debugging-Tools

Auf eine neue Funktion bin ich besonders gespannt: eine bessere Übersicht über die Anfragen und Antworten, die über die API erfolgen.

Das aktuelle SDK, sogar mit 2.2.0, bietet einen gewissen Zugang zu den Anfragen und Antworten, die passieren, aber es kann schwierig sein zu wissen, welche Entitäten Zugang haben.

Alle APIs (außer messages() und calls()) haben jetzt einen eingebetteten API-Handler, der die zuletzt erstellte Anfrage und Antwort verfolgt. Sie können den API-Handler von jedem Namespace der Dienstebene mit getApiResource() und erhalten eine PSR-7-kompatible Anfrage oder Antwort.

$response = $client->sms()->send(
    new \Nexmo\SMS\Message\SMS(TO_NUMBER, NEXMO_NUMBER, 'A text message sent using the Nexmo SMS API')
);

$lastRequest = $client->sms()->getApiResource()->getLastRequest();
$lastResponse = $client->sms()->getApiResource()->getLastResponse();

Wir haben das Abrufen von Anfragen und Antworten aus Entitäten und Ausnahmen veraltet und empfehlen, diese Informationen aus den Service-Namespaces zu beziehen. Die einzige Ausnahme hiervon sind einige der neueren Suchmethoden auf den Dienstschichten, die eine Lazy-Loading-Sammlung zurückgeben. In diesem Fall verfügt der API-Handler der Sammlung über die Anfrage und die Antwort.

// Returns a lazy-loaded iterable object
$applications = $client->applications()->getAll();
assert($applications instanceof \Nexmo\Entity\IterableAPICollection);

// Start iterating, which fires off an HTTP request
$application = $applications->current();

// Get the request/response
$lastRequest = $applications->getApiResource()->getLastRequest();
$lastResponse = $applications->getApiResource()->getLastResponse();

Einige APIs werden in v2.2.0 weiterhin Arrays zurückgeben, überprüfen Sie also die Methodensignaturen oder verwenden Sie instanceof wenn Sie unsicher sind. In Version 3.0.0 werden fast alle Suchergebnisse eine neuere Schnittstelle haben.

Die neue SMS-Schicht

Viele unserer Kunden nutzen unsere alten SMS-Funktionen. Während wir an neuen APIs wie unserer Messages API arbeiten, um noch mehr Messaging-Funktionen anbieten zu können, heißt das nicht, dass wir unsere SMS-Kunden zurücklassen wollen.

Zu diesem Zweck wurde die gesamte SMS-Schicht überarbeitet, um eine strikte Typisierung und eine vollständig objektorientierte Schnittstelle zu ermöglichen. Dadurch werden Fehler, die durch die Erstellung von PHP-Arrays entstehen, reduziert und die Funktionen, die für Nachrichten zur Verfügung stehen, werden klarer dargestellt. Ich habe auch versucht, die einfache Schnittstelle beizubehalten, die Entwickler von unserem SDK erwarten.

// The old messages namespace
$message = $client->message()->send([
    'to' => TO_NUMBER,
    'from' => NEXMO_NUMBER,
    'text' => 'A text message sent using the Nexmo SMS API'
]);

// The new way
$response = $client->sms()->send(
    new \Nexmo\SMS\Message\SMS(TO_NUMBER, NEXMO_NUMBER, 'A text message sent using the Nexmo SMS API')
);

Der alte messages() Namespace auf dem Nexmo-Client wird in Version 2.2.0 vollständig veraltet sein, und der neue sms() Namespace kann verwendet werden. Diese können nebeneinander verwendet werden, so dass Legacy-Code weiterhin den alten Namensraum und neuer Code den neuen sms() Namespace verwenden kann.

Ich habe auch die Schnittstelle für eingehende Webhooks erweitert. Genau wie zuvor können Sie eine eingehende Anfrage analysieren, aber jetzt erhalten Sie ein vollständig typisiertes \Nexmo\SMS\Webhook\InboundSMS Objekt zurück. Dies sollte es viel klarer, wie die eingehenden Daten im Vergleich zum Umgang mit Query-Parameter oder eine rohe JSON Post Körper, oder sogar ein Array zu erhalten.

$inboundSMS = \Nexmo\SMS\Webhook\Factory::createFromGlobals();
echo $inboundSMS->getFrom() . PHP_EOL;
echo $inboundSMS->getTo() . PHP_EOL;
echo $inboundSMS->getText() . PHP_EOL;

Der neue Voice-Layer

Die Voice API ist eine weitere unserer am meisten genutzten APIs und ein weiterer Bereich, in dem ich sicherstellen wollte, dass die Schnittstelle so sauber wie möglich ist.

Um einen sauberen Schnitt zu machen, wurde der calls() Namespace komplett veraltet zugunsten einer brandneuen Schnittstelle durch den voice() Namespace.

Die Idee war die gleiche wie bei der neuen SMS-Schicht - eine neue, übersichtliche Oberfläche bereitzustellen, die es einfach macht, gängige Aufgaben zu erledigen, und dabei die gesamte Leistungsfähigkeit unserer Voice API beizubehalten und diese mit modernen PHP-Praktiken zu entwickeln. Ich habe mich in anderen Beiträgen über einige dieser Schnittstellen ausgelassen, und dies war die perfekte Gelegenheit, einige Ecken und Kanten abzuschleifen.

// The old way
$call = $client->calls()->create([
    'to' => [[
        'type' => 'phone',
        'number' => TO_NUMBER
    ]],
    'from' => [
        'type' => 'phone',
        'number' => NEXMO_NUMBER
    ],
    'ncco' => [
        [
            'action' => 'talk',
            'text' => 'This is a text to speech call from Nexmo'
        ]
    ]
]);

// The new way
$outboundCall = new \Nexmo\Voice\OutboundCall(
    new \Nexmo\Voice\Endpoint\Phone(TO_NUMBER),
    new \Nexmo\Voice\Endpoint\Phone(NEXMO_NUMBER)
);
$ncco = new NCCO();
$ncco->addAction(new \Nexmo\Voice\NCCO\Action\Talk('This is a text to speech call from Nexmo'));
$outboundCall->setNCCO($ncco);

$response = $client->voice()->createOutboundCall($outboundCall);

Da die neue voice() Schicht objektorientiert ist, muss man sich nicht mehr merken, wie man eine Array-Struktur für einen unserer NCCOs oder sogar grundlegende Aufrufe aufbaut. Alle verfügbaren Optionen werden als Setter-Methoden auf dem neuen \Nexmo\Voice\OutboundCall Objekt, und das \Nexmo\Voice\OutboundCall Objekt hat eine bessere Unterstützung für verschiedene Endpunkte.

Die Arbeit mit NCCOs war schon immer ein wunder Punkt für mich. Obwohl es mit PHP trivial ist, ein Array in JSON zu verwandeln, schickt mich das Erinnern an all die NCCO-Optionen normalerweise zu unserer (zugegebenermaßen großartigen) Dokumentation.

Das SDK wird jetzt mit einem NCCO-Builder ausgeliefert, so dass Sie Ihre NCCOs mit stark typisierten Objekten erstellen und trotzdem genauso einfach JSON für eingehende NCCO-Anforderungen oder NCCOs, die Sie als Teil von ausgehenden Aufrufen senden, generieren können.

$ncco = new \Nexmo\Voice\NCCO\NCCO();
$ncco
    ->addAction(
        new \Nexmo\Voice\NCCO\Action\Talk('Welcome to the amazing Nexmo conference call')
    )
    ->addAction(
        new \Nexmo\Voice\NCCO\Action\Conversation('amazing-conference-call')
    )
;

header('Content-Type: application/json');
$json = json_encode($ncco);
echo($json);

Die Voice API stützt sich in hohem Maße auf Webhook-Rückrufe, so dass mit dieser Version auch ein viel umfassenderer Parser für eingehende Webhooks eingeführt wird. Dieser Parser hat die gleiche Schnittstelle wie unser SMS-Parser, gibt aber Objekte zurück, die sich auf den Lebenszyklus der Voice API beziehen.

$inboundVAPI = \Nexmo\Voice\Webhook\Factory::createFromGlobals();
if ($inboundVAPI instanceof \Nexmo\Voice\Webhook\Event) {
    echo $inboundVAPI->getTo() . PHP_EOL;
    echo $inboundVAPI->getFrom() . PHP_EOL;
    echo $inboundVAPI->getStatus() . PHP_EOL;
    echo $inboundVAPI->getUuid() . PHP_EOL;  
}

if ($inboundVAPI instanceof \Nexmo\Voice\Webhook\Record) {
    echo $inboundVAPI->getRecordingUrl() . PHP_EOL;
}

// And other types can also be returned

Updates verifizieren

Die letzte große API, die ein größeres Refactoring erfahren hat, ist unsere Verify Produkt, das unter dem verify() Namespace. Diese Überarbeitung war nicht so umfangreich wie bei SMS und Voice, aber es gibt ein paar neue Funktionen, die Sie beachten sollten.

Die erste ist eine klarere Art und Weise, einen Überprüfungsantrag zu erstellen. Dies wird nun durch das \Nexmo\Verify\Request Objekt abgewickelt, das eine klarere Schnittstelle zum Starten des Überprüfungsprozesses bietet.

Dieses Objekt ist stark typisiert und gibt besser wieder, was wir für eine Überprüfungsanfrage erwarten, als das allgemeinere \Nexmo\Verify\Verification Objekt. Aus Gründen der Abwärtskompatibilität wird ein \Nexmo\Verify\Verification zurückgegeben, aber das wird sich in v3.0.0 ändern.

// The old way
$verification = new \Nexmo\Verify\Verification(NUMBER, BRAND_NAME);
$client->verify()->start($verification);

// The new way
$request = new \Nexmo\Verify\Request(NUMBER, BRAND_NAME);
$response = $client->verify()->start($request);

Das Prüfen, Abbrechen und Auslösen des nächsten Ereignisses ist einfacher. Man muss nicht mehr ein Objekt instanziieren \Nexmo\Verify\Verification Objekt zu instanziieren oder zu serialisieren und über Sitzungen zu transportieren. Die verify() Serviceschicht übernimmt jetzt nur noch die direkte Annahme der Verify Request ID.

// The old way
$verification = new \Nexmo\Verify\Verification(REQUEST_ID);
$result = $client->verify()->check($verification, CODE);

// The new way
$result = $client->verify()->check(REQUEST_ID, CODE);

Dies ist zwar keine große Änderung, aber in Version 3.0.0 wird nur eine String-Anfrage-ID anstelle des Objekts akzeptiert, so dass man sich dessen bewusst sein sollte.

Das Versprechen leichterer Upgrades

Jeder Code, der mit Version 2.1.0 kompatibel ist, sollte sofort und ohne Änderungen mit 2.2.0 kompatibel sein. Diese Version gibt Ihnen einfach die Möglichkeit, die Upgrades in Ihrer eigenen Zeit zu machen, während Sie immer noch so aktuell wie möglich gehalten werden.

In Zukunft wird das PHP-SDK weiterhin formellere Abkündigungen und Upgrade-Pfade enthalten, so dass Sie, der Entwickler, die Möglichkeit haben, so schnell und schmerzlos wie möglich auf Änderungen zu aktualisieren.

Ich freue mich auf jegliches Feedback und bis bald zur Veröffentlichung der Version 3.0.0!