Annonce de la version 2.2.0 du SDK du serveur PHP

Je suis heureux d'annoncer la sortie de la version 2.2.0 de notre SDK serveur PHP pour les API de Vonage.

Bien qu'il s'agisse d'une version mineure du SDK, elle est remplie de nouvelles fonctionnalités issues de la version 3.0.0 que nous publierons bientôt. Vous pouvez commencer à utiliser la plupart des nouvelles fonctionnalités dès maintenant, tout en conservant l'accès aux capacités existantes fournies par le SDK.

Notre première mise à jour

Une grande quantité de travail a été effectuée pour retravailler de nombreux éléments internes du SDK PHP, mais avec cette refonte, de nombreuses méthodes publiques de l'API du SDK seront modifiées dans la version 3.0.0.

Je connais aussi la douleur d'avoir à travailler avec une base de code existante, et trouver le temps de mettre à jour peut être difficile. Cette version reprend le plus grand nombre possible de changements qui ne sont pas liés à la rétrocompatibilité, y compris la nouvelle interface pour travailler avec notre ancienne API SMS et notre Voice API. Plus d'informations sur ces nouveaux espaces de noms dans un instant.

La version 3.0.0 rendra également obsolètes plusieurs fonctionnalités, y compris de nombreux modes d'accès aux données dans plusieurs de nos API.

Toutes ces dépréciations sont marquées dans le code source par des annotations @deprecated mais nous sommes allés plus loin en vous permettant de voir quelles dépréciations vous utilisez dans les journaux en temps réel.

Il s'agit d'une option facultative, ce qui vous évite d'avoir à vous préoccuper d'un tas d'avis dans vos journaux de production. Il s'agit également d'une fonctionnalité de développement que vous pouvez activer pour afficher des éléments tels que des changements de signature de méthode, des pointeurs vers de nouvelles méthodes ou classes à utiliser, etc. Tout ce que vous avez à faire est d'activer l'option show_deprecations lors de la création du client Nexmo.

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

Une fois cette option activée, vous pouvez exécuter votre application localement et voir quels avis de dépréciation apparaissent ! En fonction de l'API à laquelle vous accédez, il se peut que vous constatiez un grand nombre de dépréciations, mais tous les avis de dépréciation devraient vous indiquer le correctif approprié. Une fois tous les avis de dépréciation résolus, vous devriez également être pleinement compatible avec la version 3.0.0, et cette mise à niveau devrait se faire en toute transparence !

Une liste plus complète des dépréciations est disponible dans les notes de version de sur Githubmais il s'agit d'un aperçu rapide :

• L'accès aux tableaux est obsolète dans toutes les couches de service, telles que messages(), voice(), applications(), etc. Ils sont tous remplacés par des méthodes de recherche réelles.

• Le passage d'un filtre de recherche dans une couche de service, comme applications()est obsolète. Veuillez utiliser les fonctions de recherche/obtention dédiées à chaque couche.

• La plupart des entités ne sont plus accessibles aux tableaux et doivent être modifiées pour utiliser les méthodes d'obtention.

• La plupart des méthodes ne prennent plus de tableaux PHP bruts, pour des raisons de sécurité de type. Les avis de dépréciation vous indiqueront les objets appropriés à utiliser.

• Les conversation() et user() sont obsolètes et seront entièrement supprimées dans la v3.0.0.

• L'ancienne couche Voice de synthèse vocale est obsolète et sera entièrement supprimée dans la version 3.0.0.

• La recherche par SMS est obsolète et sera entièrement supprimée dans la version 3.0.0.

De meilleurs outils de débogage

Je suis très enthousiaste à propos d'une nouvelle fonctionnalité : une meilleure visibilité des demandes et des réponses qui se produisent à travers l'API.

Le SDK actuel, même avec la version 2.2.0, permet d'accéder aux demandes et aux réponses qui se produisent, mais il peut être difficile de savoir quelles entités y ont accès.

Toutes les API (à l'exception de messages() et calls()) disposent désormais d'un gestionnaire d'API intégré qui garde la trace de la dernière demande et de la dernière réponse créées. Vous pouvez interroger le gestionnaire d'API à partir de n'importe quel espace de noms de la couche de service à l'aide de la commande getApiResource() et obtenir une demande ou une réponse compatible avec la compatible avec la PSR-7.

$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();

Nous avons renoncé à obtenir les requêtes et les réponses des entités et des exceptions, et nous recommandons d'obtenir ces informations à partir des espaces de noms des services. La seule exception à cette règle concerne certaines méthodes de recherche plus récentes sur les couches de service, qui renvoient une collection à chargement paresseux. Dans ce cas, le gestionnaire de l'API de la collection possède la requête et la réponse.

// 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();

Certaines API continueront à renvoyer des tableaux dans la version 2.2.0. Il convient donc de vérifier les signatures des méthodes ou d'utiliser la méthode instanceof en cas de doute. Dans la version 3.0.0, presque tous les résultats de recherche auront une interface plus récente.

La nouvelle couche SMS

Beaucoup de nos clients utilisent nos anciennes fonctions SMS. Pendant que nous travaillons sur de nouvelles API comme notre Messages API afin d'offrir encore plus de fonctionnalités de messagerie, cela ne signifie pas que je souhaite laisser nos clients SMS de côté.

À cette fin, l'ensemble de la couche SMS a été remaniée pour inclure un typage strict et une interface entièrement orientée objet. Cela permettra de réduire les erreurs dues à la création de tableaux PHP bruts et de donner une image plus claire des fonctionnalités disponibles pour les messages. J'ai également essayé de conserver l'interface simple que les développeurs attendent de notre SDK.

// 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')
);

L'ancien espace de noms messages() sur le client Nexmo est totalement obsolète dans la version 2.2.0, et le nouvel espace de noms sms() est disponible. Ces deux espaces peuvent être utilisés côte à côte, de sorte que le code existant puisse continuer à utiliser l'ancien espace de noms, et que le nouveau code puisse utiliser le nouvel espace de noms. sms() espace de noms.

J'ai également étendu l'interface du webhook entrant. Comme auparavant, vous pouvez analyser une requête entrante, mais maintenant vous obtenez en retour un objet de type \Nexmo\SMS\Webhook\InboundSMS avec indication de type. Cela devrait rendre beaucoup plus clair la façon d'obtenir les données entrantes par rapport à la gestion des paramètres de requête ou d'un corps de message JSON brut, ou même d'un tableau.

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

La nouvelle couche Voice

L'API Voice est l'une de nos API les plus utilisées, et c'est un autre domaine dans lequel je voulais m'assurer que l'interface était aussi propre que possible.

Pour faire place nette, l'espace de noms calls() a été complètement déprécié en faveur d'une toute nouvelle interface à travers l'espace de noms voice() l'espace de noms.

L'idée était la même que pour la nouvelle couche SMS - fournir une nouvelle interface propre qui facilite les tâches courantes, tout en conservant toute la puissance de notre API Voice et en la développant avec des pratiques PHP modernes. J'ai déjà parlé de certaines de ces interfaces dans d'autres articles, et c'était l'occasion idéale de poncer quelques aspérités.

// 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);

Étant donné que la nouvelle couche voice() est entièrement orientée objet, il n'est plus nécessaire de se rappeler comment construire une structure de tableau pour l'un de nos NCCO ou même pour les appels de base. Toutes les options disponibles sont exposées en tant que méthodes setter sur le nouvel objet \Nexmo\Voice\OutboundCall et l'objet \Nexmo\Voice\OutboundCall prend mieux en charge les différents points de terminaison.

Travailler avec des NCCOs a toujours été un point sensible pour moi. Même si PHP rend trivial la transformation d'un tableau en JSON, me souvenir de toutes les options des NCCOs me renvoie généralement à notre (certes géniale) documentation.

Le SDK est désormais livré avec un constructeur de NCCO qui vous permet de construire vos NCCO avec des objets fortement typés et de générer tout aussi facilement du JSON pour les demandes de NCCO entrantes ou pour les NCCO que vous envoyez dans le cadre d'appels sortants.

$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);

L'API Voice API Voice s'appuie fortement sur les rappels de webhooks, c'est pourquoi cette version introduit également un parseur de webhooks entrants beaucoup plus complet. Cet analyseur est doté de la même interface que notre analyseur de SMS, mais il renvoie des objets relatifs au cycle de vie de l'API Voice.

$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

Mises à jour de Verify

La dernière API majeure à avoir fait l'objet d'une refonte importante est notre API Verify sous l'espace de noms verify() . Cette refonte n'a pas été aussi importante que pour SMS et Voice, mais il y a quelques nouvelles fonctionnalités à connaître.

La première est une façon plus claire de créer une demande de vérification. Celle-ci est désormais gérée par l'objet \Nexmo\Verify\Request qui fournit une interface plus propre pour lancer le processus de vérification.

Cet objet est fortement typé et expose mieux ce que nous attendons d'une demande de vérification que l'objet plus général \Nexmo\Verify\Verification plus général. Pour des raisons de compatibilité ascendante, un objet \Nexmo\Verify\Verification est toujours retourné, mais cela changera dans la version 3.0.0.

// 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);

La vérification, l'annulation et le déclenchement de l'événement suivant sont plus faciles. Il n'est plus nécessaire d'instancier un objet \Nexmo\Verify\Verification ou de le sérialiser et de le transporter via des sessions. La couche de service verify() se contente désormais d'accepter directement l'identifiant de la demande de Verify.

// 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);

Bien qu'il ne s'agisse pas d'un changement majeur, la version 3.0.0 n'acceptera qu'une chaîne de caractères d'identification de la demande au lieu de l'objet, il faut donc en tenir compte.

La promesse d'une mise à niveau plus facile

Tout code compatible avec la version 2.1.0 devrait être immédiatement compatible avec la version 2.2.0 sans aucun changement. Cette version vous donnera simplement la possibilité d'effectuer les mises à jour à votre rythme tout en restant aussi à jour que possible.

A l'avenir, le SDK PHP continuera à être plus formel avec les dépréciations et les chemins de mise à jour afin que vous, le développeur, ayez la possibilité de mettre à jour les changements aussi rapidement et sans douleur que possible.

J'attends avec impatience tout retour d'information, et je vous dis à bientôt pour la sortie de la version 3.0.0 !