Envoyer des messages Viber en Unicode grec avec Symfony

J'adore le caractère aléatoire des choses que l'on découvre dans le cadre de Developer Advocacy. Cette découverte particulière est le fruit d'une conversation que j'ai eue lors de la conférence We Are Developers à Berlin cette année. Il s'avère que les messages officiels du gouvernement grec sont envoyés en utilisant ViberAccount une part significative de 4,55 % du marché de la messagerie mobile. J'ai eu un déclic : Vonage prend en charge Viber dans l Messages APIAlors pourquoi ne pas montrer un exemple d'envoi d'un message Unicode à l'aide de PHP vers un appareil Viber ? Et c'est exactement ce que nous allons faire, en partant de zéro.

Nous allons utiliser le Symfony Framework pour ce tutoriel, mais au lieu de suivre le processus d'installation décrit dans les documents Symfony, j'ai adopté une approche légèrement différente. Neal Brooks m'a aidé en créant ce dépôt qui permet de démarrer un framework complet en une seule commande !

Pour commencer

Passons aux choses sérieuses et démarrons d'abord l'application. Comme nous utilisons Docker pour cette application, vous devrez d'abord installer Docker sur votre plateformeet vous devrez avoir installé le contrôle de version git version control installé. Une autre étape nécessaire (qui sera plus pertinente pour les utilisateurs de Windows que pour les environnements Linux ou Mac) est de s'assurer que GNU Make est installé.

Clonez le dépôt suivant à partir de votre ligne de commande :

Nous utilisons maintenant make pour construire l'application :

La commande aura deux effets :

• Téléchargez et installez toutes les dépendances de la dernière version de Symfony, qui se trouve dans le dossier app (c'est le code source de votre application maintenant).

• Démarrez l'environnement Docker en utilisant docker compose up ce qui fera apparaître le conteneur Symfony PHP exécutant PHP8.2, Postgres, Node, et Nginx comme serveur web.

Parce que nous allons être super paresseux, nous allons également utiliser une commande pour ouvrir notre application dans le navigateur :

Welcome to Symfony!

Installer les dépendances et configurer

Nous sommes prêts ! Commençons maintenant à développer. La première chose que nous allons faire est d'ajouter le Vonage PHP SDK comme dépendance de l'application Symfony, en utilisant Composer. Nous pouvons utiliser le makefile pour le faire à l'intérieur du conteneur PHP.

Ce que nous allons faire avec l'application, c'est simuler un webhook entrant via une route exposée, puis envoyer le message contenu dans cette charge utile à un numéro via Viber. Quelques étapes sont nécessaires pour que cela fonctionne : tout d'abord, vous aurez besoin d'un Account Vonage.

Ensuite, nous devons créer une application Vonage, avec la capacité Messages. Nous pouvons le faire via le tableau de bord de Vonage :

Creating an Application in the Vonage Dashboard

Ne vous préoccupez pas des webhooks Messages pour les URLs entrantes - nous ne sommes pas intéressés par les rappels d'état ou les messages entrants dans le cadre de cet article. Lors de la création de l'application, vous pouvez mettre des URL factices dans la configuration du webhook car ce sont des champs obligatoires.

Les pièces les plus importantes dont vous aurez besoin sont les suivantes :

• Votre numéro d'identification de la demande

• Les private.key est téléchargé depuis le bouton Generate public and private key sur ce tableau de bord, et placées dans le dossier racine de Symfony (c.-à-d. app)

Après avoir cliqué sur 'Generate Application', nous avons besoin de pouvoir récupérer notre configuration en utilisant le Config Builder de Symfony. Nous allons les configurer en tant que paramètres, car c'est la forme la plus simple pour obtenir les valeurs globales de l'application.

Créez un nouveau fichier, vonage.yamlet placez-le dans app/config/packages. Dans ce fichier, nous placerons nos clés :

parameters:  
  application_id: '99996908-65ec-XxXx-a640-f5f4a999a3b9'  
  private_key_path: '%kernel.project_dir%/private.key'

Veillez à remplacer la valeur fictive que j'ai donnée pour application_id par la valeur correcte de l'Applications Vonage que vous avez générée via le tableau de bord. Avec ces paramètres définis, vous serez en mesure d'accéder à leurs valeurs de n'importe où dans Symfony en utilisant l'option ParameterBag (nous y reviendrons plus tard).

Utilisation de l'Environnement de test des messages

Lorsque le tableau de bord est ouvert, nous allons configurer le compte que nous allons utiliser pour la plateforme Viber Business Messages. Plutôt que de passer par le processus de configuration de votre propre compte Viber Business Messages, nous utiliserons un compte préprovisionné disponible dans l'espace de travail de Messages Sandbox.

Avant de configurer l'Environnement de test, vous devez disposer de l'application Viber installée sur votre téléphone. Téléchargez l'application et suivez la procédure complète.

L'étape suivante consiste à mettre sur liste d'autorisation le numéro associé à votre Account Viber pour l'Environnement de test des messages. Pour ce faire, accédez à l'espace de stockage des messages dans le tableau de bord. Messages Sandbox dans le tableau de bord. Vous pouvez y accéder à l'aide du menu Troubleshoot & Learn > Developer Tools > Messages Sandbox. Cliquez sur le lien "Ajouter à l'Environnement de test" dans la carte Viber, et suivez les instructions données pour inscrire votre numéro sur la liste des comptes Viber de l'Environnement de test. Puisque nous utilisons le compte Sandbox préprovisionné, la marque Vonage sera présente dans les messages de ce compte.

Routage

Maintenant que le compte Sandbox est configuré, nous allons créer la route dans Symfony qui déclenchera le message. Nous allons le faire à l'intérieur du conteneur Docker (à condition d'être un niveau au-dessus du répertoire app où se trouve tout le code source) :

Vous serez invité à nommer votre contrôleur. Appelons-le MessengerController. La console fera le reste pour vous, vous pouvez le voir avec les deux codes qu'elle génère :

namespace App\Controller;  
  
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;  
use Symfony\Component\HttpFoundation\Response;  
use Symfony\Component\Routing\Annotation\Route;  
  
class MessengerController extends AbstractController  
{  
    #[Route('/messenger', name: 'app_messenger')]  
    public function index(): Response  
    {  
        return $this->render('messenger/index.html.twig', [  
            'controller_name' => 'MessengerController',  
        ]);    
	}
}        

Vous pouvez dès à présent accéder au nouvel itinéraire à partir de votre navigateur :

Symfony's default controller template

Notre route va se comporter davantage comme une route d'API REST que comme une route d'application web. Nous devons donc la spécifier en tant que POST et lui faire renvoyer du JSON. Mettons à jour le code pour cela :

#[Route('/messenger', name: 'app_messenger', methods: ['POST'], format: 'json')] 
public function index(): Response  
{ 
    return new JsonResponse(['message_success' => true]);  
}

Trois choses ont changé ici pour obtenir une réponse :

• L'annotation Route a été modifiée pour autoriser uniquement les POST uniquement.

• L'annotation Route précise également que seuls les messages application/json peuvent être envoyées à ce point d'accès

• Nous renvoyons maintenant un JsonResponse objet.

Vous pouvez maintenant essayer d'atteindre le point de terminaison avec un outil de test d'API tel que Postman. Ici, j'ai choisi d'utiliser Insomnie:

Using Insomnia to test our Application

OK, nous avons un cycle de vie requête/réponse qui fonctionne. C'est excellent. Il est temps d'assembler le reste du puzzle.

Vous avez peut-être remarqué que nous envoyons un message dans la charge utile JSON - et, comme promis, elle est en Unicode grec ! Donc, la première chose à faire est d'extraire cette chaîne de caractères. En utilisant l'injection de dépendance de Symfony, nous allons ajouter l'objet Request dans la méthode du contrôleur, ce qui nous donnera accès à l'ensemble de la requête :

use Symfony\Component\HttpFoundation\Request;

#[Route('/messenger', name: 'app_messenger', methods: ['POST'], format: 'json')] 
public function index(Request $request): Response  
{ 
    return new JsonResponse(['message_success' => true]);  
}

Maintenant, nous pouvons extraire une clé dans la charge utile de la requête nommée message:

use Symfony\Component\HttpFoundation\Request;

#[Route('/messenger', name: 'app_messenger', methods: ['POST'], format: 'json')] 
public function index(Request $request): Response  
{ 
	$message = $request->getPayload()->get('message');
	
    return new JsonResponse(['message_success' => true]);  
}

Utiliser Vonage

Nous avons donc configuré notre message et notre requête/réponse. Il est temps d'intégrer le Vonage Client SDK dans notre contrôleur, le client de base étant configuré avec les informations d'identification que nous avons définies dans la configuration de Symfony. Nous utilisons un objet appelé ParameterBag pour obtenir ces informations d'identification. Pour accéder à cette classe, il faut l'injecter dans le constructeur du contrôleur :

public function __construct(  
    protected ParameterBagInterface $parameterBag,  
) {}

Vous pouvez désormais y accéder en utilisant $this->parameterBag. Extrayons ce dont nous avons besoin :

use Symfony\Component\HttpFoundation\Request;

#[Route('/messenger', name: 'app_messenger', methods: ['POST'], format: 'json')] 
public function index(Request $request): Response  
{ 
	$message = $request->getPayload()->get('message');

	$privateKey = file_get_contents($this->parameterBag->get('private_key_path'));
	$applicationId = $this->parameterBag->get('application_id');
	
    return new JsonResponse(['message_success' => true]);
}

Maintenant que nous avons les deux paramètres requis pour nos informations d'identification Vonage, nous pouvons les utiliser comme arguments pour créer un objet Vonage\Credentials\Keypair et passer ensuite cet objet lors de l'instanciation d'un nouveau Vonage Client:

use Symfony\Component\HttpFoundation\Request;

#[Route('/messenger', name: 'app_messenger', methods: ['POST'], format: 'json')] 
public function index(Request $request): Response  
{ 
	$message = $request->getPayload()->get('message');

	$privateKey = file_get_contents($this->parameterBag->get('private_key_path'));
	$applicationId = $this->parameterBag->get('application_id');
	
	$vonageCredentials = new Client\Credentials\Keypair($privateKey, $applicationId);  
  
	$client = new Client(  
		$vonageCredentials,  
		[
			'base_api_url' => 'https://messages-sandbox.nexmo.com'  
	    ]  
	);
	
    return new JsonResponse(['message_success' => true]);
}

Il est important de noter que l'option Client prend une option supplémentaire, base_api_url. Cette option remplace les paramètres de l'URL de base intégrés au SDK, afin que vous puissiez utiliser le bac à sable de l'API Messages.

Il est temps de créer le message Viber. Vous devrez utiliser un from numéro qui vous est indiqué dans le tableau de bord de Vonage. Vous pouvez voir ce numéro si vous faites défiler vers le bas la page de l'écrin de sable des messages :

You can see the correct 'from' field here

Nous utilisons ce numéro lors de la création de l ViberText objet :

$messageText = 'Καλώς ήρθατε στο Vonage στα Ελληνικά!'
$vonageMessage = new ViberText('44999999999', '22353', $messageText);

La dernière chose à faire est d'envoyer le message, mais il serait préférable que la clé JSON renvoyée soit à la fois précise et défensive. message_success soit à la fois précise et défensive. Voici donc le résultat final, dans son intégralité :

namespace App\Controller;  
  
use Psr\Log\LoggerInterface;  
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;  
use Symfony\Component\DependencyInjection\ParameterBag\ParameterBagInterface;  
use Symfony\Component\HttpFoundation\JsonResponse;  
use Symfony\Component\HttpFoundation\Request;  
use Symfony\Component\HttpFoundation\Response;  
use Symfony\Component\Routing\Annotation\Route;  
use Vonage\Client;  
use Vonage\Messages\Channel\Viber\ViberText;  
  
class MessengerController extends AbstractController  
{  
    public function __construct(  
        protected ParameterBagInterface $parameterBag,  
        protected LoggerInterface $logger  
    ) {}  
  
    #[Route('/messenger', name: 'app_messenger', methods: ['POST'], format: 'json')]  
    public function index(Request $request): Response  
    {  
        $messageText = $request->getPayload()->get('message');  
        $responseData = ['message_success' => false];  
  
		$privateKey = file_get_contents($this->parameterBag->get('private_key_path'));
		$applicationId = $this->parameterBag->get('application_id');
	
		$vonageCredentials = new Client\Credentials\Keypair($privateKey, $applicationId);  
  
		$client = new Client(  
			$vonageCredentials,  
			[
				'base_api_url' => 'https://messages-sandbox.nexmo.com'  
		    ]  
		);
        
        $vonageMessage = new ViberText('44999999999', '22353', $messageText);  
  
        try {  
            $client->messages()->send($vonageMessage);  
            $responseData['message_success'] = true;  
        } catch (\Exception $exception) {  
            $this->logger->error($exception->getMessage());  
        }
        
        return new JsonResponse($responseData);  
    }
}

Il y a quelques points à vérifier dans le code final. Tout d'abord, l'exigence d'un code défensif signifie que nous avons introduit un bloc try-catch. Mais que faisons-nous en cas d'échec, si ce n'est d'envoyer false pour informer le client que le résultat a échoué ? Eh bien, nous pouvons enregistrer la réponse d'erreur. Cela a été fait en utilisant l'injection de dépendance de Symfony pour ajouter la fonction Logger à la classe du contrôleur via le constructeur. Dans ce cas, Symfony est livré avec le bien connu Monolog bien connu configuré dès le départ, de sorte que vous pouvez utiliser le constructeur LoggerInterface ici.

Relancez la demande sur Insomina et...

Greek Viber Messages!

Magique ! Nous avons un message local grec sur Viber !

Conclusion

L'utilisation du SDK PHP de Vonage est conçue pour rendre le temps de développement très rapide, et associée au temps de développement rapide offert par le Symfony Framework, elle constitue un ensemble d'outils puissants entre vos mains. Si vous construisez quelque chose et que vous avez besoin d'aide ou de conseils, faites-le nous savoir en en vous inscrivant à notre communauté Slack.

Ressources complémentaires

Envoi de SMS depuis PHP avec basculement : La boulangerie Cupcake

Type Safety Done Right - PHP Array Hacking (en anglais)

Nettoyer ! Nettoyer votre application PHP avec PHPStan

SDK PHP de Vonage