WIADOMOŚCI

Samouczek biblioteki klienta PHP SMS API dla aplikacji web

Published on:14 / August / 2017

Jeśli budujesz aplikację webową w języku PHP i chcesz wdrożyć funkcjonalność SMS, jesteś we właściwym miejscu. Zbudowaliśmy bibliotekę klienta API Infobip, aby Ci pomóc i napisaliśmy ten samouczek, aby przeprowadzić Cię przez wszystkie kroki procesu. W ten sposób ułatwiliśmy wdrożenie tej funkcjonalności i udostępniliśmy dodatkową warstwę zabezpieczeń Twojej witryny korzystając z naszego rozwiązania 2FA, ponieważ każde wywołanie HTTP API i serializacja modeli odbywa się poprzez naszą bibliotekę.

Ten przewodnik krok po kroku jest ulepszoną wersją naszego poprzedniego samouczka SMS API w języku PHP, napisanego tak, aby przyspieszyć wdrożenie funkcjonalności SMS w Twojej aplikacji webowej. Przejdziesz przez trzy podstawowe etapy, opisane w osobnych rozdziałach. Po pierwsze, uzyskasz informacje na temat wysyłania wiadomości SMS, a następnie pobierania logów wiadomości i otrzymywania raportów doręczenia.

Aby aplikacja webowa SMS działała poprawnie, musisz skonfigurować serwer PHP. Ponieważ biblioteka klienta wysyła żądania HTTP do interfejsu API Infobip, musisz aktywować rozszerzenie PHP cURL na swoim serwerze WWW.

W celu uruchomienia aplikacji możesz użyć pewnego rozwiązania ze zbioru rozwiązań AMP (wamp, xampp itp.). Są to zbiory oprogramowania dla różnych systemów operacyjnych składające się z serwera WWW Apache, bazy danych MySQL i obsługi języka programowania PHP. Powinieneś włączyć rozszerzenie phpcurl dla wybranej przez siebie opcji.

Zalecamy zainstalowanie composera – prostego narzędzia ułatwiającego rozwiązywanie zależności projektów PHP i uproszczającego proces pobierania i korzystania z klienta API Infobip używanego w tym projekcie. Szczegółowe instrukcje dotyczące procedury instalowania composera można znaleźć na stronie internetowej, a w tym blogu omówimy część praktyczną.

Uwaga: Aby zapewnić bezpieczne wysyłanie wiadomości SMS, na serwerze HTTPS (przy użyciu protokołu TLS) należy przechowywać poniższe przykłady. Dla uproszczenia, w tym samouczku korzystaliśmy z prostego protokołu HTTP.

 

KLIENT API INFOBIP

Aby korzystać z biblioteki klienta API Infobip, musisz ją pobrać do swojego projektu. Aby ułatwić realizację tego procesu, zalecamy użycie composera. W tym celu wystarczy tylko zdefiniować wersję klienta, z którego chcesz korzystać. Robi się to w specjalnym pliku o nazwie composer.json:

 

{

  "require": {

          "infobip/infobip-api-php-client": "2.0.1"

  }

}

 

Mając już plik „composer.json”, możesz polecić composerowi pobieranie wymienionych zależności, uruchamiając następujące polecenie z terminala:

 

„composer install” („zainstaluj composer”)

 

Teraz powinien zostać utworzony katalog dostawcy obok pliku composer.json. Jeśli spojrzysz do środka, znajduje się w nim plik o nazwie „autoload.php”, który przyda Ci się później. Dodatkowo katalog dostawcy zawiera osobne podkatalogi dla kodu biblioteki klienta API Infobip i jej zależności.

WYŚLIJ WIADOMOŚĆ SMS

W pełni funkcjonalna strona wiadomości tekstowych (advancedSms.php) zawiera formularz wejściowy do wysyłania wiadomości SMS. Wymagane pola to nazwa użytkownika, hasło i numer telefonu adresata, wszystkie pozostałe wartości są opcjonalne. Dodatkowe wyjaśnienia dotyczące powiadamiania o typie zawartości treści URL i oddzwaniania możesz znaleźć w rozdziale Odbiór raportów doręczenia. Przycisk „Wyślij” powoduje wysłanie żądania do strony określonej w atrybucie akcji formularza. W poniższym przykładzie, żądanie zostanie wysłane do tej samej strony.

 

form action="<?php echo htmlspecialchars($_SERVER["PHP_SELF"]); ?>" method="POST" ...

 

Zanim utworzysz wywołanie API, sprawdź, czy użytkownik przesłał wszystkie potrzebne pola. W tym przykładzie sprawdziliśmy tylko pole „ToInput”. Nie trzeba sprawdzać wszystkich pól, ponieważ nie wszystkie są wymagane przez API, a wszystkie brakujące właściwości zostaną po prostu zignorowane przez klienta. Jeśli strona jest wczytywana po raz pierwszy, pamiętaj, że tych pól nie będzie.

KORZYSTANIE Z KLIENTA API INFOBIP

Będziemy korzystać z klienta API Infobip do przekazywania żądań http. Spowoduje to znaczne skrócenie kodu, ale najpierw trzeba poinstruować PHP, gdzie można znaleźć niezbędne klasy. Robi się to żądając poprzednio omówionego pliku „autoload.php” z katalogu dostawcy, a następnie określając części biblioteki klienta, które zostaną użyte:

 

      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;

 

Nie martw się o większość z tych klas, wkrótce zobaczymy je w akcji. Pierwszą rzeczą, którą musimy zrobić, jest pobranie instancji klienta „SendMultipleTextualSmsAdvanced”. Możesz ją pobrać dostarczając jej obiekt konfiguracji uwierzytelniania:

 

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

$client = new SendMultipleTextualSmsAdvanced($configuration);

 

Zwróć uwagę na ostatni parametr w konstruktorze „BasicAuthConfiguration” i wykorzystanie przez niego protokołu http. Odbywa się to tylko dla uproszczenia. Podczas wdrożenia w środowisku produkcyjnym, powinieneś pozostawić ten parametr w całości. W takim przypadku obiekt konfiguracji domyślnie użyje protokołu https. Patrz uwaga w rozdziale wprowadzającym.

Teraz masz klienta „$client”, który może poprosić o wykonanie Twoich żądań. Zajmie się za Ciebie przetwarzaniem żądań w JSON, konfigurowaniem i wykonywaniem żądań HTTP oraz analizowaniem odpowiedzi API. Pozostaje tylko wypełnienie modelu żądania i wyświetlenie odpowiedzi użytkownikowi.

BUDOWANIE ŻĄDANIA

Ogólnie rzecz biorąc, klient API umożliwia wysyłanie różnych wiadomości tekstowych, każdej z wieloma numerami telefonu w jednym żądaniu. W tym przykładzie wyślemy tylko jedną wiadomość tekstową do jedne adresata. Aby skompletować żądanie, potrzebujesz trzech obiektów. Zaczniemy od adresata:   

$destination = new Destination();

$destination->setTo($_POST['toInput']);

$destination->setMessageId($_POST['messageIdInput']);

Właściwość „to” („do”) oznacza numer telefonu, na który wysyłane będą wiadomości sms, natomiast parametr „messageId” („ID wiadomości”) jest nieco ciekawszy. Ta właściwość jest później wykorzystywana do unikatowego identyfikowania wiadomości sms podczas, na przykład, pobierania logów. Zobaczymy to w rozdziale Pobieranie logów wiadomości w tym samouczku. Zauważ, że o ile właściwość „to” jest wymagana, „messageId” już nie jest i wiadomości sms zostaną pomyślnie wysłane nawet, jeśli parametr ten nie zostanie ustawiony. W takim przypadku API wygeneruje losowy identyfikator wiadomości, który otrzymasz w odpowiedzi na to żądanie.

Następnym modelem jest sama wiadomość. Pozwala określić wielu adresatów, z których każdy otrzyma ten sam tekst. Możesz przekazać tablicę tylko z jednym adresatem:

 

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

 

Właściwości „from” („od”) i „text” („tekst”) określają część wiadomości sms widoczną dla odbiorcy wiadomości. W szczególności, właściwość „from” będzie wyświetlana jako nadawca wiadomości, a „text” będzie naturalnie treścią wysłanej wiadomości. Z drugiej strony „notifyUrl”, „notifyContentType” i „callbackData” to metawłaściwości, które są używane do wygenerowania i odesłania raportu doręczenia. Więcej informacji na temat raportów doręczenia można znaleźć w rozdziale Odbiór raportów doręczenia.

Na końcu, konfigurujesz wiadomość w modelu żądania:

 

$requestBody = new SMSAdvancedTextualRequest();

$requestBody->setMessages([$message]);

 

WYŚWIETLANIE ODPOWIEDZI

Gdy masz gotowe właściwości „$requestBody” i „$client”, możesz polecić $client wykonanie żądania i przeanalizowanie odpowiedzi w jednym wierszu:

 

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

 

Ważne jest, aby obsługiwać wszystkie przypadki brzegowe i informować użytkownika o wszystkim, co dzieje się z naszymi aplikacjami. W tym przypadku oznacza to prawidłowe zarządzanie zarówno udanymi, jak i nieudanymi wywołaniami API. Można to osiągnąć przez skonfigurowanie wywołania metody „$client->execute” w bloku „try-catch”. Na wysokim poziomie powinno to wyglądać tak:

 

try {

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

   // display results

} catch (Exception $apiCallException) {

   // display the error message

}

 

Aby wyświetlić wyniki, należy powtarzać kolejne iteracje dla odpowiedzi na wysłane odpowiedzi na tablicy z pętlą foreach i napisać pojedynczy wiersz dla każdej z wysłanych wiadomości. W naszym przykładzie wybraliśmy: messageId, to, smsCount, status, ale możesz wybrać co chcesz. Kod powinien wyglądać tak:

 

<?php

$messages = $apiResponse->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 "";

}

?>

 

Uwaga: W tym przykładzie wysyłamy tylko jedną wiadomość do jednego adresata, więc tablica odpowiedzi na wysłane wiadomości będzie zawierała tylko jeden element i nie ma potrzeby jej zapętlania. Jeśli jednak zdecydujesz się wysłać wiadomość do więcej niż jednego adresata, będziesz musiał przeanalizować całą tablicę odpowiedzi. Jeśli wystąpi wyjątek, w taki sposób możesz przekazać użytkownikowi szczegółowe informacje o błędzie:   

 

          An error occurred! Reason:

          <?php

          $errorMessage = $apiCallException->getMessage();

          $errorResponse = json_decode($apiCallException->getMessage());

          if (json_last_error() == JSON_ERROR_NONE) {

          $errorReason = $errorResponse->requestError->serviceException->text;

          } else {

          $errorReason = $errorMessage;

          }

          echo $errorReason;

          ?>

 

Powyższy kod będzie próbował przeanalizować odpowiedź o błędzie z interfejsu API, a w przypadku niepowodzenia, wydrukuje jakąkolwiek wiadomość zawartą w $apiCallException.

I to jest cały kod, który potrzebujesz, aby wysłać wiadomość sms! Masz teraz w pełni funkcjonalną aplikację do wysyłania wiadomości. Pełny kod można znaleźć na stronie advancedSms.php.

POBIERANIE LOGÓW WIADOMOŚCI

Strona logów wiadomości wysłanych (logs.php) służy do pobierania logów wysłanych wiadomości i wyświetlania ich użytkownikom. Zawiera formularz wejściowy poświadczeń potrzebnych do pobrania logów z interfejsu API Infobip. Ponadto umożliwia filtrowanie wszystkich dostępnych logów według dowolnego numeru adresata lub dokładnego identyfikatora wiadomości. Po naciśnięciu przycisku „Wyślij”, strona wyśle te pola do siebie samej.

KORZYSTANIE Z KLIENTA API INFOBIP

Tak samo, jak w rozdziale Wysyłanie wiadomości SMS, musimy użyć kilku klas z biblioteki klienta API. Tym razem polecenie „use” będzie wyglądało następująco:

 

    require_once __DIR__ . '/vendor/autoload.php';

 

use infobip\api\client\GetSentSmsLogs;

use infobip\api\configuration\BasicAuthConfiguration;

use infobip\api\model\sms\mt\logs\GetSentSmsLogsExecuteContext;

I znowu można zainicjować obiekt klienta, przekazując konfigurację uwierzytelniania do konstruktora:

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

$client = new GetSentSmsLogs($configuration);

 

Ponownie możesz pozostawić ostatni parametr konstruktora „BasicAuthConfiguration” w kodzie produkcyjnym. Patrz uwaga w rozdziale wprowadzającym.

BUDOWANIE KONTEKSTU WYKONANIA

W przeciwieństwie do poprzedniego rozdziału, w którym wysyłano dane do interfejsu API Infobip, w tym przypadku chodzi przede wszystkim o pobieranie danych z interfejsu API. Możesz jednak nadal filtrować pobrane logi według niektórych właściwości. Możesz, na przykład, pobrać tylko 20 logów wysłanych do określonego numeru telefonu. Możesz określić parametry filtrowania przy użyciu modelu „GetSentSmsLogsExecuteContext”:

 

$context = new GetSentSmsLogsExecuteContext();

$context->setMessageId($_POST['messageIdInput']);

$context->setTo($_POST['toInput']);

$context->setLimit(20);

WYŚWIETLANIE ODPOWIEDZI

Podobnie, jak w poprzednim rozdziale, chcemy obsługiwać zarówno udane, jak i nieudane wywołania API. Znowu możesz użyć bloku „try-catch”, aby skonfigurować wywołanie do „$client->execute” i obsłużyć potencjalne wyjątki w bloku „catch”:

 

try {

   $apiResponse = $client->execute($context);

   // display results

} catch (Exception $apiCallException) {

   // display the error message

}

 

Jeśli wszystko poszło dobrze i wywołanie API zakończyło się powodzeniem, możesz dokonać iteracji na tablicy wyników zwróconych przez interfejs API z pętlą foreach. W tym przypadku pętla jest konieczna, ponieważ poprosiliśmy o pobranie wielu logów wiadomości. Dla każdego loga pobierz potrzebne informacje i przedstaw je użytkownikowi w wierszu tabeli. W naszym przykładzie wybraliśmy: messageId, to, from, text, status i sentAtproperties. Tak jak poprzednio, możesz wybrać co chcesz. Nasz kod wygląda tak:

 

    <?php

$logs = $apiResponse->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 "";

} ?>

 

Na koniec możesz obsłużyć wyjątek tak samo, jak w poprzednim rozdziale:

 

          An error occurred! Reason:

          <?php

          $errorMessage = $apiCallException->getMessage();

          $errorResponse = json_decode($apiCallException->getMessage());

          if (json_last_error() == JSON_ERROR_NONE) {

          $errorReason = $errorResponse->requestError->serviceException->text;

          } else {

          $errorReason = $errorMessage;

          }

          echo $errorReason;

          ?>

 

Ponownie, pełny kod dla tej strony możesz znaleźć na logs.php.

ODBIÓR RAPORTÓW DORĘCZENIA

Ta funkcjonalność nieco się różni od poprzednich – strona „dlrPush.php” nie jest używana do żądania wybranych danych, ale w rzeczywistości ich oczekuje. Po wypchnięciu danych na tę stronę, można je odpowiednio analizować i wyświetlać użytkownikowi.

Uwaga: Aby zobaczyć raporty doręczenia w trybie demonstracyjnym, powinny zostać wypchnięte z w pełni funkcjonalnej strony wiadomości tekstowych po wpisaniu adresu URL strony „dlrPush.php” w polu „Notify URL”. Ponadto, pole „Notify ContentType” na tej stronie określa typ nadchodzącej treści.

OTRZYMYWANIE WYPCHNIĘTEGO RAPORTU DORĘCZENIA  

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

          }

          }

}

Powyższy kod pokazuje, że metoda „file_get_contents('php://input')” jest używana do pobierania surowych danych POST w postaci ciągu znaków. Te surowe dane POST są raportem doręczenia pochodzącym z Infobip i są zapisywane lokalnie w pliku „dlr.txt” za pomocą „file_put_contents("dlr.txt", $responseBody)”. Blok „else” wykorzystuje treść żądania zapisanego w pliku i pokazuje, jak sprawdzić, czy dane są analizowane jako XML czy JSON oraz jak uzyskać wypchnięte raporty doręczenia. W przypadku języka XML sprawdzamy, czy ciąg znaków treści odpowiedzi zaczyna się od , a jeśli nie, próbujemy odkodować go bez błędów - isJson() function. Jeśli wszystkie warunki są FAŁSZYWE, zmienna „$result” pozostanie nieustawiona, co oznacza, że powinniśmy przekazać użytkownikowi informację, że serwer oddzwaniania nie otrzymał żadnego raportu doręczenia.

Należy pamiętać, że dane są obsługiwane za pośrednictwem pliku, dzięki czemu wersja demonstracyjna może jednocześnie wyświetlać wysyłanie i odbieranie wiadomości, ponownie wykorzystując tę samą stronę. Dane są zapisywane do pliku w momencie nadejścia raportu doręczenia, natomiast dane są odczytywane, gdy strona otrzyma żądanie „GET” przeglądarki. Każdy nowy raport doręczenia zastępuje poprzedni, zatem możesz przeglądać tylko najnowszy raport. Ponadto, raport jest pokazywany każdemu odwiedzającemu stronę niezależnie od użytkownika, który przesłał pierwotną wiadomość. W aplikacji produkcyjnej możesz chcieć zapisać każdy z tych raportów bez nadpisywania poprzednich i wyświetlać raporty tylko użytkownikom uprawnionym do ich przeglądania.

ANALIZOWANIE WYNIKÓW

Analizowanie wypchniętych raportów doręczenia jest podobne do analizowania odpowiedzi na wysłanie wiadomości SMS i logów wysłanych wiadomości, z wyjątkiem tego, że nie sprawdzamy kodu odpowiedzi HTTP (ponieważ w ogóle nie ma odpowiedzi). Jedyne, co musimy zrobić, to wybrać, które informacje z raportów doręczenia chcemy pokazać i zapisać je na stronie.

 

Josip Antolis, Inżynier Oprogramowania / Kierownik Zespołu

 

JUŻ DZIŚ ZBUDUJ SWOJĄ APLIKACJĘ WEBOWĄ

ROZPOCZNIJ TERAZ