Utiliser les API de Vonage avec Drupal

Conditions préalables

• PHP 7.3 ou supérieur

• SQLite 3.26 ou supérieur OU MySQL 5.7.8 ou supérieur

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

This tutorial also uses a virtual phone number. To purchase one, go to Numbers > Buy Numbers and search for one that meets your needs.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

Installation de Drupal

Avec l'introduction de Drupal 8, vous pouvez désormais installer Drupal à l'aide de Composerle gestionnaire de paquets de PHP. Composer s'occupera de maintenir votre site web à jour ainsi que toutes les dépendances de notre site web, mais peut également être utilisé pour une installation basique de Drupal. Clonons le dépôt drupal/recommended-project en tant que projet pour réaliser une installation Drupal de base :

$ composer create-project drupal/recommended-project vonage-and-drupal

Composer téléchargera le dépôt et extraira automatiquement les dépendances pour notre application, ce qui, au moment de la rédaction de cet article, extraira Drupal 9.1. Nous pouvons aller dans le répertoire vonage-and-drupal/ et continuer l'installation.

Alors que nous pouvons exécuter Drupal à partir d'un serveur web comme httpd d'Apache ou Nginx, PHP dispose d'un serveur de développement intégré que nous pouvons utiliser. Ouvrez une autre fenêtre de terminal et accédez à l'endroit où nous avons téléchargé le code Drupal, puis démarrez le serveur :

$ php -S localhost:3000 -t web

Ouvrez un navigateur web et visitez http://localhost:3000 pour être accueilli par le formulaire d'installation de Drupal !

Nous utiliserons une installation de base, il faut donc suivre l'assistant d'installation et sélectionner les options suivantes :

1. Choisissez votre langue et cliquez sur "Enregistrer et continuer". Dans le cas présent, nous choisissons la langue par défaut, l'anglais.

2. Sélectionnez le profil d'installation "Standard" et cliquez sur "Enregistrer et continuer".

3. Sélectionnez "SQLite" pour le type de base de données et laissez les autres options par défaut. Cliquez sur "Enregistrer et continuer".

4. Pour "Configurer le site", indiquez le nom du site, l'adresse électronique, le nom d'utilisateur et le mot de passe que vous souhaitez. Cliquez sur "Enregistrer et continuer".

Drupal va terminer l'installation. Vous serez automatiquement connecté et prêt à commencer à jouer !

Si vous utilisez PHP 7.4 ou 8.0, il se peut que vous rencontriez une erreur concernant la version trop basse de SQLite. PHP a dissocié SQLite à partir de la version 7.4 et utilise la version installée sur votre système d'exploitation. Si vous utilisez Ubuntu 18.04 ou des versions plus anciennes de Fedora ou CentOS, il se peut que vous ne puissiez pas installer Drupal 9 en utilisant SQLite. Si vous rencontrez ce problème, vous pouvez envisager d'utiliser MySQL ou MariaDB comme base de données au lieu de SQLite.

Installation des API de Vonage

Maintenant que nous avons une installation de Drupal, nous pouvons décider comment nous voulons interagir avec les API de Vonage. Bien que Drupal puisse effectuer des requêtes HTTP de direction à l'aide de l'interface intégrée \Drupal::httpClient()intégrée, les développeurs devront se préoccuper de déterminer les points de terminaison de l'API, les structures JSON et l'authentification pour chaque requête. Il s'agit de l'option de mise en œuvre la plus difficile.

Vonage fournit une bibliothèque PHP qui peut vous aider avec une grande partie du code de base pour chaque demande. Cette bibliothèque fonctionne pour la plupart des Applications PHP puisque tout ce que vous avez à faire est de créer un objet \Vonage\Client et de fournir vos informations d'identification. Cette bibliothèque fonctionnera parfaitement pour Drupal, mais le point délicat est de faire en sorte que l'objet que vous créez soit accessible au reste du système. Vous devrez écrire un petit module qui pousse le client Vonage dans la couche de service de Drupal.

Pour vous aider, Vonage a créé un module qui fournit une interface d'administration pour ajouter vos informations d'identification, crée le client API de Vonage et l'enregistre avec le système de service. Si vous souhaitez consulter le code source, il est disponible à l'adresse suivante https://github.com/Nexmo/vonage-php-drupal-module. Nous l'avons également rendu disponible en tant que bibliothèque qui peut être installée via Composer, à l'aide de la commande vonage/vonage_drupal.

Puisque nous utilisons Composer pour gérer nos dépendances, nous pouvons retourner dans notre terminal et ajouter le paquet à notre site web :

$ composer require vonage/vonage_drupal

Composer téléchargera quelques dépendances, et vous devriez trouver le module installé dans web/modules/contrib/vonage_drupal. Une fois le téléchargement terminé, nous devons activer le module en allant sur la page "Extend" et en activant le module "Vonage API SDK". Vous pouvez le rechercher ou faire défiler la page jusqu'à la section "Communications". Cochez la case à côté du nom du module et cliquez sur "Installer" Après quelques instants, la page devrait se rafraîchir et vous verrez un message de réussite "Le module Vonage API SDK a été activé" !

Nous pouvons maintenant configurer le module en allant sur la page "Configuration" et en cliquant sur "Vonage API Settings" sous le titre "SYSTEM". Sur cette page, nous pouvons configurer deux ensembles d'informations d'identification que le module utilisera pour configurer notre Client SDK. La plupart des API de Vonage ont tendance à utiliser le secret et la clé de l'API de Vonage, que vous pouvez trouver sur votre tableau de bord Vonage. Si vous utilisez un API qui utilise l'authentification par clé privée comme notre Voice API, vous pouvez développer cette section et entrer l'ID de l'application et la clé privée.

Si vous souhaitez tester vos informations d'identification, vous pouvez utiliser les onglets "Test de l'API SMS de Vonage" ou "Test de l'API Voice de Vonage" sur la page de configuration. En cas de problème, le système devrait renvoyer l'erreur que nous avons rencontrée. Pour l'instant, indiquez votre secret et votre clé API et enregistrez la configuration.

Utilisation du SDK de l'API de Vonage

Le module Drupal Vonage configure automatiquement l'objet client et le rend disponible par l'intermédiaire du système de conteneurs de services Drupal. Cette fonctionnalité signifie que nous pouvons injecter le SDK dans nos modules personnalisés, alors créons un petit module. Nous pouvons utiliser drush pour créer un squelette de module. Exécutez les commandes suivantes pour installer drush pour notre projet, et pour répondre à une série de questions rapides pour créer le module :

$ composer require --dev drush/drush
$ vendor/bin/drush generate module

1. Nom du module : Vonage Hello World

2. Nom de la machine : vonage_hello_world

3. Description du module : Module pour tester l'API de Vonage

4. Paquet : Sur mesure

5. Dépendances : Pas de dépendances, appuyer sur ENTRÉE

6. Répondez "non" à toutes les questions sur la création, sauf :

   1. Vous souhaitez créer un contrôleur ?

Cette commande créera un nouveau module dans web/modules/vonage_hello_worldainsi qu'un nouveau contrôleur dans lequel nous pourrons utiliser le SDK !

Ouvrez web/modules/vonage_hello_world/src/Controller/VonageHelloWorldController.php dans votre éditeur. La première chose à faire pour intégrer le SDK dans le contrôleur est de surcharger la méthode create() . Cette méthode est utilisée par Drupal pour créer n'importe quel contrôleur, et en tant que telle, elle transmet le localisateur de service. Ajoutons une create() surchargeons la méthode :

public static function create(\Symfony\Component\DependencyInjection\ContainerInterface $container) {
    $client = $container->get(\Vonage\Client::class);
    return new static($client);
}

En passant le conteneur comme argument dans la méthode, nous pouvons extraire le client API Vonage du conteneur en utilisant le nom de la classe. En interne, il s'agit d'appeler la fabrique qui prend les informations d'identification que nous avons saisies plus tôt et génère un objet utilisable. Nous pouvons ensuite passer cet objet dans un nouveau contrôleur. En parlant de cela, ajoutons une méthode __construct() qui prend notre nouveau SDK, et une propriété pour le stocker.

protected $client;

public function __construct(\Vonage\Client $client) {
    $this->client = $client;
}

Puisque nous avons utilisé la commande drush pour construire notre module, il a automatiquement ajouté une méthode à notre contrôleur qui est attachée à une route. Nous pouvons modifier la méthode build() et ajouter un appel pour envoyer un SMS à notre téléphone portable. En utilisant l'extrait Envoyer un SMS comme base, nous pouvons utiliser le client que nous avons passé pour envoyer le SMS. Modifiez la méthode build() pour qu'elle ressemble à l'exemple suivant. Veillez à remplacer TO_NUMBER par votre numéro de téléphone mobile, et VONAGE_NUMBER par le numéro que vous avez dans Vonage. Pour s'assurer que Drupal ne met pas la page en cache, nous allons également désactiver la mise en cache de la page chaque fois que quelqu'un accède à cette route.

public function build() {
    \Drupal::service('page_cache_kill_switch')->trigger();

    $response = $this->client->sms()->send(
      new \Vonage\SMS\Message\SMS(
        'TO_NUMBER',
        'FROM_NUMBER', 
        'This was sent from Drupal!'
      )
    );

    $status = $response->current()->getStatus();
    if ($status == 0) {
      $message = "The message was sent successfully";
    } else {
      $message = "The message failed with status: " . $status;
    }
    $build['content'] = [
      '#type' => 'item',
      '#markup' => $this->t($message),
    ];

    return $build;
}

Tout ce qui est nécessaire pour envoyer un SMS à partir de Drupal est installé et configuré. Retournez à l'interface d'administration de Drupal, allez à la page "Extend", trouvez "Vonage Hello World" et cochez la case correspondante. Cliquez sur "Install" pour installer notre module personnalisé. Au bout d'un moment, un message de succès devrait apparaître pour indiquer que nous avons installé notre module.

Par défaut, le drush met en place une route pour notre contrôleur à l'adresse /vonage-hello-world/example. Nous nous rendons à l'adresse http://localhost:3000/vonage-hello-world/example. Nous devrions voir un nœud Drupal normal qui dit "Le message a été envoyé avec succès" et votre téléphone devrait recevoir le message SMS que nous avons configuré dans le contrôleur. Si vous rafraîchissez cette page, le SMS sera à nouveau envoyé puisque nous avons désactivé la mise en cache de la sortie.

Pour en savoir plus

À partir de là, le SDK PHP complet de Vonage est disponible pour que vous puissiez jouer avec vos modules personnalisés. N'hésitez pas à consulter nos extraits de code PHP pour obtenir d'autres exemples de ce que vous pouvez faire avec notre SDK dans presque toutes nos API.

Vous trouverez le code d'exemple de cette démo à l'adresse suivante https://github.com/nexmo-community/vonage-php-sdk-drupal-9.