Anunciamos o lançamento do PHP Server SDK versão 2.2.0

Tenho o prazer de anunciar o lançamento da versão 2.2.0 do nosso SDK do servidor PHP para as APIs da Vonage.

Embora esta seja uma versão secundária do SDK, ela está repleta de novos recursos da próxima versão 3.0.0, que lançaremos em breve. Você pode começar a usar muitos desses novos recursos imediatamente, sem deixar de ter acesso aos recursos já existentes oferecidos pelo SDK.

Nossa Primeira Versão de Atualização

Foi dedicado um enorme volume de trabalho à reformulação de muitos dos componentes internos do SDK do PHP, mas, com essa refatoração, muitas das APIs de métodos públicos do SDK sofrerão alterações na versão 3.0.0.

Também conheço a dificuldade de ter que trabalhar com uma base de código já existente, e encontrar tempo para fazer a atualização pode ser complicado. Esta versão está incorporando, na medida do possível, o máximo de alterações que não quebram a compatibilidade com versões anteriores, incluindo a nova interface para trabalhar com nossa SMS API legada e nossa Voice API. Mais informações sobre esses novos namespaces em instantes.

A versão 3.0.0 também deixará de oferecer vários recursos, incluindo muitas das formas de acesso aos dados em várias de nossas APIs.

Todas essas funcionalidades obsoletas estão marcadas no código-fonte com @deprecated anotações, mas fomos um pouco além e permitimos que você veja quais elementos obsoletos você está usando nos logs em tempo real.

Essa é uma opção opcional, portanto, você não precisa se preocupar com uma enxurrada de avisos nos seus logs de produção. Trata-se também de um recurso de desenvolvimento que você pode ativar para exibir informações como alterações na assinatura de métodos, indicações sobre novos métodos ou classes a serem usados e muito mais. Basta ativar a show_deprecations opção ao criar o Nexmo Client.

$creds = new \Nexmo\Client\Credentials\Basic(NEXMO_API_KEY, NEXMO_API_SECRET);
$client = new \Nexmo\Client($creds, [
    'show_deprecations' => true
]);

Depois que essa opção estiver ativada, você poderá executar seu aplicativo localmente e ver quais avisos de descontinuação aparecem! Dependendo da API que você estiver acessando, poderá ver um grande número de avisos de descontinuação, mas todos eles devem indicar a correção adequada. Assim que todos os avisos de descontinuação forem resolvidos, sua aplicação também estará totalmente compatível com a versão 3.0.0, e essa atualização deve ocorrer sem problemas!

Há uma lista mais completa das funcionalidades obsoletas nas próprias notas de lançamento no GitHub, mas, para uma visão geral rápida:

• O acesso a matrizes está obsoleto em todas as camadas de serviço, como messages(), voice(), applications(), etc. Todos eles foram substituídos por métodos de pesquisa propriamente ditos.

• Passar um filtro de pesquisa para uma camada de serviço, como applications(), está obsoleto. Use as funções específicas search/get para cada camada.

• A maioria das entidades não pode mais ser acessada por meio de array e deve passar a utilizar os métodos getter.

• A maioria dos métodos não aceita mais matrizes PHP em formato bruto, por uma questão de segurança de tipos. Os avisos de obsolescência indicarão os objetos adequados a serem utilizados.

• O conversation() e user() camadas de serviço estão obsoletas e serão totalmente removidas na versão 3.0.0

• A antiga camada de Voice para conversão de texto em fala está obsoleta e será totalmente removida na versão 3.0.0.

• A pesquisa por SMS está obsoleta e será totalmente removida na versão 3.0.0.

Melhores ferramentas de depuração

Estou super animado com um novo recurso: maior visibilidade das solicitações e respostas que ocorrem na API.

O SDK atual, mesmo na versão 2.2.0, oferece algum acesso às solicitações e respostas que ocorrem, mas pode ser difícil saber quais entidades têm acesso a elas.

Todas as APIs (exceto messages() e calls()) agora possuem um manipulador de API embutido que mantém o registro da última solicitação e resposta criadas. Você pode consultar o manipulador de API a partir de qualquer namespace da camada de serviço usando getApiResource() e obter uma solicitação ou resposta compatível com PSR-7.

$response = $client->sms()->send(
    new \Nexmo\SMS\Message\SMS(TO_NUMBER, NEXMO_NUMBER, 'A text message sent using the Nexmo SMS API')
);

$lastRequest = $client->sms()->getApiResource()->getLastRequest();
$lastResponse = $client->sms()->getApiResource()->getLastResponse();

Deixamos de recomendar a obtenção da solicitação e das respostas a partir de entidades e exceções, e recomendamos que essas informações sejam obtidas a partir dos namespaces do serviço. A única exceção a essa regra são alguns dos métodos de pesquisa mais recentes nas camadas de serviço, que retornam uma coleção com carregamento diferido. Nesse caso, o manipulador da API da coleção contém a solicitação e a resposta.

// Returns a lazy-loaded iterable object
$applications = $client->applications()->getAll();
assert($applications instanceof \Nexmo\Entity\IterableAPICollection);

// Start iterating, which fires off an HTTP request
$application = $applications->current();

// Get the request/response
$lastRequest = $applications->getApiResource()->getLastRequest();
$lastResponse = $applications->getApiResource()->getLastResponse();

Algumas APIs continuarão a retornar matrizes na versão 2.2.0; portanto, verifique as assinaturas dos métodos ou use instanceof se não tiver certeza. Na versão 3.0.0, quase todos os resultados de pesquisa terão uma interface mais recente.

A nova camada de SMS

Muitos de nossos clientes utilizam nossos recursos legados de SMS. Enquanto trabalhamos em novas APIs, como nossa Messages API para oferecer ainda mais recursos de mensagens, isso não significa que eu queira deixar nossos clientes de SMS para trás.

Para isso, toda a camada de SMS foi reformulada para incluir tipagem estrita e uma interface totalmente orientada a objetos. Isso reduzirá os erros decorrentes da necessidade de criar arrays de PHP em formato bruto e proporcionará uma visão mais clara dos recursos disponíveis para as mensagens. Também procurei manter a interface simples que os desenvolvedores já esperam encontrar em nosso SDK.

// The old messages namespace
$message = $client->message()->send([
    'to' => TO_NUMBER,
    'from' => NEXMO_NUMBER,
    'text' => 'A text message sent using the Nexmo SMS API'
]);

// The new way
$response = $client->sms()->send(
    new \Nexmo\SMS\Message\SMS(TO_NUMBER, NEXMO_NUMBER, 'A text message sent using the Nexmo SMS API')
);

O antigo messages() namespace no Nexmo Client será totalmente descontinuado na versão 2.2.0, e o novo sms() espaço de nomes já está disponível para uso. Ambos podem ser usados simultaneamente, de modo que o código legado possa continuar a utilizar o espaço de nomes antigo, enquanto o código novo pode utilizar o novo sms() namespace.

Também ampliei a interface de webhooks de entrada. Assim como antes, você pode analisar uma solicitação recebida, mas agora recebe de volta um objeto com indicação completa de tipos \Nexmo\SMS\Webhook\InboundSMS . Isso deve deixar muito mais claro como obter os dados recebidos, em comparação com lidar com parâmetros de consulta, um corpo de postagem JSON bruto ou até mesmo um array.

$inboundSMS = \Nexmo\SMS\Webhook\Factory::createFromGlobals();
echo $inboundSMS->getFrom() . PHP_EOL;
echo $inboundSMS->getTo() . PHP_EOL;
echo $inboundSMS->getText() . PHP_EOL;

A nova camada de Voice

A Voice API é outra das nossas APIs mais utilizadas, e essa é mais uma área em que eu queria garantir que a interface fosse a mais simples possível.

Para proporcionar uma separação clara e organizada, o calls() namespace foi completamente descontinuado em favor de uma interface totalmente nova por meio do voice() namespace.

A ideia era a mesma da nova camada de SMS: oferecer uma interface nova e simples que facilitasse a realização de tarefas comuns, mantendo todo o potencial que nossa Voice API oferece, e desenvolvê-la seguindo as práticas modernas de PHP. Já falei bastante em outros posts sobre algumas dessas interfaces, e essa foi a oportunidade perfeita para aperfeiçoar alguns detalhes.

// The old way
$call = $client->calls()->create([
    'to' => [[
        'type' => 'phone',
        'number' => TO_NUMBER
    ]],
    'from' => [
        'type' => 'phone',
        'number' => NEXMO_NUMBER
    ],
    'ncco' => [
        [
            'action' => 'talk',
            'text' => 'This is a text to speech call from Nexmo'
        ]
    ]
]);

// The new way
$outboundCall = new \Nexmo\Voice\OutboundCall(
    new \Nexmo\Voice\Endpoint\Phone(TO_NUMBER),
    new \Nexmo\Voice\Endpoint\Phone(NEXMO_NUMBER)
);
$ncco = new NCCO();
$ncco->addAction(new \Nexmo\Voice\NCCO\Action\Talk('This is a text to speech call from Nexmo'));
$outboundCall->setNCCO($ncco);

$response = $client->voice()->createOutboundCall($outboundCall);

Como a nova voice() camada é totalmente orientada a objetos, não há mais necessidade de lembrar como construir uma estrutura de array para nenhum dos nossos NCCOs nem mesmo para chamadas básicas. Todas as opções disponíveis são expostas como métodos setter no novo \Nexmo\Voice\OutboundCall objeto, e o \Nexmo\Voice\OutboundCall objeto oferece melhor suporte a diversos endpoints.

Trabalhar com NCCOs sempre foi um ponto delicado para mim. Embora o PHP torne muito fácil converter um array em JSON, lembrar de todas as opções do NCCO geralmente me leva à nossa (reconhecidamente incrível) documentação.

O SDK agora vem com um gerador de NCCO, para que você possa criar seus NCCOs com objetos fortemente tipados e, ainda assim, gerar JSON com a mesma facilidade, seja para solicitações de NCCO recebidas, seja para os NCCOs que você está enviando como parte de chamadas de saída.

$ncco = new \Nexmo\Voice\NCCO\NCCO();
$ncco
    ->addAction(
        new \Nexmo\Voice\NCCO\Action\Talk('Welcome to the amazing Nexmo conference call')
    )
    ->addAction(
        new \Nexmo\Voice\NCCO\Action\Conversation('amazing-conference-call')
    )
;

header('Content-Type: application/json');
$json = json_encode($ncco);
echo($json);

A Voice API depende fortemente de callbacks de webhook; por isso, esta versão também apresenta um analisador de webhooks recebidos muito mais completo. Esse analisador possui a mesma interface que nosso analisador de SMS, mas retornará objetos relacionados ao ciclo de vida da Voice API.

$inboundVAPI = \Nexmo\Voice\Webhook\Factory::createFromGlobals();
if ($inboundVAPI instanceof \Nexmo\Voice\Webhook\Event) {
    echo $inboundVAPI->getTo() . PHP_EOL;
    echo $inboundVAPI->getFrom() . PHP_EOL;
    echo $inboundVAPI->getStatus() . PHP_EOL;
    echo $inboundVAPI->getUuid() . PHP_EOL;  
}

if ($inboundVAPI instanceof \Nexmo\Voice\Webhook\Record) {
    echo $inboundVAPI->getRecordingUrl() . PHP_EOL;
}

// And other types can also be returned

Verify atualizações

A última API importante a passar por uma grande reformulação foi a nossa Verify , no verify() namespace. Essa reformulação não foi tão abrangente quanto a do SMS e do Voice, mas há alguns novos recursos que devem ser levados em consideração.

A primeira é uma maneira mais clara de criar uma solicitação de verificação. Isso agora é feito pelo \Nexmo\Verify\Request objeto, que oferece uma interface mais organizada para iniciar o processo de verificação.

Esse objeto é fortemente tipado e expressa melhor o que esperamos de uma solicitação de verificação, em comparação com o objeto de uso mais geral \Nexmo\Verify\Verification . Por uma questão de compatibilidade com versões anteriores, um \Nexmo\Verify\Verification ainda é retornado, mas isso mudará na versão 3.0.0.

// The old way
$verification = new \Nexmo\Verify\Verification(NUMBER, BRAND_NAME);
$client->verify()->start($verification);

// The new way
$request = new \Nexmo\Verify\Request(NUMBER, BRAND_NAME);
$response = $client->verify()->start($request);

Verificar, cancelar e acionar o próximo evento ficou mais fácil. Você não precisa mais instanciar um \Nexmo\Verify\Verification objeto nem serializá-lo e transportá-lo por meio de sessões. A verify() camada de serviço agora se limita a aceitar diretamente o ID da solicitação Verify.

// The old way
$verification = new \Nexmo\Verify\Verification(REQUEST_ID);
$result = $client->verify()->check($verification, CODE);

// The new way
$result = $client->verify()->check(REQUEST_ID, CODE);

Embora não se trate de uma mudança significativa, a versão 3.0.0 aceitará apenas um ID de solicitação na forma de string, em vez do objeto; portanto, é importante estar ciente disso.

A promessa de atualizações mais fáceis

Qualquer código compatível com a versão 2.1.0 deve ser imediatamente compatível com a 2.2.0, sem a necessidade de alterações. Esta versão simplesmente lhe dará a oportunidade de realizar as atualizações no seu próprio ritmo, mantendo-se, ao mesmo tempo, o mais atualizado possível.

Daqui para frente, o SDK do PHP continuará a adotar uma abordagem mais formal em relação às funcionalidades obsoletas e aos caminhos de atualização, para que você, desenvolvedor, tenha a possibilidade de se adaptar às mudanças da maneira mais rápida e simples possível.

Aguardo ansiosamente seus comentários e nos vemos em breve para o lançamento da versão 3.0.0!