Como usar as APIs da Vonage com o Drupal

Pré-requisitos

• PHP 7.3 ou superior

• SQLite 3.26 ou superior OU MySQL 5.7.8 ou superior

Instalando o Drupal

Com o lançamento do Drupal 8, agora é possível instalar o Drupal usando Composer, o gerenciador de pacotes do PHP. O Composer se encarregará de manter seu site atualizado, bem como todas as dependências do site, mas também pode ser usado para realizar uma instalação básica do Drupal. Vamos clonar o drupal/recommended-project repositório como um projeto para obter uma instalação básica do Drupal:

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

O Composer fará o download do repositório e baixará automaticamente as dependências para o nosso aplicativo; no momento da redação deste artigo, isso incluirá o Drupal 9.1. Podemos acessar o vonage-and-drupal/ diretório e continuar a instalação.

Embora possamos executar o Drupal por meio de um servidor web como o httpd do Apache ou o Nginx, o PHP possui um servidor de desenvolvimento integrado que podemos utilizar. Abra outra janela de terminal, navegue até o diretório onde baixamos o código do Drupal e inicie o servidor:

$ php -S localhost:3000 -t web

Abra um navegador da web e acesse http://localhost:3000 para ser recebido com o formulário de instalação do Drupal!

Vamos utilizar uma instalação básica; portanto, siga as etapas do assistente de instalação e selecione as seguintes opções:

1. Escolha seu idioma e clique em “Salvar e continuar”. Neste caso, vamos usar a opção padrão, que é “Inglês”.

2. Selecione o perfil de instalação “Padrão” e clique em “Salvar e continuar”.

3. Selecione “SQLite” como tipo de banco de dados e mantenha as demais opções nos valores padrão. Clique em “Salvar e continuar”.

4. Na seção “Configurar site”, preencha o nome do site, o e-mail, o nome de usuário e a senha que desejar. Clique em “Salvar e continuar”.

O Drupal vai concluir a instalação. Você será conectado automaticamente e estará pronto para começar a explorar o sistema!

Se você estiver usando o PHP 7.4 ou 8.0, poderá receber uma mensagem de erro informando que a versão do SQLite está muito antiga. A partir da versão 7.4, o PHP deixou de incluir o SQLite e passa a utilizar a versão instalada no seu sistema operacional. Se você estiver usando o Ubuntu 18.04 ou versões mais antigas do Fedora ou do CentOS, talvez não consiga instalar o Drupal 9 usando o SQLite. Se isso acontecer, considere usar o MySQL ou o MariaDB como banco de dados em vez do SQLite.

Instalando as APIs da Vonage

Agora que já temos uma instalação do Drupal, podemos decidir como queremos interagir com as APIs da Vonage. Embora o Drupal possa fazer solicitações HTTP diretas usando o \Drupal::httpClient(), os desenvolvedores terão que se preocupar em identificar os endpoints das APIs, as estruturas JSON e a autenticação para cada solicitação individualmente. Essa é a opção de implementação mais desafiadora.

A Vonage fornece uma biblioteca PHP que pode ajudar com grande parte do código repetitivo em cada solicitação. Essa biblioteca funciona para a maioria das Applications PHP, já que tudo o que você precisa fazer é criar um \Vonage\Client objeto e fornecer suas credenciais. Essa biblioteca funcionará bem com o Drupal, mas o ponto delicado é garantir que o objeto criado fique acessível ao restante do sistema. Você precisaria escrever um pequeno módulo que integre o cliente da Vonage à camada de serviços do Drupal.

Para ajudar nisso, a Vonage criou um módulo que oferece uma interface de administração para inserir suas credenciais, cria o cliente da API da Vonage e o registra no sistema de serviço. Se você quiser consultar o código-fonte, ele está disponível em https://github.com/Nexmo/vonage-php-drupal-module. Também o disponibilizamos como uma biblioteca que pode ser instalada via Composer, usando vonage/vonage_drupal.

Como estamos usando o Composer para gerenciar nossas dependências, podemos voltar ao terminal e adicionar o pacote ao nosso site:

$ composer require vonage/vonage_drupal

O Composer fará o download de algumas dependências, e você deverá encontrar o módulo instalado em web/modules/contrib/vonage_drupal. Quando o download estiver concluído, precisamos habilitar o módulo acessando a página “Extend” e ativando o módulo “Vonage API SDK”. Você pode procurá-lo ou rolar a página até a seção “Communications”. Marque a caixa ao lado do nome do módulo e clique em “Install”. Após alguns instantes, a página deve ser atualizada, e você verá a mensagem de sucesso “O módulo Vonage API SDK foi ativado”!

Agora podemos configurar o módulo acessando a página “Configuração” e clicando em “Configurações da API da Vonage”, na seção “SISTEMA”. Nessa página, podemos configurar dois conjuntos de credenciais que o módulo utilizará para configurar nosso Client SDK. A maioria das APIs da Vonage costuma usar a Chave Secreta e a Chave da API da Vonage, que você pode encontrar no seu Painel da Vonage. Preencha o formulário e clique em “Salvar configuração”. Se você estiver usando uma API que utilize autenticação por chave privada, como nossa Voice API, pode expandir essa seção e inserir o ID do aplicativo e a chave privada.

Se você quiser testar suas credenciais, pode usar as guias “Teste da SMS API da Vonage” ou “Teste da Voice API da Vonage” na página de configuração. Se houver algum problema, o sistema deve exibir o erro encontrado. Por enquanto, vamos preencher o seu Segredo e a Chave da API e salvar a configuração.

Como usar o SDK da API da Vonage

O módulo Vonage para Drupal configura automaticamente e disponibiliza o objeto cliente por meio do sistema de contêiner de serviços do Drupal. Essa funcionalidade significa que podemos injetar o SDK em nossos módulos personalizados; portanto, vamos criar um pequeno módulo. Podemos usar drush para criar um esqueleto de módulo para nós. Execute os seguintes comandos para instalar o drush em nosso projeto e responder a uma série rápida de perguntas para criar o módulo:

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

1. Nome do módulo: Vonage Hello World

2. Nome da máquina: vonage_hello_world

3. Descrição do módulo: Módulo para testar a API da Vonage

4. Pacote: Personalizado

5. Dependências: Sem dependências, pressione ENTER

6. Responda “Não” a todas as perguntas sobre a criação, exceto:

   1. Você gostaria de criar um controlador?

Este comando criará um novo módulo em web/modules/vonage_hello_world, além de um novo controlador no qual poderemos usar o SDK!

Abra web/modules/vonage_hello_world/src/Controller/VonageHelloWorldController.php no seu editor. A primeira coisa que precisamos fazer para incluir o SDK no Controlador é sobrescrever o create() método. Esse método é usado pelo Drupal para criar qualquer controlador e, por isso, passa o localizador de serviços. Vamos adicionar uma create() sobrescrito do método:

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

Ao passar o contêiner como argumento no método, podemos extrair o cliente da API da Vonage do contêiner usando o nome da classe. Internamente, isso chama a fábrica que utiliza as credenciais que inserimos anteriormente e gera um objeto pronto para uso. Podemos então passar esse objeto para um novo controlador. Por falar nisso, vamos adicionar um __construct() método para pegar nosso novo SDK e uma propriedade para armazená-lo.

protected $client;

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

Como usamos o drush comando para compilar nosso módulo, ele adicionou automaticamente um método ao nosso controlador que está vinculado a uma rota. Podemos editar o build() método e adicionar uma chamada para enviar um SMS para o nosso celular. Usando o trecho “Enviar um SMS” como base, podemos usar o cliente que passamos para enviar o SMS. Edite o build() método para que fique como no exemplo a seguir. Certifique-se de substituir TO_NUMBER pelo seu número de celular e VONAGE_NUMBER pelo número que você possui na Vonage. Para garantir que o Drupal não armazene a página em cache, também vamos desativar o cache da página sempre que alguém acessar essa rota.

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

Tudo o que é necessário para enviar uma mensagem SMS a partir do Drupal já está instalado e configurado. Volte à interface de administração do Drupal, acesse a página “Extend”, localize “Vonage Hello World” e marque a caixa de seleção correspondente. Clique em “Install” para instalar nosso módulo personalizado. Após alguns instantes, deverá aparecer uma mensagem de sucesso informando que instalamos nosso módulo.

Por padrão, o drush esqueleto configura uma rota para o nosso controlador em /vonage-hello-world/example. Acesse http://localhost:3000/vonage-hello-world/example. Devemos ver um nó normal do Drupal que diz “A mensagem foi enviada com sucesso” e seu celular deve receber a mensagem SMS que configuramos no controlador. Se você atualizar esta página, a mensagem SMS será enviada novamente, já que desativamos o cache de saída.

Leitura complementar

A partir daqui, o SDK completo do Vonage para PHP está disponível para você experimentar em seus módulos personalizados. Fique à vontade para dar uma olhada em nossos trechos de código PHP para ver mais exemplos do que você pode fazer com nosso SDK em praticamente todas as nossas APIs.

Você pode encontrar o código de exemplo desta demonstração em https://github.com/nexmo-community/vonage-php-sdk-drupal-9.