Development

Tutorial per app web Client Library PHP API SMS

n questo tutorial, vedremo tutti gli step per installare un’app web PHP funzionale e per utilizzare la libreria API client di Infobip.

August 18 2017

Se stai costruendo un’app web utilizzando PHP e vuoi implementare la funzionalità SMS, sei nel posto giusto. Abbiamo creato una libreria API client Infobip per aiutarti, realizzando questo tutorial per guidarti passo per passo. In questo modo abbiamo reso ancora più semplice l’implementazione di questa funzionalità e l’applicazione di un ulteriore livello di sicurezza sul tuo sito web, con la nostra soluzione 2FA, in modo tale che ogni chiamata HTTP API e la serializzazione dei modelli vengano eseguiti sulla nostra libreria.

Questa guida operativa è una versione aggiornata del nostro precedente tutorial sull'api sms php, redatto per rendere ancora più veloce l’implementazione delle funzionalità SMS per la tua applicazione web. Affronterai tre passi essenziali, ognuno dei quali viene descritto in una sezione separata. In primo luogo, affronteremo il tema dell’invio dei messaggi SMS, seguito dal recupero dei log dei messaggi ed infine la ricezione dei rapporti di consegna.

Gli indici si collegano a queste tre pagine in modo da poter navigare facilmente.

Affinché la tua app web SMS funzioni correttamente, devi configurare il server PHP. Poiché la libreria client esegue richieste HTTP all’API Infobip, è necessario abilitare l’estensione cURL PHP sul tuo server web.

Per eseguire l’applicazione è possibile utilizzare alcune soluzioni dallo stack di soluzioni AMP (wamp, xampp, ...). Questi sono stack software per vari sistemi operativi, costituiti da server web Apache, database MySQL e supporto di linguaggio di programmazione PHP. È necessario abilitare l’estensione phpcurl per quella che scegli.

Ti consigliamo di installare il composer, un semplice strumento che ti aiuterà a risolvere le dipendenze dei progetti PHP e a semplificare il processo di download e di utilizzo del client API Infobip utilizzato in questo progetto. Le istruzioni dettagliate su come installare il composer sono disponibili sul loro sito web e in questo blog affronteremo la parte pratica.

N.B.: Per garantire l’invio sicuro di SMS, questi esempi devono essere ospitati su HTTPS (utilizzando TLS) quando vengono trasmessi. Per semplificare, in questo tutorial abbiamo usato l’HTTP.

INFOBIP API CLIENT

Per poter utilizzare la libreria API client di Infobip, è necessario includerla nel proprio progetto. Per facilitare questo processo, ti consigliamo di utilizzare il composer. Con questo ti basterà definire una versione del client che desideri utilizzare. È possibile farlo in uno speciale file denominato composer.json:


{
  "require": {
	"infobip/infobip-api-php-client": "2.0.1"
  }
}

Con il file composer.json nella giusta posizione, è possibile istruire il composer per ottenere le dipendenze elencate, eseguendo il seguente comando dal terminale:

composer install

Adesso dovrebbe esserci una cartella chiamata “vendor” accanto al file composer.json. Se la apri, all’interno c’è un file chiamato autoload.php che sarà utile in seguito. Inoltre, la cartella vendor ha delle sottocartelle separate per il codice della libreria API client di Infobip e le sue dipendenze.

INVIARE MESSAGGI SMS 

La pagina dei messaggi di testo completi di funzioni (advancedSms.php) contiene il modulo di input per l’invio di un messaggio SMS. I campi richiesti sono username, password e numero di telefono di destinazione, mentre tutti gli altri valori sono facoltativi. Per ulteriori informazioni sulla notifica del tipo di contenuto URL e dei dati di richiamata, consulta il capitolo “Ricevere il rapporto di consegna”. Il pulsante “Invia” manda la richiesta a una pagina specificata nell’attivazione di azione del modulo. In questo esempio lo invierà a se stesso.

form action="" method="POST" ... 

Prima di effettuare una chiamata API, è necessario verificare che l’utente abbia inviato tutti i campi necessari. In questo esempio abbiamo spuntato solo il campo toInput. Non è necessario controllarli tutti perché non tutte le proprietà sono richieste dall’API e qualsiasi proprietà mancante verrà semplicemente ignorata dal client. Se stai caricando la pagina per la prima volta, ricorda che questi campi non saranno presenti.

UTILIZZARE L’INFOBIP API CLIENT

Utilizzeremo l’Infobip API client per eseguire richieste http. Questo accorcerà notevolmente il codice, ma prima di tutto è necessario fornire a PHP il percorso delle classi necessarie. Ciò è possibile caricando il file autoload.php dalla cartella “vendors” e specificando le parti della libreria client da utilizzare:


      require_once __DIR__ . '/vendor/autoload.php';
 
use infobip\api\client\SendMultipleTextualSmsAdvanced;
use infobip\api\configuration\BasicAuthConfiguration;
use infobip\api\model\Destination;
use infobip\api\model\sms\mt\send\Message;
use infobip\api\model\sms\mt\send\textual\SMSAdvancedTextualRequest;

Non preoccuparti, la maggior parte di queste classi le vedremo a breve. La prima cosa da fare è ottenere un’istanza di client SendMultipleTextualSmsAdvanced. È possibile ottenerla fornendo l’oggetto di configurazione di autenticazione:


$configuration = new BasicAuthConfiguration($_POST['username'], $_POST['password'], 'http://api.infobip.com/');
$client = new SendMultipleTextualSmsAdvanced($configuration); 

Nota l’ultimo parametro nel costruttore BasicAuthConfiguration ed il suo utilizzo del protocollo http. Questo è fatto per una questione di semplicità. Nella tua implementazione di produzione dovresti escludere completamente questo parametro. In questo caso l’oggetto di configurazione sarà predefinito per l’utilizzo di http. Vedi la nota del capitolo introduttivo.

Ora hai un $client a cui puoi richiedere di eseguire le richieste per te. Gestirà le richieste di conversione in JSON, impostando ed eseguendo richieste http e analizzando le risposte API per te. Tutto quello che resta da fare è compilare il modello di richiesta e visualizzare la risposta all’utente.

COSTRUIRE LA RICHIESTA

In generale, il client API consente di inviare messaggi di testo diverso, ciascuno a più numeri di telefono in una singola richiesta. In questo esempio invieremo un messaggio di testo solo a un destinatario. Per assemblare la richiesta avrai bisogno di tre oggetti. Cominceremo con la destinazione:

    
$destination = new Destination();
$destination->setTo($_POST['toInput']);
$destination->setMessageId($_POST['messageIdInput']);

La proprietà to è il numero di telefono a cui gli sms saranno inviati mentre l’id message è un po’ più interessante. Questa proprietà verrà utilizzata in seguito per identificare in modo univoco il messaggio sms quando, ad esempio, recupererai i registri di log. Vedremo che questo verrà utilizzato nel capitolo “Recuperare i log di messaggio” di questo tutorial. Nota che, mentre la proprietà to è richiesta, lo stesso non vale per l’id messagge ed il messaggio sms verrà inviato con successo se questo non verrà impostato. In questo caso l’API genera un id del messaggio random che riceverai nella risposta a questa richiesta. 

Il modello successivo è il messaggio stesso. Consente di specificare più destinazioni, ognuna delle quali riceverà lo stesso testo. Puoi passare un array con una sola destinazione:

$message = new Message();
$message->setDestinations([$destination]);
$message->setFrom($_POST['fromInput']);
$message->setText($_POST['textInput']);
$message->setNotifyUrl($_POST['notifyUrlInput']);
$message->setNotifyContentType($_POST['notifyContentTypeInput']);
$message->setCallbackData($_POST['callbackDataInput']);

Le proprietà from e text definiscono parte del messaggio sms visibile al destinatario del messaggio. Nello specifico, from sarà visualizzato come mittente del messaggio e text sarà naturalmente il testo inviato. Dall’altra parte, notifyUrl, notifyContentType e callbackData sono proprietà utilizzate per generare il rapporto di consegna e per inviarlo di nuovo. Ulteriori informazioni sui rapporti di consegna saranno disponibili nel capitolo “Ricevere un rapporto di consegna”. 

Infine, inserisci il messaggio in un modello di richiesta:

$requestBody = new SMSAdvancedTextualRequest();
$requestBody->setMessages([$message]);


Visualizzando la risposta

Sia con $requestBody che $client è possibile istruire il $client per eseguire la richiesta e analizzare la risposta con una singola riga:

$response = $client->execute($requestBody);

È importante gestire tutti i casi limite e informare l’utente di tutto ciò che accade nelle nostre applicazioni. In questo caso vuol dire gestire correttamente sia le chiamate API riuscite che quelle non riuscite. È possibile ottenere questo inserendo il metodo chiamata $client->execute in un blocco try-catch. Approssimativamente dovrebbe apparire così:

try {
   $apiResponse = $client->execute($requestBody);
   // display results
} catch (Exception $apiCallException) {
   // display the error message
}

 

Per visualizzare i risultati, scorri l’elenco dei messaggi di risposta inviati con un ciclo e scrivi una singola riga per ciascuno dei messaggi inviati. Nel nostro esempio abbiamo scelto di presentare: messageId, to, smsCount, status, ma puoi scegliere quello che vuoi. Il codice dovrebbe essere così:

getMessages(); foreach ($messages as $message) { echo ""; echo "" . $message->getMessageId() . ""; echo "" . $message->getTo() . ""; echo "" . $message->getStatus()->getGroupId() . ""; echo "" . $message->getStatus()->getGroupName() . ""; echo "" . $message->getStatus()->getId() . ""; echo "" . $message->getStatus()->getName() . ""; echo "" . $message->getStatus()->getDescription() . ""; echo "" . $message->getSmsCount() . ""; echo ""; } ?>

N.B.: in questo esempio invieremo un solo messaggio a una destinazione, in modo che l’elenco di risposta del messaggio inviato contenga un solo elemento e non ci sia bisogno di ripeterlo. Tuttavia, se decidi di inviare un messaggio a più di una destinazione, dovrai scorrere l’elenco delle risposte. Se si verifica l’eccezione, potrebbe presentarsi un messaggio di errore dettagliato all’utente come di seguito:

 
    

Il codice mostrato qui sopra cercherà di analizzare la risposta di errore dall’API e se anche ciò dovesse fallire, verrà comunque stampato qualunque messaggio contenuto nella $apiCallException. 

E questo è il codice di cui hai bisogno per inviare un messaggio sms! Adesso hai un’app funzionale per inviare messaggi. Puoi trovare il codice completo su advancedSms.php.

RECUPERARE I LOG DEI MESSAGGI

La pagina dei log dei messaggi inviati (logs.php) viene utilizzata per recuperare i log dei messaggi inviati e farli visualizzare ai tuoi utenti. Questa pagina contiene il modulo di input per le credenziali necessarie per recuperare i log dall’API di Infobip. Inoltre, consente all’utente di filtrare tutti i log disponibili o per numero di telefono di destinazione o tramite ID del messaggio esatto. Con il pulsante di invio, la pagina POSTERA’ questi campi a se stesso.

UTILIZZARE L'API CLIENT DI INFOBIP

Come abbiamo fatto nel capitolo “Inviare un sms”, dovremo utilizzare un paio di classi dalla libreria API client. Questa volta le istruzioni saranno le seguenti:


    require_once __DIR__ . '/vendor/autoload.php';
 
use infobip\api\client\GetSentSmsLogs;
use infobip\api\configuration\BasicAuthConfiguration;
use infobip\api\model\sms\mt\logs\GetSentSmsLogsExecuteContext;
And again, you can instantiate a client object by passing the authentication configuration to it's constructor:
$configuration = new BasicAuthConfiguration($_POST['username'], $_POST['password'], 'http://api.infobip.com/');
$client = new GetSentSmsLogs($configuration);

Ancora una volta, puoi escludere l’ultimo parametro del costruttore di BasicAuthConfiguration dal tuo codice di produzione. Vedi la nota nel capitolo introduttivo.

COSTRUIRE IL CONTESTO DI ESECUZIONE

A differenza del precedente capitolo in cui stavi inviando i dati all’API di Infobip, in questo caso ci interessa principalmente il recupero dei dati dall’API. Tuttavia, potresti ancora voler filtrare i log recuperati da alcune proprietà. Ad esempio, potresti voler recuperare solo 20 log inviati a un determinato numero di telefono. È possibile specificare tali parametri di filtro utilizzando il modello GetSentSmsLogsExecuteContext:

 
$context = new GetSentSmsLogsExecuteContext();
$context->setMessageId($_POST['messageIdInput']);
$context->setTo($_POST['toInput']);
$context->setLimit(20);


Visualizzando la risposta

Come nel capitolo precedente, vogliamo gestire sia le chiamate API riuscite che quelle non riuscite. Ancora una volta, potrai utilizzare il blocco try-catch per inserire la chiamata in $client->execute e gestire l’eventuale Exception nel blocco catch:


try {
   $apiResponse = $client->execute($context);
   // display results
} catch (Exception $apiCallException) {
   // display the error message
}

Se tutto è andato bene e la chiamata API è riuscita, puoi scorrere l’elenco dei risultati forniti dall’API con un ciclo per ciascuno. In questo caso il ciclo è necessario perché abbiamo richiesto di recuperare più log di messaggi. Per ogni estratto di log sono necessarie delle informazioni che vanno presentate al tuo utente in una tabella con colonne diversificate. Nel nostro esempio abbiamo scelto: messageId, to, from, text, status e sentAtproperties. Come prima, puoi scegliere quello che desideri. Di seguito il codice:


    getResults();
foreach ($logs as $log) {
	echo "";
	echo "" . $log->getMessageId() . "";
	echo "" . $log->getTo() . "";
	echo "" . $log->getFrom() . "";
	echo "" . $log->getText() . "";
	echo "" . $log->getStatus()->getGroupName() . "";
	echo "" . $log->getStatus()->getDescription() . "";
	$formattedSentAt = $log->getSentAt()->format("M d, Y - H:i:s P T");
	echo "" . $formattedSentAt . "";
	echo "";
} ?>

Infine, potrai gestire l’eccezione come hai fatto nel capitolo precedente:


Ancora una volta, il codice completo per questa pagina è disponibile su logs.php.

RICEVERE IL RAPPORTO DI CONSEGNA

Questa funzione è leggermente diversa dalle due precedenti: la pagina dlrPush.php non viene utilizzata per richiedere dati, ma li aspetta. Quando i dati vengono inviati su questa pagina, possono essere analizzati e mostrati all’utente in modo appropriato.

N.B.: per visualizzare i rapporti di consegna all’interno della demo, questi dovrebbero essere inviati dalla pagina dei messaggi di testo pienamente funzionali inserendo l’URL della pagina dlrPush.php nel campo Notifica URL. Inoltre, il campo Notifica ContentType in quella pagina determina quale tipo di corpo sta per arrivare.

RICEVERE IL RAPPORTO DI CONSEGNA SPEDITO

   
$responseBody = file_get_contents('php://input');
if ($responseBody) {
	file_put_contents("dlr.txt", $responseBody);
} else {
	$fileBody = file_get_contents("dlr.txt");
	if ($fileBody <> "") {
    	if (isJson($fileBody)) {
        	$responseJson = json_decode($fileBody);
        	$results = $responseJson->results;
    	} else if (strpos(trim($fileBody), '') === 0) {
        	$responseXml = simplexml_load_string($fileBody);
        	$results = $fileBody->results->result;
    	}
	}
}

Il codice di cui sopra mostra che il metodo file_get_contents ('php://input') viene utilizzato per ottenere dei dati POST grezzi come stringa. Questi dati POST grezzi sono rappresentati dal rapporto di consegna proveniente da Infobip e vengono salvati localmente in un file dlr.txt withfile_put_contents ("dlr.txt", $responseBody). L’altro blocco utilizza il corpo di richiesta salvato nel file e mostra come verificare se i dati vengono analizzati in XML o JSON e come estrarre i rapporti di consegna spediti. Per l'XML verifichiamo se il corpo della stringa di risposta inizia con, altrimenti cerchiamo di decodificarla senza errori - funzione isJason(). Se tutte le condizioni sono FALSE, la variabile $result rimane disattivata, il che significa che dovremmo dire all’utente che non è stato spedito nessun rapporto di consegna al server di richiamata.

N.B.: il trattamento dei dati tramite file viene utilizzato in modo che questa demo possa mostrare l’invio e la ricezione di messaggi allo stesso tempo, riutilizzando la stessa pagina. Il salvataggio su file si verifica quando arriva il rapporto di consegna, mentre la lettura avviene quando la pagina viene richiesta tramite la richiesta GET del browser. Ogni nuovo rapporto di consegna sostituirà quello precedente in modo da poter visualizzare solo l’ultimo rapporto. Inoltre, il rapporto viene visualizzato a chiunque visiti la pagina indipendentemente dall’utente che ha inviato il messaggio originale. Nelle applicazioni di produzione, potresti voler salvare ogni rapporto senza riscrivere quelli precedenti e mostrare i rapporti solo agli utenti autorizzati a vederli.

ANALIZZARE IL RISULTATO

L’analisi dei rapporti di consegna spediti è simile all’analisi della risposta di “Inviare SMS” e dei metodi di log dei messaggi inviati, a meno che non controlliamo il codice di risposta HTTP (perché non c’è alcuna risposta). Tutto quello che dobbiamo fare è scegliere quali informazioni provenienti dai rapporti di consegna spediti vogliamo mostrare e scriverlo sulla pagina.

Di Josip Antolis, Software Engineer / Team Leader

Crea oggi la tua app web

Inizia ora