Anuncio de la versión 2.2.0 del SDK del servidor PHP

Me complace anunciar el lanzamiento de versión 2.2.0 de nuestro SDK de servidor PHP para las API de Vonage.

Aunque se trata de una versión menor para el SDK, está repleta de nuevas funciones de la próxima versión 3.0.0 que realizaremos en breve. Usted puede comenzar a utilizar muchas de las nuevas características de inmediato, sin dejar de mantener el acceso a las capacidades existentes proporcionadas por el SDK.

Nuestra primera actualización

Se ha invertido una gran cantidad de trabajo en reelaborar muchos de los aspectos internos del SDK de PHP, pero con esa refactorización, muchas de las API de métodos públicos del SDK cambiarán en la versión 3.0.0.

También conozco el dolor de tener que trabajar con una base de código existente, y encontrar tiempo para actualizar puede ser difícil. Esta versión incorpora tantos cambios de retrocompatibilidad como ha sido posible, incluida la nueva interfaz para trabajar con nuestra SMS API heredada y nuestra Voice API. Más información sobre estos nuevos espacios de nombres dentro de un momento.

La versión 3.0.0 también dejará obsoletas varias funciones, incluidas muchas de las formas en que se accede a los datos a través de muchas de nuestras API.

Todas estas depreciaciones están marcadas en el código fuente con @deprecated anotaciones, pero hemos ido un paso más allá y le hemos permitido ver qué depreciaciones está utilizando en los registros en tiempo real.

Esto es opcional, por lo que no tiene que preocuparse por un montón de avisos en sus registros de producción. También es una característica de desarrollo que puede activar para mostrar cosas como cambios en la firma de métodos, punteros a nuevos métodos o clases a utilizar, y más. Todo lo que necesitas hacer es activar la opción show_deprecations al crear el Cliente Nexmo.

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

Una vez activada esta opción, puede ejecutar su aplicación localmente y ver qué avisos de desaprobación aparecen. Dependiendo de la API a la que estés accediendo, es posible que veas un gran número de obsoletos, pero todos los avisos de obsoletos deberían indicarte la corrección adecuada. Una vez que todos los avisos de desaprobación se hayan aclarado, también debería ser totalmente compatible con la versión 3.0.0, y la actualización debería ser perfecta.

Existe una lista más completa de imprecisiones en las notas de la versión en Githubpero a modo de resumen:

• El acceso a matrices está obsoleto en todas las capas de servicio, tales como messages(), voice(), applications()etc. Todos ellos se sustituyen por métodos de búsqueda reales.

• Pasar un filtro de búsqueda a una capa de servicio, como applications()está obsoleto. Utilice las funciones de búsqueda/obtención específicas de cada capa.

• La mayoría de las entidades ya no son accesibles mediante arrays y deberían cambiar para utilizar los métodos getter.

• La mayoría de los métodos ya no toman arrays PHP sin procesar, por seguridad de tipo. Los avisos de desaprobación le indicarán los objetos apropiados a utilizar.

• En conversation() y user() están obsoletas y se eliminarán por completo en la versión 3.0.0.

• La antigua capa Voice de texto a voz está obsoleta y se eliminará por completo en la versión 3.0.0.

• La búsqueda de SMS está obsoleta y se eliminará por completo en la versión 3.0.0.

Mejores herramientas de depuración

Estoy muy entusiasmado con una nueva función: una mejor visibilidad de las solicitudes y respuestas que se producen a través de la API.

El SDK actual, incluso con 2.2.0, proporciona cierto acceso a las peticiones y respuestas que se producen, pero puede ser difícil saber qué entidades tienen acceso.

Todas las API (excepto messages() y calls()) tienen ahora un gestor de API integrado que realiza un seguimiento de la última solicitud y respuesta creadas. Puedes consultar el gestor de API desde cualquier espacio de nombres de la capa de servicios con getApiResource() y obtener una solicitud o respuesta compatible con solicitud o respuesta compatible con 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();

Hemos dejado de lado la obtención de solicitudes y respuestas de entidades y excepciones, y recomendamos obtener esta información de los espacios de nombres de los servicios. La única excepción a esto son algunos de los nuevos métodos de búsqueda en las capas de servicio, que devuelven una colección de carga perezosa. En este caso, el manejador API de la colección tiene la solicitud y la respuesta.

// 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();

Algunas API seguirán devolviendo matrices en la versión 2.2.0, así que compruebe las firmas de los métodos o utilice instanceof si no está seguro. En la versión 3.0.0, casi todos los resultados de búsqueda tendrán una interfaz más nueva.

La nueva capa SMS

Muchos de nuestros clientes utilizan nuestras funciones de SMS heredadas. Mientras trabajamos en nuevas API como nuestra Messages API para ofrecer aún más funciones de mensajería, eso no significa que queramos dejar atrás a nuestros clientes de SMS.

Para ello, se ha renovado toda la capa de SMS para incluir una tipificación estricta y una interfaz totalmente orientada a objetos. Esto reducirá los errores que se cometen al tener que crear matrices PHP sin procesar y ofrecerá una visión más clara de las funciones disponibles para los mensajes. También he intentado mantener la interfaz sencilla que los desarrolladores esperan de nuestro 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')
);

El antiguo messages() en el Cliente Nexmo está totalmente obsoleto en la versión 2.2.0, y el nuevo espacio de nombres sms() está disponible para su uso. Estos pueden ser utilizados lado a lado por lo que el código heredado puede seguir utilizando el antiguo espacio de nombres, y el nuevo código puede utilizar el nuevo sms() nuevo.

También he ampliado la interfaz de webhook entrante. Al igual que antes, se puede analizar una solicitud entrante, pero ahora se obtiene de vuelta un objeto totalmente de tipo \Nexmo\SMS\Webhook\InboundSMS objeto. Esto debería hacer que sea mucho más claro sobre cómo obtener los datos entrantes en comparación con el tratamiento de los parámetros de consulta o un cuerpo de entrada JSON en bruto, o incluso una matriz.

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

La nueva capa Voice

La Voice API es otra de nuestras API más utilizadas, y es otra área en la que quería asegurarme de que la interfaz fuera lo más limpia posible.

Para ofrecer un corte limpio, el espacio de nombres calls() en favor de una nueva interfaz a través del espacio de nombres voice() espacio de nombres.

La idea era la misma que con la nueva capa de SMS: proporcionar una interfaz nueva y limpia que facilite las tareas habituales, conservando toda la potencia que ofrece nuestra Voice API y desarrollándola con prácticas PHP modernas. Ya he hablado en otras entradas sobre algunas de estas interfaces, y esta era la oportunidad perfecta para limar asperezas.

// 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);

Dado que la nueva voice() está orientada a objetos, ya no es necesario recordar cómo construir una estructura de array para cualquiera de nuestras NCCOs o incluso llamadas básicas. Todas las opciones disponibles se exponen como métodos setter en el nuevo objeto \Nexmo\Voice\OutboundCall y el objeto \Nexmo\Voice\OutboundCall tiene un mejor soporte para varios puntos finales.

Trabajar con NCCOs siempre ha sido un punto delicado para mí. A pesar de que PHP hace que sea trivial convertir un array en JSON, recordar todas las opciones NCCO normalmente me envía a nuestra (ciertamente impresionante) documentación.

El SDK incluye ahora un generador de NCCO para que pueda crear sus NCCO con objetos de tipado fuerte y generar JSON con la misma facilidad para las solicitudes NCCO entrantes o las NCCO que envíe como parte de las llamadas salientes.

$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);

El sitio Voice API depende en gran medida de las devoluciones de llamada de webhook, por lo que esta versión también introduce un analizador de webhook entrante mucho más completo. Este analizador tiene la misma interfaz que nuestro analizador de SMS, pero devolverá objetos relacionados con el ciclo de vida de la 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

Verificar actualizaciones

La última API importante que ha sido objeto de una refactorización importante es nuestra API Verify bajo el espacio de nombres verify() espacio de nombres. Esta remodelación no ha sido tan importante como la de SMS y Voice, pero hay que tener en cuenta algunas novedades.

La primera es una forma más clara de crear una solicitud de verificación. Ahora la gestiona el objeto \Nexmo\Verify\Request que proporciona una interfaz más limpia para iniciar el proceso de verificación.

Este objeto está fuertemente tipado y expone mejor lo que esperamos de una solicitud de verificación, frente al objeto de propósito más general \Nexmo\Verify\Verification de propósito general. Por compatibilidad con versiones anteriores, se sigue devolviendo un \Nexmo\Verify\Verification pero esto cambiará en la versión 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);

Comprobar, cancelar y activar el siguiente evento es más fácil. Ya no es necesario instanciar un objeto \Nexmo\Verify\Verification o serializarlo y transportarlo a través de sesiones. La capa de servicio verify() capa de servicio se encarga ahora de aceptar directamente el ID de solicitud de 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);

Aunque no se trata de un cambio importante, la versión 3.0.0 sólo aceptará un ID de solicitud de cadena en lugar del objeto, por lo que es algo a tener en cuenta.

La promesa de actualizaciones más sencillas

Cualquier código compatible con la versión 2.1.0 debería ser inmediatamente compatible con la 2.2.0 sin cambios. Este lanzamiento simplemente le dará la oportunidad de realizar las actualizaciones en su propio tiempo mientras se mantiene lo más actualizado posible.

En el futuro, el SDK de PHP continuará siendo más formal con las depreciaciones y las rutas de actualización para que usted, el desarrollador, obtenga la capacidad de actualizarse a los cambios lo más rápido y sin dolor como sea posible.

Espero sus comentarios y nos vemos pronto para el lanzamiento de la versión 3.0.0.