Verwendung von Vonage APIs mit Drupal

Voraussetzungen

• PHP 7.3 oder höher

• SQLite 3.26 oder höher ODER MySQL 5.7.8 oder höher

Vonage API-Konto

Um dieses Tutorial durchzuführen, benötigen Sie ein Vonage API-Konto. Wenn Sie noch keines haben, können Sie sich noch heute anmelden und mit einem kostenlosen Guthaben beginnen. Sobald Sie ein Konto haben, finden Sie Ihren API-Schlüssel und Ihr API-Geheimnis oben auf dem Vonage-API-Dashboard.

In diesem Lernprogramm wird auch eine virtuelle Telefonnummer verwendet. Um eine zu erwerben, gehen Sie zu Rufnummern > Rufnummern kaufen und suchen Sie nach einer Nummer, die Ihren Anforderungen entspricht.

Sind Sie bereit, mit dem Bau zu beginnen?

Erleben Sie nahtlose Konnektivität, Echtzeit-Messaging und kristallklare Sprach- und Videoanrufe - alles auf Knopfdruck.

Drupal installieren

Mit der Einführung von Drupal 8 können Sie Drupal jetzt mit dem Composerdem Paketmanager von PHP, installieren. Composer kümmert sich darum, Ihre Website auf dem neuesten Stand zu halten und alle Abhängigkeiten unserer Website zu verwalten, kann aber auch zur Installation einer einfachen Drupal-Installation verwendet werden. Klonen wir das drupal/recommended-project Repository als Projekt klonen, um eine einfache Drupal-Installation durchzuführen:

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

Composer lädt das Repository herunter und ruft automatisch die Abhängigkeiten für unsere Anwendung ab, die zum Zeitpunkt dieses Schreibens Drupal 9.1 abruft. Wir können in das vonage-and-drupal/ Verzeichnis wechseln und die Installation fortsetzen.

Während wir Drupal hinter einem Webserver wie Apache's httpd oder Nginx laufen lassen können, hat PHP einen eingebauten Entwicklungsserver, den wir verwenden können. Öffnen Sie ein weiteres Terminal-Fenster und wechseln Sie dorthin, wo wir den Drupal-Code heruntergeladen haben, und starten Sie den Server:

$ php -S localhost:3000 -t web

Öffnen Sie einen Webbrowser und besuchen Sie http://localhost:3000 und Sie werden mit dem Drupal-Installationsformular begrüßt!

Wir werden eine Basisinstallation verwenden, also gehen Sie durch den Installationsassistenten und wählen Sie die folgenden Optionen:

1. Wählen Sie Ihre Sprache und klicken Sie auf "Speichern und weiter". In diesem Fall nehmen wir die Standardeinstellung "Englisch".

2. Wählen Sie das Installationsprofil "Standard" und klicken Sie auf "Speichern und weiter".

3. Wählen Sie als Datenbanktyp "SQLite" und lassen Sie die restlichen Optionen auf den Standardwerten. Klicken Sie auf "Speichern und fortfahren".

4. Geben Sie unter "Site konfigurieren" den gewünschten Site-Namen, E-Mail, Benutzernamen und Passwort ein. Klicken Sie auf "Speichern und fortfahren".

Drupal wird die Installation abschließen. Sie werden automatisch eingeloggt und sind bereit, mit dem Spielen zu beginnen!

Wenn Sie PHP 7.4 oder 8.0 verwenden, kann es sein, dass Sie eine Fehlermeldung erhalten, dass Ihre SQLite-Version zu niedrig ist. PHP hat SQLite ab 7.4 entbündelt und verwendet die Version, die auf Ihrem Betriebssystem installiert ist. Wenn Sie Ubuntu 18.04 oder ältere Versionen von Fedora oder CentOS verwenden, kann es sein, dass Sie Drupal 9 nicht mit SQLite installieren können. In diesem Fall sollten Sie MySQL oder MariaDB als Datenbank anstelle von SQLite verwenden.

Installation der Vonage APIs

Da wir nun eine Drupal-Installation haben, können wir entscheiden, wie wir mit den Vonage-APIs interagieren wollen. Während Drupal in der Lage ist, HTTP-Anfragen mit Hilfe des eingebauten \Drupal::httpClient()verwenden kann, müssen sich die Entwickler um API-Endpunkte, JSON-Strukturen und Authentifizierung für jede einzelne Anfrage kümmern. Dies ist die anspruchsvollste Implementierungsoption.

Vonage stellt eine PHP-Bibliothek zur Verfügung, die einen großen Teil des Standardcodes für jede Anfrage übernehmen kann. Diese Bibliothek eignet sich für die meisten PHP-Applikationen, da Sie lediglich ein \Vonage\Client Objekt zu erstellen und Ihre Anmeldedaten anzugeben. Diese Bibliothek funktioniert gut für Drupal, aber der Knackpunkt ist, dass das von Ihnen erstellte Objekt für den Rest des Systems zugänglich sein muss. Sie müssten ein kleines Modul schreiben, das den Vonage-Client in die Service-Schicht von Drupal einbindet.

Um Ihnen dabei zu helfen, hat Vonage ein Modul entwickelt, das eine Verwaltungsschnittstelle zum Hinzufügen Ihrer Anmeldeinformationen bereitstellt, den Vonage API-Client erstellt und ihn beim Servicesystem registriert. Wenn Sie sich den Quellcode ansehen möchten, finden Sie ihn unter https://github.com/Nexmo/vonage-php-drupal-module. Wir haben es auch als Bibliothek zur Verfügung gestellt, die über Composer installiert werden kann, indem Sie vonage/vonage_drupal.

Da wir Composer verwenden, um unsere Abhängigkeiten zu verwalten, können wir zu unserem Terminal zurückkehren und das Paket zu unserer Website hinzufügen:

$ composer require vonage/vonage_drupal

Composer lädt einige Abhängigkeiten herunter, und Sie sollten das Modul in web/modules/contrib/vonage_drupal. Wenn der Download abgeschlossen ist, müssen wir das Modul aktivieren, indem wir auf die Seite "Erweitern" gehen und das Modul "Vonage API SDK" aktivieren. Sie können entweder danach suchen oder nach unten zum Abschnitt "Communications" scrollen. Aktivieren Sie das Kontrollkästchen neben dem Modulnamen und klicken Sie auf "Installieren". Nach einem kurzen Moment sollte die Seite aktualisiert werden, und Sie sehen die Erfolgsmeldung "Das Modul Vonage API SDK wurde aktiviert"!

Jetzt können wir das Modul konfigurieren, indem wir auf die Seite "Konfiguration" gehen und unter der Überschrift "SYSTEM" auf "Vonage API-Einstellungen" klicken. Auf dieser Seite können wir zwei Sätze von Anmeldeinformationen konfigurieren, die das Modul zur Einrichtung unseres SDK-Clients verwenden wird. Die meisten Vonage-APIs verwenden das Vonage-API-Geheimnis und den Schlüssel, die Sie in Ihrem Vonage Dashboard. Füllen Sie das Formular aus und klicken Sie auf "Konfiguration speichern". Wenn Sie eine API verwenden, die eine Authentifizierung mit privatem Schlüssel verwendet, wie unsere Voice API, können Sie diesen Abschnitt erweitern und die Anwendungs-ID und den privaten Schlüssel eingeben.

Wenn Sie Ihre Anmeldedaten testen möchten, können Sie die Registerkarten "Vonage SMS API Testing" oder "Vonage Voice API Testing" auf der Konfigurationsseite verwenden. Wenn es ein Problem gibt, sollte das System den aufgetretenen Fehler zurückgeben. Geben Sie nun Ihr API-Geheimnis und Ihren Schlüssel ein und speichern Sie die Konfiguration.

Verwendung des Vonage API SDK

Das Vonage Drupal-Modul konfiguriert automatisch das Client-Objekt und macht es über das Drupal-Service-Container-System verfügbar. Diese Funktionalität bedeutet, dass wir das SDK in unsere benutzerdefinierten Module einbinden können, also lassen Sie uns ein kleines Modul erstellen. Wir können drush verwenden, um ein Modul-Skelett für uns zu erstellen. Führen Sie die folgenden Befehle aus, um drush für unser Projekt zu installieren und um eine Reihe von Fragen zur Erstellung des Moduls zu beantworten:

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

1. Name des Moduls: Vonage Hallo Welt

2. Name der Maschine: vonage_hello_world

3. Beschreibung des Moduls: Modul zum Testen der Vonage-API

4. Paket: Benutzerdefiniert

5. Abhängigkeiten: Keine Abhängigkeiten, ENTER drücken

6. Beantworten Sie alle Fragen zur Schöpfung mit "Nein", außer den Fragen zur Schöpfung:

   1. Möchten Sie einen Controller erstellen?

Dieser Befehl erstellt ein neues Modul in web/modules/vonage_hello_worldsowie einen neuen Controller, in dem wir das SDK verwenden können!

Öffnen Sie web/modules/vonage_hello_world/src/Controller/VonageHelloWorldController.php in Ihrem Editor. Das erste, was wir tun müssen, um das SDK in den Controller zu bekommen, ist das Überschreiben der create() Methode. Diese Methode wird von Drupal zum Erstellen von Controllern verwendet und übergibt den Service Locator als solchen. Fügen wir eine create() Methode überschreiben:

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

Durch die Übergabe des Containers als Argument in der Methode können wir den Vonage-API-Client unter Verwendung des Klassennamens aus dem Container ziehen. Intern ruft dies die Fabrik auf, die unsere zuvor eingegebenen Anmeldedaten aufnimmt und ein verwendbares Objekt erzeugt. Dieses Objekt können wir dann an einen neuen Controller übergeben. Wo wir gerade dabei sind, fügen wir eine __construct() Methode hinzufügen, die unser neues SDK aufnimmt, und eine Eigenschaft, in der wir es speichern.

protected $client;

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

Da wir das Modul mit dem drush Befehl verwendet haben, um unser Modul zu erstellen, wurde automatisch eine Methode zu unserem Controller hinzugefügt, die mit einer Route verbunden ist. Wir können die build() Methode bearbeiten und einen Aufruf zum Senden einer SMS an unser Mobiltelefon hinzufügen. Mit dem SMS-Snippet senden können wir den Client verwenden, den wir zum Senden der SMS übergeben haben. Bearbeiten Sie die build() Methode so, dass sie wie das folgende Beispiel aussieht. Stellen Sie sicher, dass Sie TO_NUMBER durch Ihre Mobiltelefonnummer und VONAGE_NUMBER durch die Nummer, die Sie bei Vonage haben. Um sicherzustellen, dass Drupal die Seite nicht zwischenspeichert, werden wir auch das Zwischenspeichern der Seite deaktivieren, wenn jemand auf diese Route zugreift.

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

Alles, was für den Versand einer SMS aus Drupal erforderlich ist, ist installiert und konfiguriert. Kehren Sie zur Drupal Admin UI zurück, gehen Sie zur Seite "Erweitern", suchen Sie "Vonage Hello World" und aktivieren Sie das entsprechende Kontrollkästchen. Klicken Sie auf "Installieren", um unser benutzerdefiniertes Modul zu installieren. Nach einem kurzen Moment sollte eine Erfolgsmeldung erscheinen, die besagt, dass wir unser Modul installiert haben.

Standardmäßig hat das drush Skelett eine Route für unseren Controller unter /vonage-hello-world/example. Gehen Sie rüber zu http://localhost:3000/vonage-hello-world/example. Es sollte ein normaler Drupal-Knoten mit der Meldung "Die Nachricht wurde erfolgreich gesendet" angezeigt werden, und Ihr Telefon sollte die SMS-Nachricht erhalten, die wir im Controller eingerichtet haben. Wenn Sie diese Seite aktualisieren, wird die SMS erneut gesendet, da wir das Caching der Ausgabe deaktiviert haben.

Weitere Lektüre

Von hier aus steht Ihnen das vollständige PHP-SDK von Vonage zur Verfügung, mit dem Sie in Ihren eigenen Modulen herumspielen können. Werfen Sie einen Blick auf unsere PHP-Code-Schnipsel für weitere Beispiele für verschiedene Dinge, die Sie mit unserem SDK für fast alle unsere APIs tun können.

Den Beispielcode für diese Demo finden Sie unter https://github.com/nexmo-community/vonage-php-sdk-drupal-9.