Uso de las API de Vonage con Drupal

Requisitos previos

• PHP 7.3 o superior

• SQLite 3.26 o superior O MySQL 5.7.8 o superior

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.

Instalación de Drupal

Con la introducción de Drupal 8, ahora puede instalar Drupal utilizando Composerel gestor de paquetes de PHP. Composer se encargará de mantener su sitio web actualizado, así como todas las dependencias de nuestro sitio web, pero también se puede utilizar para instalar una instalación básica de Drupal. Vamos a clonar el repositorio drupal/recommended-project como proyecto para realizar una instalación básica de Drupal:

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

Composer descargará el repositorio y automáticamente bajará las dependencias para nuestra aplicación, que en el momento de escribir esto bajará Drupal 9.1. Podemos movernos al directorio vonage-and-drupal/ y continuar con la instalación.

Mientras que podemos ejecutar Drupal desde detrás de un servidor web como httpd de Apache o Nginx, PHP tiene un servidor de desarrollo incorporado que podemos utilizar. Abra otra ventana de terminal y cd en el que hemos descargado el código de Drupal, y poner en marcha el servidor:

$ php -S localhost:3000 -t web

Abra un navegador web y visite http://localhost:3000 y aparecerá el formulario de instalación de Drupal.

Utilizaremos una instalación básica, así que ve al asistente de instalación y selecciona las siguientes opciones:

1. Elija su idioma y haga clic en "Guardar y continuar". En este caso, vamos a tomar el predeterminado de "Inglés".

2. Seleccione el perfil de instalación "Estándar" y haga clic en "Guardar y continuar".

3. Seleccione "SQLite" para el tipo de base de datos, y deje el resto de las opciones por defecto. Haz clic en "Guardar y continuar".

4. En "Configurar sitio", introduzca el nombre del sitio, el correo electrónico, el nombre de usuario y la contraseña que desee. Haga clic en "Guardar y continuar".

Drupal terminará la instalación. Automáticamente iniciará sesión y estará listo para empezar a jugar.

Si estás usando PHP 7.4 o 8.0, puede que encuentres un error acerca de que tu versión de SQLite es demasiado baja. PHP desacopló SQLite a partir de la versión 7.4 y utiliza la versión que tenga instalada su sistema operativo. Si utiliza Ubuntu 18.04 o versiones anteriores de Fedora o CentOS, es posible que no pueda instalar Drupal 9 utilizando SQLite. Si se encuentra con esto, es posible que desee buscar en el uso de MySQL o MariaDB como base de datos en lugar de SQLite.

Instalación de las API de Vonage

Ahora que tenemos una instalación de Drupal, podemos decidir cómo queremos interactuar con las API de Vonage. Si bien Drupal puede realizar solicitudes HTTP de dirección utilizando la función incorporada \Drupal::httpClient()los desarrolladores tendrán que preocuparse por descifrar los puntos finales de la API, las estructuras JSON y la autenticación para cada solicitud. Es la opción de implementación más desafiante.

Vonage proporciona una biblioteca PHP que puede ayudar con gran parte del código repetitivo para cada solicitud. Esta biblioteca funciona para la mayoría de las aplicaciones PHP, ya que todo lo que necesitas hacer es crear un objeto \Vonage\Client y suministrar tus credenciales. Esta biblioteca funcionará bien para Drupal, pero el punto difícil es hacer que el objeto que cree sea accesible para el resto del sistema. Tendrías que escribir un pequeño módulo que empuje al cliente de Vonage a la capa de servicio de Drupal.

Para ayudar con esto, Vonage ha creado un módulo que proporciona una interfaz de administración para agregar tus credenciales, crea el cliente API de Vonage y lo registra en el sistema de servicio. Si quieres ver el código fuente, está disponible en https://github.com/Nexmo/vonage-php-drupal-module. También lo hemos puesto a disposición como una biblioteca que se puede instalar a través de Composer, utilizando vonage/vonage_drupal.

Ya que estamos utilizando Composer para manejar nuestras dependencias, podemos volver a nuestro terminal y añadir el paquete a nuestro sitio web:

$ composer require vonage/vonage_drupal

Composer descargará algunas dependencias, y debería encontrar el módulo instalado en web/modules/contrib/vonage_drupal. Una vez completada la descarga, debemos habilitar el módulo yendo a la página "Extend" y habilitando el módulo "Vonage API SDK". Puedes buscarlo o desplazarte hasta la sección "Comunicaciones". Marca la casilla junto al nombre del módulo y haz clic en "Instalar" Después de un momento, la página debería actualizarse y verás el mensaje de éxito "El módulo Vonage API SDK ha sido habilitado".

Ahora podemos configurar el módulo yendo a la página "Configuración" y haciendo clic en "Configuración de API de Vonage" bajo el título "SISTEMA". En esta página podemos configurar dos conjuntos de credenciales que el módulo utilizará para configurar nuestro cliente SDK. La mayoría de las API de Vonage tienden a usar el secreto y la clave de la API de Vonage, que puedes encontrar en tu Panel de Vonage. Completa el formulario y haz clic en "Guardar configuración". Si estás usando una API que utiliza autenticación de clave privada como nuestra Voice API, puedes expandir esa sección e ingresar el ID de la aplicación y la clave privada.

Si deseas probar tus credenciales, puedes usar las pestañas "Prueba de SMS API de Vonage" o "Prueba de Voice API de Vonage" en la página de configuración. Si hay algún problema, el sistema debería devolver el error que encontramos. Por ahora, ingresemos tu clave y secreto de API y guardemos la configuración.

Uso del SDK de la API de Vonage

El módulo Vonage Drupal configura automáticamente y hace que el objeto cliente esté disponible a través del sistema contenedor de servicios de Drupal. Esta funcionalidad significa que podemos inyectar el SDK en nuestros módulos personalizados, así que vamos a crear un pequeño módulo. Podemos utilizar drush para crear un esqueleto de módulo para nosotros. Ejecute los siguientes comandos para instalar drush para nuestro proyecto, y para ejecutar a través de un rápido conjunto de preguntas para hacer el módulo:

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

1. Nombre del módulo: Vonage Hola Mundo

2. Nombre de la máquina: vonage_hello_world

3. Descripción del módulo: Módulo para probar la API de Vonage

4. Paquete: A medida

5. Dependencias: No hay dependencias, pulse ENTER

6. Responde "No" a todas las preguntas de creación excepto:

   1. ¿Quieres crear un controlador?

Este comando creará un nuevo módulo en web/modules/vonage_hello_worldasí como un nuevo controlador en el que podremos utilizar el SDK.

Abra web/modules/vonage_hello_world/src/Controller/VonageHelloWorldController.php en tu editor. Lo primero que tenemos que hacer para introducir el SDK en el controlador es redefinir el método create() de Drupal. Este método es utilizado por Drupal para crear cualquier controlador, y como tal pasa en el localizador de servicios. Vamos a añadir un create() anulación del método:

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

Al pasar el contenedor como argumento en el método, podemos extraer el cliente de la API de Vonage del contenedor utilizando el nombre de la clase. Internamente, esto llama a la fábrica que toma las credenciales que ingresamos anteriormente y genera un objeto utilizable. Luego podemos pasar este objeto a un nuevo controlador. Hablando de eso, vamos a añadir un método __construct() método que tome nuestro nuevo SDK, y una propiedad para almacenarlo.

protected $client;

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

Como hemos utilizado el comando drush para construir nuestro módulo, se añadió automáticamente un método a nuestro controlador que está conectado a una ruta. Podemos editar el método build() y añadir una llamada para enviar un SMS a nuestro teléfono móvil. Utilizando el fragmento Enviar un SMS podemos utilizar el cliente que hemos pasado para enviar el SMS. Edita el método build() para que se parezca al siguiente ejemplo. Asegúrate de sustituir TO_NUMBER con tu número de teléfono móvil, y VONAGE_NUMBER con el número que tienes en Vonage. Para asegurarnos de que Drupal no almacene la página en caché, también vamos a deshabilitar el almacenamiento en caché de la página cada vez que alguien acceda a esta ruta.

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;
}

Todo lo necesario para enviar un mensaje SMS desde Drupal está instalado y configurado. Vuelve a la interfaz de administración de Drupal, ve a la página "Extender", busca "Vonage Hello World" y selecciona su casilla de verificación. Haz clic en "Instalar" para instalar nuestro módulo personalizado. Después de un momento, debería aparecer un mensaje de éxito para decir que hemos instalado nuestro módulo.

Por defecto el drush establece una ruta para nuestro controlador en /vonage-hello-world/example. Dirígete a http://localhost:3000/vonage-hello-world/example. Deberíamos ver un nodo normal de Drupal que dice "El mensaje se ha enviado correctamente" y tu teléfono debería recibir el mensaje SMS que configuramos en el controlador. Si actualizas la página, el SMS se enviará de nuevo, ya que hemos desactivado la caché de salida.

Lecturas complementarias

Desde aquí, el SDK PHP completo de Vonage está disponible para que juegues con tus módulos personalizados. No dudes en consultar nuestros fragmentos de código PHP para ver más ejemplos de las diversas cosas que puedes hacer con nuestro SDK en casi todas nuestras API.

Puede encontrar el código de ejemplo de esta demostración en https://github.com/nexmo-community/vonage-php-sdk-drupal-9.