Development

Bibliothèque client SMS API PHP pour tutoriel sur applis Web

Ce tutoriel passe en revue toutes les étapes de configuration d’une application Web PHP complète et l’utilisation de la bibliothèque client de l’API Infobip .

August 23 2017

Si vous développez une application Web à l’aide de PHP et souhaitez y intégrer la fonctionnalité SMS, vous êtes au bon endroit. Nous avons mis sur pied une bibliothèque client de l’API Infobip pour vous aider et nous avons rédigé ce tutoriel pour vous guider à chaque étape. De cette façon, nous avons simplifié davantage l’intégration de cette fonctionnalité. Nous avons en outre amélioré la sécurité de votre site Web grâce à notre solution 2FA, étant donné que tous les appels et la sérialisation du modèle API HTTP s’effectuent dans notre bibliothèque.

Ce guide détaillé est une version améliorée de notre précédent tutoriel sms php api, rédigé en vue d’accélérer l’intégration des fonctionnalités SMS dans votre application Web. Vous aurez à franchir trois étapes essentielles, chacune décrite dans une section distincte. Tout d’abord, nous procéderons à l’envoi des SMS, puis à la récupération des journaux de messages et enfin à la réception des rapports d’envoi.

La page d’index est liée à ces trois pages de fonctionnalités afin de faciliter votre navigation.

est liée à ces trois pages de fonctionnalités afin de faciliter votre navigation. Vous devez configurer le serveur PHP pour assurer le bon fonctionnement de votre application Web SMS. Étant donné que la bibliothèque client adresse des demandes HTTP à Infobip API, vous devrez activer l’extension cURL PHP sur votre serveur Web.

Pour exécuter l’application, vous pouvez utiliser quelques-unes des multiples solutions AMP (wamp, xampp, ...). Il s’agit de piles logicielles pour divers systèmes d’exploitation constituées d’un serveur Web Apache, d’une base de données MySQL et d’un support de langage de programmation PHP. Vous devez activer l’extension phpcurl pour la solution que vous avez choisie.

Nous vous conseillons d’installer le composer – il s’agit d’un outil simple qui vous aidera à résoudre les dépendances des projets PHP et à simplifier le processus de téléchargement et d’utilisation par le client de l’API Infobip utilisé dans ce projet. Vous pouvez retrouver les instructions détaillées sur le processus d’installation du composer sur leur site Web et dans ce blog, nous y couvrirons la partie pratique.

Remarque: Pour garantir un envoi sécurisé des SMS, ces exemples doivent être hébergés sur HTTPS (en utilisant TLS) lors de la diffusion. Par souci de simplicité, nous avons utilisé le HTTP simple dans ce tutoriel.

CLIENT DE L’API INFOBIP

Pour utiliser la bibliothèque client de l’API Infobip vous devez la télécharger dans votre projet. Pour faciliter ce processus, nous vous recommandons d’utiliser le composer. Avec cela, il vous suffit de définir une version du client que vous souhaitez utiliser. Ceci se fait dans un fichier spécial nommé composer.json:


{
  "require": {
	"infobip/infobip-api-php-client": "2.0.1"
  }
}

Lorsque le fichier composer.jsonest en place, vous pouvez demander au composer de récupérer les dépendances de la liste en exécutant la commande suivante du terminal:

composer install

Vous devez à présent apercevoir un dossier nommé « fournisseur » à côté du fichier composer.json file. Si vous l’ouvrez, vous y trouverez un fichier nommé autoload.php qui vous sera utile plus tard. En outre, le dossier « fournisseur » possède des sous-dossiers distincts réservés au code de la bibliothèque client de l’ API Infobip et ses dépendances.

ENVOYER UN SMS

La page complète de messages texte ( advancedSms.php ) contient le formulaire de saisie d’envoi d’un SMS. Les champs requis sont le nom d’utilisateur, le mot de passe et le numéro de téléphone de destination ; toutes les autres valeurs sont facultatives. Pour des détails supplémentaires concernant le type de contenu de l’URL et les données de rappel, référez-vous à la section Recevez un rapport de livraison. Le bouton Envoyez permet d’envoyer la demande à une page spécifiée dans l’attribut d’action du formulaire. Dans cet exemple, il s’afficheraautomatiquement.

form action="<?php echo htmlspecialchars($_SERVER["PHP_SELF"]); ?>" method="POST" ... 

Avant d’effectuer un appel API, vous devez vérifier que l’utilisateur a envoyé tous les champs nécessaires. Dans cet exemple, nous avons uniquement vérifié le champ toInput. Vous n’êtes pas obligé de tous les vérifier, car toutes les options ne sont pas requises par API et celles manquantes seront simplement ignorées par le client. Si vous chargez la page pour la première fois, notez que ces champs ne seront pas disponibles.

UTILISATION DE LA BIBLIOTHÈQUE CLIENT DE L’API INFOBIP

Nous utiliserons le client de l’API Infobip pour formuler des demandes HTTP. Cela réduira considérablement le code; cependant, vous devez d’abord demander l’emplacement des classes nécessaires au PHP. Cela se fait par la demande du fichier autoload.php du dossier « fournisseur » ci-dessus mentionné, puis par la spécification des parties de la bibliothèque client à utiliser :


      require_once __DIR__ . '/vendor/autoload.php';
 
use infobip\api\client\SendMultipleTextualSmsAdvanced;
use infobip\api\configuration\BasicAuthConfiguration;
use infobip\api\model\Destination;
use infobip\api\model\sms\mt\send\Message;
use infobip\api\model\sms\mt\send\textual\SMSAdvancedTextualRequest;

Ne vous souciez pas de la plupart de ces classes, nous les verrons bientôt en action. La première chose à faire est d’obtenir une instance de SendMultipleTextualSmsAdvanced client. Vous pouvez l’obtenir en lui attribuant un objet de configuration de l’authentification.


$configuration = new BasicAuthConfiguration($_POST['username'], $_POST['password'], 'http://api.infobip.com/');
$client = new SendMultipleTextualSmsAdvanced($configuration); 

Notez le dernier paramètre du constructeur BasicAuthConfiguration et son utilisation du protocole http. Cela se fait uniquement par souci de simplicité. Lors de la mise en œuvre de production, vous devez complètement ignorer ce paramètre. Dans ce cas, l’objet de configuration par défaut sera l’utilisation du https. Lisez la remarque contenue dans la section introductive.

Vous avez à présent un $client qui peut effectuer des demandes pour vous. Il se chargera, à votre place, de la conversion des requêtes en fichiers JSON, la configuration et l’exécution des requêtes http et l’analyse des réponses de l’API. Il vous reste juste à remplir le formulaire de demande et à afficher la réponse pour l’utilisateur.

FORMULATION DE LA DEMANDE

De manière générale, le client API vous permet d’envoyer divers messages texte en une seule demande, et chacun à plusieurs numéros de téléphone. Dans cet exemple, nous enverrons un message texte à une seule destination. Vous aurez besoin de trois objets pour formuler la demande. Nous commencerons par la destination:

    
$destination = new Destination();
$destination->setTo($_POST['toInput']);
$destination->setMessageId($_POST['messageIdInput']);

L’option « à » renvoie au numéro de téléphone du destinataire du message, tandis que l’identificateur du message est un peu plus complexe. Cette option sera utilisée plus tard pour identifier uniquement le sms, par exemple lors de l’extraction des journaux à cet effet. Nous verrons son utilisation dans la section Récupérez les journaux de messages de ce tutoriel. Notez que lorsque l’option « à » est requise, l’identificateur de message ne l’est pas, et le sms sera envoyé avec succès, même s’il n’est pas réglé. Dans ce cas, le client API génère un identificateur de message aléatoire que vous recevrez dans la réponse à cette demande.

Le modèle suivant renvoie au message proprement dit. Il vous permet de définir plusieurs destinations, auxquelles sera envoyé le même texte. Vous pouvez passer un tableau avec une seule destination:

$message = new Message();
$message->setDestinations([$destination]);
$message->setFrom($_POST['fromInput']);
$message->setText($_POST['textInput']);
$message->setNotifyUrl($_POST['notifyUrlInput']);
$message->setNotifyContentType($_POST['notifyContentTypeInput']);
$message->setCallbackData($_POST['callbackDataInput']);

Les options « de » et « texte » renvoient à une partie du sms visible pour le destinataire du message. Plus précisément, « de » s’affichera comme expéditeur du message et « texte » évidemment comme texte envoyé. D’autre part, notifyUrl, notifyContentType et callbackData sont des méta-options utilisées pour générer le rapport de livraison et vous le renvoyer. Vous trouverez plus d’informations sur les rapports de livraison dans la section Recevoir un rapport de livraison.

Enfin, vous entrez le message dans un formulaire de demande:

$requestBody = new SMSAdvancedTextualRequest();
$requestBody->setMessages([$message]);

AFFICHAGE DE LA RÉPONSE

Avec $requestBody et $client ready, vous pouvez demander au $client d’exécuter la demande et d’analyser la réponse avec une seule ligne:

$response = $client->execute($requestBody);

Il est important de gérer tous les cas exceptionnels et d’informer l’utilisateur de tout ce qui se passe avec nos applications. Il s’agit, dans ce cas, de gérer correctement les appels API réussis et échoués. Vous pouvez y parvenir en utilisant la méthode d’appel $client->execute dans un bloc try/catch. D’un point de vue schématique, cela devrait se présenter ainsi:

try {
   $apiResponse = $client->execute($requestBody);
   // display results
} catch (Exception $apiCallException) {
   // display the error message
}

Pour afficher les résultats, répétez le processus dans l’ensemble des réponses de messages envoyés avec une boucle foreach et produisez une seule rangée pour chacun des messages envoyés. Nous avons choisi de présenter dans notre exemple : l’identificateur de message, smsCount, le statut, mais vous pouvez choisir ce qui vous convient. Le code doit se présenter de la manière suivante:

<?php $messages = $apiResponse->getMessages(); foreach ($messages as $message) { echo ""; echo "" . $message->getMessageId() . ""; echo "" . $message->getTo() . ""; echo "" . $message->getStatus()->getGroupId() . ""; echo "" . $message->getStatus()->getGroupName() . ""; echo "" . $message->getStatus()->getId() . ""; echo "" . $message->getStatus()->getName() . ""; echo "" . $message->getStatus()->getDescription() . ""; echo "" . $message->getSmsCount() . ""; echo ""; } ?>

Remarque : Dans cet exemple, nous envoyons un seul message à une destination, afin que la réponse du message envoyé ne contienne qu’un seul élément et nul besoin de la boucler. Toutefois, si vous décidez d’envoyer un message à plus d’une destination, vous devez répéter le processus dans l’ensemble des réponses. Si l’exception se produit, voici comment vous pouvez présenter un message d’erreur détaillé à l’utilisateur:

 
    

Le code ci-dessus essayera d’interpréter la réponse d’erreur de l’API et même en cas d’échec, imprimera n’importe quel message contenu dans $apiCallException.

Voilà donc le code complet dont vous aurez besoin pour envoyer un message ! Vous avez maintenant une application entièrement fonctionnelle pour envoyer des messages. Vous pouvez obtenir un code complet à advancedSms.php.

RÉCUPÉRATION DES JOURNAUX DE MESSAGES

La page des journaux des messages envoyés (logs.php) vous sert à récupérer les journaux des messages envoyés et à voir vos utilisateurs. Elle contient un formulaire de saisie des références nécessaires pour récupérer les journaux à partir de l’API Infobip. De plus, elle permet à l’utilisateur de filtrer tous les journaux disponibles, soit par le numéro de téléphone du destinataire, soit par l’identificateur de message exact. En appuyant sur le bouton « Envoyez », la page AFFICHERA ces champs.

UTILISATION DE LA BIBLIOTHÈQUE CLIENT DE L’ API INFOBIP

Comme nous l’avons fait dans le chapitre Envoyez des sms, nous devrons utiliser quelques classes provenant de la bibliothèque client de l’API. Cette fois-ci, les instructions d’utilisation vont se présenter de la manière suivante:


    require_once __DIR__ . '/vendor/autoload.php';
 
use infobip\api\client\GetSentSmsLogs;
use infobip\api\configuration\BasicAuthConfiguration;
use infobip\api\model\sms\mt\logs\GetSentSmsLogsExecuteContext;
And again, you can instantiate a client object by passing the authentication configuration to it's constructor:
$configuration = new BasicAuthConfiguration($_POST['username'], $_POST['password'], 'http://api.infobip.com/');
$client = new GetSentSmsLogs($configuration);

Une fois de plus, vous pouvez laisser le dernier paramètre du constructeur de BasicAuthConfiguration dans votre code de production. Lisez la remarque contenue dans la section Introduction.

CRÉATION DU CONTEXTE D’EXÉCUTION

Contrairement au chapitre précédent où vous envoyiez les données à l’API Infobip, dans le cas présent, nous nous intéressons principalement à l’extraction des données de l’API. Toutefois, il est possible que vous souhaitiez encore filtrer les journaux récupérés en fonction de certaines propriétés. Par exemple, vous voudrez peut-être récupérer 20 journaux envoyés à un numéro de téléphone spécifique. Vous pouvez spécifier ces paramètres de filtrage à l’aide de GetSentSmsLogsExecuteContext model:

 
$context = new GetSentSmsLogsExecuteContext();
$context->setMessageId($_POST['messageIdInput']);
$context->setTo($_POST['toInput']);
$context->setLimit(20);

AFFICHAGE DE LA RÉPONSE

Comme dans le chapitre précédent, nous souhaitons gérer à la fois les appels API réussis et rejetés. Une fois de plus, vous pouvez utiliser le bloc try-catch pour terminer l’appel à $client->execute et gérer l’exception potentielle dans le bloc catch:


try {
   $apiResponse = $client->execute($context);
   // display results
} catch (Exception $apiCallException) {
   // display the error message
}

Si tout s’est bien passé et que l’appel de l’API a réussi, vous pouvez répéter le processus dans l’ensemble des résultats renvoyé par l’API via une boucle foreach. La boucle est nécessaire dans ce cas, car nous avons demandé de récupérer plusieurs journaux de messages. Pour chaque journal, vous devez extraire les informations requises et les présenter à votre utilisateur dans une rangée de tableau. Nous avons choisi dans notre exemple : l’identificateur du message, le destinataire, l’expéditeur, le message, le statut et sentAtproperties. Comme précédemment, vous pouvez choisir tout ce qui vous convient. Notre code se présente comme suit:


    <?php
$logs = $apiResponse->getResults();
foreach ($logs as $log) {
	echo "";
	echo "" . $log->getMessageId() . "";
	echo "" . $log->getTo() . "";
	echo "" . $log->getFrom() . "";
	echo "" . $log->getText() . "";
	echo "" . $log->getStatus()->getGroupName() . "";
	echo "" . $log->getStatus()->getDescription() . "";
	$formattedSentAt = $log->getSentAt()->format("M d, Y - H:i:s P T");
	echo "" . $formattedSentAt . "";
	echo "";
} ?>

Enfin, vous pouvez gérer l’exception de la même manière que dans la section précédente:


Une fois de plus, vous pouvez obtenir le code complet relatif à cette page à logs.php.

RÉCEPTION DE L’ACCUSÉ DE RÉCEPTION

Cette fonctionnalité est légèrement différente des deux précédentes: la page dlrPush.php n’est pas faite pour la demande de données, mais plutôt pour la réception de celles-ci. Lorsque les données sont envoyées à cette page, elles peuvent être analysées et présentées de manière appropriée à l’utilisateur.

Remarque : Pour voir ces rapports de livraison dans la démonstration panoramique, vous devez les déplacer de la page complète des messages texte en saisissant l’URL de la page dlrPush.php dans le champ indiqué pour cette adresse URL. Le champ Notify ContentType dans cette page définit également le type de corps à recevoir.

RÉCEPTION DU RAPPORT DE LIVRAISON ENVOYÉ

   
$responseBody = file_get_contents('php://input');
if ($responseBody) {
	file_put_contents("dlr.txt", $responseBody);
} else {
	$fileBody = file_get_contents("dlr.txt");
	if ($fileBody <> "") {
    	if (isJson($fileBody)) {
        	$responseJson = json_decode($fileBody);
        	$results = $responseJson->results;
    	} else if (strpos(trim($fileBody), '') === 0) {
        	$responseXml = simplexml_load_string($fileBody);
        	$results = $fileBody->results->result;
    	}
	}
}

Le code ci-dessus indique que la méthode file_get_contents(’php://input’) est utilisée pour obtenir les données brutes du POST comme une série. Ces données brutes du POST constituent le rapport de livraison provenant d’Infobip et sont sauvegardées localement dans dlr.txt file withfile_put_contents("dlr.txt", $responseBody). Un autre bloc utilise le corps de requête enregistré dans le fichier et vous montre comment vérifier si les données sont interprétées comme XML ou JSON, et comment récupérer les rapports de livraison envoyés. Pour XML, nous vérifions si la série du corps de la réponse démarre, sinon, essayez de la décoder sans erreur – la fonction isJson (). Si toutes les conditions sont FAUSSES, la variable $résultat reste indéfinie, ce qui signifie que nous devons informer l’utilisateur qu’aucun rapport de livraison n’a été envoyé au serveur de rappel.

Vous devez noter que la gestion des données via un fichier est utilisée afin que cette démonstration panoramique puisse afficher les messages reçus et envoyés au même moment, en réutilisant la même page. L’enregistrement sur le fichier se produit à l’arrivée du rapport de livraison, tandis que la lecture se produit lorsque la page est demandée par la requête GET du navigateur. Chaque nouveau rapport de livraison remplacera le précédent afin que seul le tout dernier soit affiché. Le rapport de livraison est également visible par tous les visiteurs de la page, indépendamment de l’utilisateur qui est à l’origine du message initial. Dans l’application grade production, vous pouvez avoir besoin d’enregistrer chaque rapport sans réécrire les précédents et ne montrer les rapports qu’aux utilisateurs qui sont autorisés à les voir.

INTERPRÉTATION DU RÉSULTAT

L’analyse des rapports de livraison envoyés est proche de l’analyse de la réponse des messages envoyés et des méthodes de journalisation des messages envoyés, sauf que nous ne vérifions pas le code de réponse HTTP (car il n’y a aucune réponse). Tout ce que nous faisons, c’est choisir les informations tirées des rapports de livraison envoyés que nous voulons afficher et les écrire sur la page.

Par l’ingénieur software et chef d’équipe Josip Antolis

DÉVELOPPEZ VOTRE APPLICATION WEB AUJOURD’HUI

COMMENCEZ DÈS MAINTENANT