So erstellen Sie eine Slack-Schnittstelle für Ihre PHP-Anwendung

() translation by (you can also view the original English article)

Wenn Sie die Entwicklung von Bürokommunikationswerkzeugen im letzten Jahr verfolgt haben, sind Sie sicher über Slack informiert. Auf der Oberflächenebene ist Slack eine weitere Chat-Anwendung, die für Unternehmen entwickelt wurde. Aufgrund ihrer Liebe zum Detail und ihrer Erweiterbarkeit sagen viele Kommentatoren jedoch bereits, dass das Tool unsere Arbeitsweise in der Zukunft dramatisch verändern wird.

Als Entwickler sind wir in einer guten Position, um den Trend zu überdenken und darüber nachzudenken, wie wir Slack als chatbasierte Benutzeroberfläche für unsere Anwendungen verwenden können.

Deshalb lernen Sie in diesem Lernprogramm, wie Sie mit der Integration Ihrer PHP-Anwendung in Slack beginnen, indem Sie sie dazu veranlassen, Nachrichten in einem Slack-Kanal zu posten und auf Slash-Befehle zu reagieren.

Sie können den Quellcode für das Lernprogramm aus dem verknüpften GitHub-Repository herunterladen oder selbst erstellen, während Sie das Lernprogramm durchgehen.

Der Code des Tutorials besteht aus zwei Teilen:

ein reines, aber komplettes Interface für die Kommunikation mit Slack
Ein einfaches Beispielskript, das die Slack-Klasse verwendet, um Benachrichtigungen zu senden und auf einen Schrägstrichbefehl zu reagieren

Lass uns anfangen.

1. Erstellen Sie Ihre Anwendung und verbinden Sie sie mit Slack

Eine schnelle Google-Suche nach dem Begriff "Slack PHP" zeigt eine Handvoll verschiedener Slack-Schnittstellen an, die von anderen Entwicklern erstellt wurden. Sie können also genauso gut mit einem vorhandenen Projekt arbeiten und es mit Ihrer Anwendung verbinden.

Die API ist jedoch nicht kompliziert, daher gibt es keinen Grund, keinen Spaß zu haben und das Projekt von Grund auf zu betrachten. Auf diese Weise wissen Sie, was in der API (und Ihrer Integration) enthalten ist. Es ist immer gut, die Dinge ein bisschen zu entmystifizieren.

Das Kernstück dieses Tutorials ist das Erstellen der Slack-Benutzeroberfläche. Um sie verwenden und testen zu können, benötigen wir außerdem eine Anwendung. Dafür habe ich mich für eine einfache PHP-Anwendung entschieden, die kein Framework verwendet.

So funktioniert die Beispielanwendung:

Wenn Sie die Anwendung zum ersten Mal ausführen, wird die Schaltfläche "Add to Slack" zum Verbinden der Anwendung mit einem Slack-Kanal angezeigt.
Wenn Sie auf die Schaltfläche klicken, werden Sie durch die OAuth-basierte Authentifizierung von Slack geführt. Wenn die Anwendung ein Zugriffstoken von Slack erhält, wird sie in einer Textdatei gespeichert, damit sie später mit Slack kommunizieren kann.
Wenn die OAuth-basierte Authentifizierung abgeschlossen ist, zeigt die Anwendung ein einfaches Textfeld an, mit dem Sie lustige Benachrichtigungen ("Oh, ich bin ein Roboter!") An Ihren Slack-Kanal gesendet werden können.
Schließlich reagiert die App hinter den Kulissen auf Slash-Befehle, die Sie oder Ihre Teamkollegen in den verknüpften Slack-Kanal eingeben.

This is what our example application will look like

Sie können die Anwendung auf einem PHP-fähigen Server im Web ausführen oder den Anweisungen in diesem Lernprogramm folgen und sie auf Ihrem lokalen Entwicklungscomputer ausführen.

Die Demoanwendung dient nur zu Demonstrationszwecken, sodass Sie am Ende wahrscheinlich die Slack-Schnittstelle verwenden und sie mit Ihrem vorhandenen WordPress-, Laravel- oder anderen PHP-Projekt verbinden. Im Verlauf des Tutorials werde ich Ihnen einige Ideen zeigen, wie Sie die Schnittstellenklasse in einer echten Anwendung anstelle unserer einfachen Demo-App verwenden können.

Schritt 1: Erstellen Sie Ihre PHP-Anwendung

Beginnen wir mit der Erstellung der grundlegenden Projektarchitektur und dem Einfügen aller Dateien.

Wenn Sie den Quellcode von GitHub heruntergeladen haben, können Sie diesen Schritt schnell durchsuchen, um sich zu vergewissern, wie der Code organisiert ist, und dann mit dem nächsten Schritt fortfahren.

Erstellen Sie im Projektverzeichnis die folgende Dateistruktur:

index.php: Die Datei für die oben beschriebene Beispielanwendung.
slack-interface: Ein Verzeichnis, das die Slack-Schnittstelle enthält, die wir in diesem Lernprogramm erstellen. Das Verzeichnis enthält drei Dateien:

slack-interface/class-slack.php: Die Slack-Schnittstellenklasse.
slack-interface/class-slack-access.php: Eine Klasse, in der die Slack-Zugriffsinformationen gespeichert und über die Schnittstelle an die Anwendung übergeben werden.
slack-interface/class-slack-api-exception.php: Eine Ausnahmeklasse für die Übergabe von Fehlern von der Schnittstelle an den Code.

Wenn die Dateien vorhanden sind, fügen wir zu jedem von ihnen einen Inhalt hinzu, sodass wir den Rahmen für die Entwicklung der eigentlichen Funktionalität haben.

Fügen Sie zunächst das HTML-Hauptformular und einen Platzhaltercode für index.php hinzu:

<?php
/**
 * A lightweight example script for demonstrating how to
 * work with the Slack API.
 */
 
// Include our Slack interface classes
require_once 'slack-interface/class-slack.php';
require_once 'slack-interface/class-slack-access.php';
require_once 'slack-interface/class-slack-api-exception.php';

use Slack_Interface\Slack;
use Slack_Interface\Slack_API_Exception;

//
// HELPER FUNCTIONS
//

/**
 * Initializes the Slack object.
 *
 * @return Slack    The Slack interface object
 */
function initialize_slack_interface() {
    return null;
}

/**
 * Executes an application action (e.g. 'send_notification').
 * 
 * @param Slack  $slack     The Slack interface object
 * @param string $action    The id of the action to execute
 *
 * @return string   A result message to show to the user
 */
function do_action( $slack, $action ) {
    $result_message = '';

    switch ( $action ) {
        default:
            break;
    }

    return $result_message;
}

//
// MAIN FUNCTIONALITY
//

// Setup the Slack interface
$slack = initialize_slack_interface();

// If an action was passed, execute it before rendering the page
$result_message = '';
if ( isset( $_REQUEST['action'] ) ) {
    $action = $_REQUEST['action'];
    $result_message = do_action( $slack, $action );
}

//
// PAGE LAYOUT
//

?>
<html>
    <head>
        <title>Slack Integration Example</title>
        
        <style>
            body {
                font-family: Helvetica, sans-serif;
                padding: 20px;
            }
            
            .notification {
                padding: 20px;
                background-color: #fafad2;
            }

            input {
                padding: 10px;
                font-size: 1.2em;
                width: 100%;
            }
        </style>
    </head>
    
    <body>
        <h1>Slack Integration Example</h1>

        <?php if ( $result_message ) : ?>
            <p class="notice">
                <?php echo $result_message; ?>
            </p>
        <?php endif; ?>

        <form action="" method="post">
            <input type="hidden" name="action" value="send_notification"/>
            <p>
                <input type="text" name="text" placeholder="Type your notification here and press enter to send." />
            </p>
        </form>
    </body>
</html>

Werfen wir einen Blick auf den Inhalt des Skripts und was sich an dieser Stelle dort befindet:

In den Zeilen 7-13 schließen wir zuerst die Bibliotheksdateien ein und benachrichtigen dann PHP, dass wir die Klassen Slack und Slack_API_Exception aus dem Slack_Interface-Namespace verwenden werden. Die Dateien und die Klasse existieren noch nicht, aber wir werden sie bald erreichen.
Als nächstes gibt es zwei Platzhalter für Hilfsfunktionen. Die erste Hilfsfunktion, initialize_slack_interface (Zeilen 19-26), richtet die Slack-Klasse für die aktuelle Sitzung ein.
Die zweite Hilfsfunktion, do_action (Zeilen 28-45), wird für andere Aktionen verwendet, außer für das Rendern der Seite, z. B. zum Senden der übermittelten Nachricht in Ihrem Slack-Kanal, aber auch um eingehende Schrägstrichbefehle von Slack zu empfangen.
Nach den Hilfsfunktionen gibt es die "Hauptfunktion" unserer kleinen Anwendung. Zunächst initialisiert die Anwendung das Slack-Objekt (Zeile 52). Dann prüft es in den Zeilen 54-59, ob eine Aktion mit dem Parameter action angefordert wurde. Wenn ja, führt die Anwendung die Aktion mit unserer Hilfsfunktion do_action aus.
Der Rest des Skripts besteht aus grundlegendem HTML-Code (und ein paar CSS-Dateien, die ich in derselben Datei geschrieben habe, um die Dinge einfach zu halten), die das Formular darstellen, das Sie im obigen Bild gesehen haben.

Als Nächstes fügen Sie den Klassendateien, aus denen sich unsere Slack-Oberfläche zusammensetzt, einige Inhalte hinzu.

Fügen Sie in class-slack.php den folgenden Code hinzu:

<?php
namespace Slack_Interface;

/**
 * A basic Slack interface you can use as a starting point
 * for your own Slack projects.
 */
class Slack {

    private static $api_root = 'https://slack.com/api/';

    public function __construct() {
        
    }

}

Die Klasse enthält noch keine Funktionalität mit Ausnahme eines Platzhalterkonstruktors und der Definition der Stamm-URL für die Slack-API. In Zeile 2 werden Sie auch feststellen, dass die Klasse in einem Namespace, Slack_Interface, platziert ist.

Fügen Sie in class-slack-access.php den folgenden Code hinzu:

<?php
namespace Slack_Interface;

/**
 * A class for holding Slack authentication data. 
 */
class Slack_Access {

    public function __construct( $data ) {

    }

}

Fügen Sie schließlich class-slack-api-exception.php den folgenden Inhalt hinzu:

<?php
namespace Slack_Interface;

use Exception;

/**
 * A simple exception class for throwing Slack API errors.
 */
class Slack_API_Exception extends Exception {

}

Jetzt haben wir das Framework für unsere Slack-Anwendung erstellt und können nun einige Funktionen hinzufügen.

Aber zuerst müssen wir die Anwendung im Web verfügbar machen, damit Slack mit ihm sprechen kann.

Schritt 2: Machen Sie Ihren Server im Internet verfügbar

Bevor Sie Ihre Anwendung bei Slack registrieren können und eingehende Anrufe von Slack annehmen können, müssen Sie sie zunächst aus dem Internet zugänglich machen.

Schrägstrichbefehle setzen auch voraus, dass die Anwendung HTTPS verwendet. Wenn Sie sich nicht für Befehle interessieren und möchten, dass Ihre Anwendung Benachrichtigungen senden kann, können Sie diesen Teil überspringen. Für dieses Tutorial benötigen eingehende Schrägstrichbefehle jedoch einen großen Teil unseres Handelns. Daher benötigen wir eine Lösung, die uns HTTPS-Unterstützung bietet.

Wenn auf Ihrem Webserver bereits HTTPS eingerichtet ist, ist dies ein natürlicher Weg.

Eine andere Option in der Entwicklungsphase ist die Verwendung eines Tunneldienstes wie localtunnel. Localtunnel gibt Ihrem Server eine sichere URL im Web, die auf Ihren Webserver verweist, der auf Ihrem lokalen Computer ausgeführt wird. Obwohl dies keine Lösung für Live-Anwendungen ist, vereinfacht dies beim Testen der Funktionalität sowohl den Arbeitsablauf (kein Hochladen von Dateien auf einen Server erforderlich) als auch HTTPS-Unterstützung.

Installieren Sie localtunnel zunächst gemäß den Anweisungen auf der Website des Tools.

Starten Sie dann Ihren Webserver und notieren Sie den Port, den Ihr Server abhört.

Starten Sie localtunnel schließlich im Terminal mit dem folgenden Befehl. Ersetzen Sie your_subdomain durch Ihre bevorzugte Subdomain und your_port durch den Port Ihres Webservers:

1	lt -s your_subdomain -p your_port

Wenn Ihre angeforderte Subdomain verfügbar ist, wird localtunnel gestartet und Sie können über die URL https://your_subdomain.localtunnel.me auf Ihren Server zugreifen.

Schritt 3: Registrieren Sie eine neue Slack-Anwendung

Sobald Ihr Server über das Internet erreichbar ist, müssen Sie eine neue Slack-Anwendung registrieren.

Um eine Slack-Anwendung zu erstellen, melden Sie sich bei Ihrem Slack-Konto an und besuchen Sie die Seite Neue Anwendung. Sie finden den Link zu dieser Seite auch, wenn Sie bei der Anmeldung oben rechts in Ihrem Slack API-Dashboard auf Meine Apps klicken.

You will find the Add New Application link on your My Apps page

Die Seite "Neue Anwendung" sieht folgendermaßen aus:

Geben Sie auf dieser Seite die Informationen zu Ihrer Anwendung ein und klicken Sie auf Anwendung erstellen, um sie zu speichern:

Anwendungsname: Ein Name zur Identifizierung Ihrer Anwendung in der Liste der Anwendungen, aber auch in allen Nachrichten, die Sie an Slack zurücksenden. Ich ging mit "Slack Tutorial".
Team: Das Team, für das die Anwendung verfügbar sein wird. Wenn Ihre Anwendung fertig ist, können Sie sie an das App-Verzeichnis senden. Zu diesem Zeitpunkt wird das Slack-Team es prüfen und, wenn alles gut läuft, Ihre Anwendung für alle verfügbar machen.
Kurzbeschreibung: Eine Beschreibung, die Benutzern angezeigt wird, wenn sie Ihre Anwendung mit ihren Slack-Kanälen verbinden. Wenn Sie nur testen, können Sie dies zunächst leer lassen. Gleiches gilt für das Link zu Installationsanweisungen und das App-Support-Info-Feld.
Symbol: Ein Symbol, das Ihren Benutzern angezeigt wird, wenn sie Ihre Anwendung mit ihren Slack-Kanälen sowie in jeder von Ihrer App bereitgestellten Nachricht verbinden.
Umleitungs-URI (s): Eine URL, zu der Slack die Benutzer umleitet, wenn der Authentifizierungsablauf abgeschlossen ist. In den folgenden Schritten 5 und 6 werden wir uns das genauer ansehen. Setzen Sie das Feld jetzt auf index.php?Action=oauth in Ihrer Anwendung.Beispiel: https://your_subdomain.localtunnel.me/slack-integration/index.php?action=oauth.

Nachdem die Slack-Anwendungsdefinition erstellt wurde, wird sie auf der Seite Meine Apps aufgelistet. Dort können Sie die Informationen der Anwendung bei Bedarf bearbeiten und ihre API-Anmeldeinformationen (aufgelistet in einem Abschnitt mit der Bezeichnung OAuth-Informationen) in Ihre Integration kopieren:

Schritt 4: Speichern Sie die API-Anmeldeinformationen in Ihrer Anwendung

Da Sie die API-Anmeldeinformationen in Ihrer PHP-Anwendung speichern, sollten Sie sich einige Zeit nehmen, um darüber nachzudenken, wie Sie dies so sicher wie möglich machen.

Im Allgemeinen wird es nicht als gute Praxis angesehen, solche sensiblen Informationen der Versionskontrolle zuzuordnen. Stattdessen möchten Sie möglicherweise eine der folgenden Optionen wählen:

Das Speichern der Anmeldeinformationen in Ihrer Datenbank kann eine gute Idee sein, z. B. in einem WordPress-Plugin, bei dem jeder Benutzer über einen eigenen Satz von API-Anmeldeinformationen verfügt, und Sie möchten, dass er seine Anmeldeinformationen direkt über das Admin-Dashboard festlegen kann.
Eine andere Option (etwas sicherer als die erste) besteht darin, die Anmeldeinformationen als Konstanten in einer Konfigurationsdatei direkt auf dem Server zu definieren (wenn Sie mit WordPress arbeiten, wäre wp-config.php natürlich eine natürliche Wahl). Stellen Sie nur sicher, dass die Konfigurationsdatei nicht der Außenwelt ausgesetzt ist (oder der Versionskontrolle verpflichtet ist).
Schließlich können Sie die Client-ID und den geheimen Schlüssel als Umgebungsvariablen auf dem Server festlegen. Auf diese Weise werden die Informationen nicht in einer Datei gespeichert, die versehentlich aus der Anwendung gelangen könnte.

Bei unserer Implementierung verwenden wir eine Kombination der letzten beiden Methoden. Fügen Sie der Slack-Klasse zwei neue Funktionen hinzu, um die Slack-Schnittstelle über die API-Anmeldeinformationen zu informieren:

/**
 * Returns the Slack client ID.
 * 
 * @return string   The client ID or empty string if not configured 
 */
public function get_client_id() {
    // First, check if client ID is defined in a constant
    if ( defined( 'SLACK_CLIENT_ID' ) ) {
        return SLACK_CLIENT_ID;
    }

    // If no constant found, look for environment variable
    if ( getenv( 'SLACK_CLIENT_ID' ) ) {
        return getenv( 'SLACK_CLIENT_ID' );
    }
  	
    // Not configured, return empty string
    return '';
}

/**
 * Returns the Slack client secret.
 * 
 * @return string   The client secret or empty string if not configured
 */
private function get_client_secret() {
    // First, check if client secret is defined in a constant
    if ( defined( 'SLACK_CLIENT_SECRET' ) ) {
        return SLACK_CLIENT_SECRET;
    }

    // If no constant found, look for environment variable
    if ( getenv( 'SLACK_CLIENT_SECRET' ) ) {
        return getenv( 'SLACK_CLIENT_SECRET' );
    }

    // Not configured, return empty string
    return '';
}

Bei den beiden Funktionen handelt es sich fast um exakte Kopien, gehen wir also durch die erste Funktion, get_client_id, um eine Vorstellung davon zu bekommen, was sie tun:

Zuerst prüft die Funktion in den Zeilen 7-10, ob die Client-ID in einer Konstanten mit dem Namen SLACK_CLIENT_ID gespeichert wurde. Wenn diese Konstante definiert ist, gibt die Funktion ihren Wert zurück.
Wenn die Konstante nicht definiert wurde, sucht die Funktion nach einer Umgebungsvariablen mit demselben Namen (Zeilen 12-15).
Wenn keine Client-ID gefunden wurde, gibt die Funktion schließlich eine leere Zeichenfolge zurück.

Um diesen Ansatz zu verwenden, fügen Sie Ihre Zugangsdaten zu Beginn von index.php hinzu, oder noch besser, eine separate PHP-Datei, die Sie in index.php einfügen, aber niemals zur Versionskontrolle verpflichten:

// Define Slack application identifiers
// Even better is to put these in environment variables so you don't risk exposing
// them to the outer world (e.g. by committing to version control)
define( 'SLACK_CLIENT_ID', 'Paste your client ID here' );
define( 'SLACK_CLIENT_SECRET', 'Paste your client secret here' );

Schritt 5: Erstellen Sie eine Datenstruktur zum Speichern von Berechtigungsinformationen

Nun, da wir die Anmeldeinformationen der Anwendung gespeichert haben, ist es an der Zeit, zur nächsten Stufe der Authentifizierung überzugehen: Benutzer können die Anwendung ihren Slack-Konten hinzufügen.

Der Authentifizierungsablauf besteht aus drei Schritten:

Wenn der Benutzer die Anwendung noch nicht zu Slack hinzugefügt hat, wird in der Anwendung die Schaltfläche "Zu Slack hinzufügen" angezeigt.
Nach dem Klicken auf die Schaltfläche wird der Benutzer aufgefordert, die Anwendung zu autorisieren, Benachrichtigungen zu veröffentlichen und auf Befehle in einem Slack-Kanal zu antworten.
Wenn der Benutzer die Anwendung autorisiert, erhält Ihre Anwendung einen temporären Code, den sie dann mithilfe der Slack-API mit einem Satz permanenter Authentifizierungsinformationen austauscht.

Wir werden bald mit der Implementierung des Flusses beginnen, aber zuerst benötigen wir eine Methode zum Speichern und Verwenden der Authentifizierungsinformationen, sobald wir sie von Slack erhalten haben.

Dazu verwenden wir die Klasse Slack_Access, die wir zuvor im Tutorial erstellt haben.

Definieren Sie zuerst in der Klasse Variablen für das Speichern der Berechtigungsdaten:

// Slack OAuth data

private $access_token;
private $scope;
private $team_name;
private $team_id;
private $incoming_webhook;

Implementieren Sie anschließend den Konstruktor, um die Werte für diese Variablen aus einem als Parameter übergebenen Array zu lesen:

/**
 * Sets up the Slack_Access object with authentication data.
 *
 * @param array $data   The Slack OAuth authentication data. If the user
 *                      hasn't been authenticated, pass an empty array.
 */
public function __construct( $data ) {
    $this->access_token = isset( $data['access_token'] ) ? $data['access_token'] : '';
    $this->scope = isset( $data['scope'] ) ? $data['scope'] : array();
    $this->team_name = isset( $data['team_name'] ) ? $data['team_name'] : '';
    $this->team_id = isset( $data['team_id'] ) ? $data['team_id'] : '';
    $this->incoming_webhook = isset( $data['incoming_webhook'] ) ? $data['incoming_webhook'] : array();
}

Der Konstruktor initialisiert die Variablen mit den Werten, die im $data-Array übergeben werden, oder mit leeren Werten, wenn die Informationen nicht im Attributarray vorhanden sind.

Fügen Sie direkt nach dem Konstruktor eine Funktion hinzu, um zu überprüfen, ob das Objekt mit gültigen Daten initialisiert wurde:

/**
 * Checks if the object has been initialized with access data.
 *
 * @return bool True if authentication data has been stored in the object. Otherwise false.
 */
public function is_configured() {
    return $this->access_token != '';
}

Fügen Sie dann zum Speichern der Authentifizierungsdaten die folgende Funktion hinzu:

/**
 * Returns the authorization data as a JSON formatted string.
 *
 * @return string   The data in JSON format
 */
public function to_json() {
    $data = array(
        'access_token' => $this->access_token,
        'scope' => $this->scope,
        'team_name' => $this->team_name,
        'team_id' => $this->team_id,
        'incoming_webhook' => $this->incoming_webhook
    );

    return json_encode( $data );
}

Die Funktion gibt eine JSON-formatierte Zeichenfolge zurück, die die Berechtigungsdaten enthält.

In einer tatsächlichen Anwendung möchten Sie höchstwahrscheinlich die Berechtigungsinformationen an Benutzerkonten binden und die JSON-Daten zusammen mit den Benutzerinformationen speichern. In unserer Beispielanwendung gehen wir jedoch noch einmal von einem einfachen Ansatz aus: Wir gehen davon aus, dass nur ein Benutzer (Sie) die Anwendung verwenden wird, und müssen nur einen Satz von OAuth-Anmeldeinformationen speichern .

Zuerst wollen wir zur Slack-Klasse wechseln und die Funktionalität nutzen, die wir gerade zu Slack_Access hinzugefügt haben.

Implementieren Sie den Konstruktor, um das Zugriffsobjekt für die aktuelle Slack-Instanz einzurichten:

/**
 * @var Slack_Access    Slack authorization data
 */
private $access;

/**
 * Sets up the Slack interface object.
 *
 * @param array $access_data An associative array containing OAuth
 *                           authentication information. If the user
 *                           is not yet authenticated, pass an empty array.
 */
public function __construct( $access_data ) {
    if ( $access_data ) {
        $this->access = new Slack_Access( $access_data );
    }
}

Fügen Sie direkt nach dem Konstruktor eine Funktion hinzu, um zu überprüfen, ob die Berechtigungsdaten im Slack-Objekt festgelegt wurden:

/**
 * Checks if the Slack interface was initialized with authorization data.
 *
 * @return bool True if authentication data is present. Otherwise false.
 */
public function is_authenticated() {
    return isset( $this->access ) && $this->access->is_configured();
}

Schritt 6: Zeigen Sie den Add to Slack-Button

Wenn die Datenstruktur vorhanden ist, können wir die Berechtigungsprüfungen in unserer Hauptanwendung verwenden und die Schaltfläche "Add to Slack" anzeigen.

Beachten Sie, dass die Slack_Access-Klasse selbst in den meisten Anwendungen verwendet werden kann, die in index.php verwendete Lösung jedoch nur zu Demonstrationszwecken ist: Da wir keine Benutzerverwaltung oder Datenbank haben, speichern wir einfach die JSON- formatierte Zugangsdaten von to_json in einer Textdatei.

Zu diesem Zeitpunkt ist die Datei noch nicht vorhanden. Dies bedeutet, dass die Anwendung noch nicht zu einem Slack-Konto hinzugefügt wurde und die Schaltfläche "Zu Slack hinzufügen" anstelle des Textfelds angezeigt werden sollte.

Um das einfache Speichersystem zu implementieren, ersetzen Sie zunächst die Dateien von index.php Funktion initialize_slack_interface mit folgendem:

/**
 * Initializes the Slack handler object, loading the authentication
 * information from a text file. If the text file is not present,
 * the Slack handler is initialized in a non-authenticated state.
 *
 * @return Slack    The Slack interface object
 */
function initialize_slack_interface() {
    // Read the access data from a text file
    if ( file_exists( 'access.txt' ) ) {
        $access_string = file_get_contents( 'access.txt' );
    } else {
        $access_string = '{}';
    }

    // Decode the access data into a parameter array
    $access_data = json_decode( $access_string, true );

    $slack = new Slack( $access_data );
    
    return $slack;
}

In den Zeilen 9-14 liest die Funktion die Berechtigungsdaten als eine Zeichenfolge aus einer Textdatei mit dem Namen access.txt, falls die Datei vorhanden ist. Wenn die Datei nicht vorhanden ist, wird die JSON-Zeichenfolge mit einem leeren Hash initialisiert.

Dann werden die Daten in Zeile 17 in ein Array geparst, um zur Slack-Schnittstelle (in Zeile 19) zu gelangen.

Jetzt können wir alles zusammenstellen und in unserer kleinen Anwendung die Schaltfläche "Zur Slack hinzufügen" anzeigen, wenn keine Berechtigungsdaten gefunden werden.

Ersetzen Sie am Ende von index.php das Formular durch den folgenden Code-Ausschnitt:

<?php if ( $slack->is_authenticated() ) : ?>
    <form action="" method="post">
        <input type="hidden" name="action" value="send_notification"/>
        <p>
            <input type="text" name="text" placeholder="Type your notification here and press enter to send." />
        </p>
    </form>
<?php else : ?>
    <p>
        <a href="https://slack.com/oauth/authorize?scope=incoming-webhook,commands&client_id=<?php echo $slack->get_client_id(); ?>"><img alt="Add to Slack" height="40" width="139" src="https://platform.slack-edge.com/img/add_to_slack.png" srcset="https://platform.slack-edge.com/img/add_to_slack.png 1x, https://platform.slack-edge.com/img/add_to_slack@2x.png 2x"></a>
    </p>
<?php endif; ?>

Im Code-Snippet in Zeile 1 werden Sie feststellen, dass das Formular jetzt von einer is_authenticated-Prüfung umgeben ist, sodass ein Benutzer es nicht sehen kann, bevor er die Anwendung autorisiert.

In den else-Zweigen wird in den Zeilen 8-12 jetzt der Button "Add to Slack" angezeigt.

Werfen wir einen Blick auf das a-Tag der Schaltfläche:

Zunächst zeigt die Schaltfläche den Benutzer in den OAuth-Autorisierungsfluss von Slack (oauth/authorize).
Mit dem scope-Parameter kann die Anwendung die Berechtigungen definieren, die der Benutzer zulassen muss: In unserem Fall benötigen wir eingehende Webhooks (incoming-webhook), um Benachrichtigungen zu veröffentlichen und neue Slash-Befehle (commands) hinzufügen zu können. Eine vollständige Liste der verfügbaren Berechtigungen finden Sie in der API-Dokumentation.
Schließlich muss der Link den öffentlichen Schlüssel der Anwendung (client_id) enthalten, den wir zuvor in diesem Tutorial für unsere Anwendung gespeichert haben.

Der Rest ist nur ein einfaches HTML, um das Bild der Schaltfläche anzuzeigen.

Wenn Sie nun die Anwendung in Ihrem Webbrowser öffnen, sollten Sie Folgendes sehen:

Schritt 7: Schließen Sie die OAuth-Authentifizierung ab

Jetzt ist die Schaltfläche "Hinzufügen zum Spiel" vorhanden. Was passiert aber, wenn der Benutzer darauf klickt?

Zunächst sieht der Benutzer die App-Authentifizierungsseite von Slack, die wie folgt aussieht:

Give the Slack application access to one your Teams channels

Wenn alles für den Benutzer gut aussieht, klickt er oder sie auf die Schaltfläche "Authorize" (Autorisieren), woraufhin die Ausführung an Ihre Anwendung zurückgegeben wird.

Sie erinnern sich, dass wir bei der Definition der Anwendung in Slack eine Rückruf-URL (YOUR_URL/index.php?Action =oauth) festgelegt haben.

Um diesen Rückruf abzuwickeln, verwenden wir das zuvor in diesem Lernprogramm erstellte Aktionssystem. In Ihrer eigentlichen Anwendung müssen Sie die Callback-URLs so implementieren, dass sie für die von Ihnen verwendete Plattform gut geeignet sind. In WordPress können Sie beispielsweise mit Hilfe der Umschreibungs-Engine eine benutzerdefinierte Permalink erstellen.

Die Art des Empfangs des Rückrufs hängt jedoch von der Anwendung ab. Was wir mit den von Slack erhaltenen Daten machen, bleibt jedoch gleich.

Ersetzen Sie die noch leere do_action-Funktion durch Folgendes:

/**
 * Executes an application action (e.g. 'send_notification').
 *
 * @param Slack  $slack     The Slack interface object
 * @param string $action    The id of the action to execute
 *
 * @return string   A result message to show to the user
 */
function do_action( $slack, $action ) {
    $result_message = '';

    switch ( $action ) {

        // Handles the OAuth callback by exchanging the access code to
        // a valid token and saving it in a file
        case 'oauth':
            $code = $_GET['code'];

            // Exchange code to valid access token
            try {
                $access = $slack->do_oauth( $code );
                if ( $access ) {
                    file_put_contents( 'access.txt', $access->to_json() );
                    $result_message = 'The application was successfully added to your Slack channel';
                }
            } catch ( Slack_API_Exception $e ) {
                $result_message = $e->getMessage();
            }
            break;

        default:
            break;

    }

    return $result_message;
}

Wenn der Benutzer aus dem Berechtigungsablauf zurückkehrt, wird diese Funktion mit der $action auf 'oauth' aufgerufen. Zusammen mit der Anfrage erhält die Anwendung ein einmaliges Token, das sie in Zeile 17 liest.

Dann ruft die Funktion in Zeile 21 zum Abschließen der Autorisierung eine Funktion in unserer Slack-Klasse do_oauth auf.

Wie Sie sich vielleicht erinnern werden, haben wir beim Initialisieren der Slack-Oberfläche versucht, die Authentifizierungsdaten aus einer Textdatei zu laden, access.txt. Wenn die Datei nicht gefunden wurde, entschied die Anwendung, dass der Benutzer die Anwendung noch nicht authentifiziert hatte, und zeigte die Schaltfläche "Add to Slack" an.

Nachdem die OAuth-Authentifizierung erfolgreich abgeschlossen wurde, speichert die Funktion in Zeile 23 die Daten in dieser Datei.

Bevor wir jedoch dorthin gelangen, müssen wir die do_oauth-Funktion in der Slack-Klasse implementieren, um den Authentifizierungsablauf abzuschließen.

Diese Funktion ruft die Slack-API auf, um den an die OAuth-Callback-Funktion übergebenen Code mit Authentifizierungsdaten auszutauschen, die dauerhaft gespeichert werden können und für die Kommunikation mit Slack verwendet werden, bis der Benutzer die Autorisierung widerruft.

Dazu benötigen wir eine Möglichkeit, eine HTTP-Anfrage an den Slack-Server zu richten. Es gibt viele Möglichkeiten, HTTP-Anforderungen in PHP zu erstellen. Wenn Sie beispielsweise für WordPress entwickeln, sollten Sie wp_remote_get und wp_remote_post verwenden.

Um diesmal jedoch unabhängig von einem bestimmten Anwendungsentwicklungs-Framework zu bleiben, entschied ich mich für eine freie Bibliothek mit der schönen und sauberen Syntax Requests.

Installieren Sie die Bibliothek gemäß den Anweisungen auf der Website. Im Quellcode des Tuts + GitHub-Repositorys finden Sie die fertige Composer-Konfiguration für die Einbindung der Bibliothek in unsere Anwendung.

Nachdem Sie Requests installiert haben (oder die gewünschte HTTP-Bibliothek ausgewählt haben), fügen Sie der Klasse Slack die Funktion do_oauth hinzu:

/**
 * Completes the OAuth authentication flow by exchanging the received
 * authentication code to actual authentication data.
 *
 * @param string $code  Authentication code sent to the OAuth callback function
 *
 * @return bool|Slack_Access    An access object with the authentication data in place
 *                              if the authentication flow was completed successfully.
 *                              Otherwise false.
 *
 * @throws Slack_API_Exception 
 */
public function do_oauth( $code ) {
    // Set up the request headers
    $headers = array( 'Accept' => 'application/json' );
		
    // Add the application id and secret to authenticate the request
    $options = array( 'auth' => array( $this->get_client_id(), $this->get_client_secret() ) );

    // Add the one-time token to request parameters 
    $data = array( 'code' => $code );

    $response = Requests::post( self::$api_root . 'oauth.access', $headers, $data, $options );
		
    // Handle the JSON response
    $json_response = json_decode( $response->body );

    if ( ! $json_response->ok ) {
        // There was an error in the request
        throw new Slack_API_Exception( $json_response->error );
    }

    // The action was completed successfully, store and return access data
    $this->access = new Slack_Access(
        array(
            'access_token' => $json_response->access_token,
            'scope' => explode( ',', $json_response->scope ),
            'team_name' => $json_response->team_name,
            'team_id' => $json_response->team_id,
            'incoming_webhook' => $json_response->incoming_webhook
        )
    );

    return $this->access;
}

Gehen wir die Funktion Zeile für Zeile durch:

In den Zeilen 14-18 initialisiert die Funktion die Parameter für die HTTP-Anforderung. Erwähnenswert ist, dass die Client-ID und das Secret als Anforderungsoptionen für den grundlegenden Authentifizierungsmechanismus von HTTP übergeben werden.

In Zeile 21 werden Sie feststellen, dass wir das in der Rückruffunktion empfangene einmalige Token an die Slack-API zurücksenden, um die Anforderung zu identifizieren.

Die POST-Anforderung wird in Zeile 23 gesendet. Dann fährt die Funktion fort, indem sie die Antwort parst und entweder die Berechtigungsdaten (Zeilen 33-44) erstellt und zurückgibt, wenn alles gut gegangen ist, oder eine Ausnahme ausgelöst (Zeilen 28-31), wenn bei der Anforderung ein Fehler aufgetreten ist.

Nun ist der Fluss "Add to Slack" fertig. Wenn Sie es versuchen, sollten Sie Folgendes sehen:

The authentication flow was completed successfully

Wenn Sie in Ihr Projektverzeichnis schauen, sollten Sie auch eine Textdatei namens access.txt finden, in der die Authentifizierungsdaten gespeichert sind.

Jetzt sind wir bereit für den spaßigen Teil: Die Anwendung wird in Ihrem Slack-Kanal veröffentlicht.

2. Senden Sie eine Benachrichtigung an einen Slack-Kanal

Das Senden von Benachrichtigungen an einen Slack-Kanal ist eine leistungsstarke Methode, um ein Team über Ereignisse auf dem Laufenden zu halten, die für sie wichtig sind. Ein Webshop sendet möglicherweise Benachrichtigungen über neue Einkäufe, eine Fehlerverfolgungssoftware kann Entwickler automatisch benachrichtigen, und die Liste wird fortgesetzt.

Wie Sie bereits in der Benutzeroberfläche gesehen haben, senden wir in unserem Beispiel alle Benachrichtigungen, die der Benutzer über das Textfeld sendet.

Die Funktionalität für das Senden anderer Benachrichtigungen ist jedoch dieselbe. Sobald sie fertig ist, können Sie denselben Code zum Senden Ihrer eigenen, komplexeren Benachrichtigungen verwenden.

Schritt 1: Erstellen Sie eine Funktion zum Senden einer Benachrichtigung

Fügen Sie in der Slack-Klasse die folgende Funktion hinzu:

/**
 * Sends a notification to the Slack channel defined in the
 * authorization (Add to Slack) flow.
 *
 * @param string $text          The message to post to Slack
 * @param array $attachments    Optional list of attachments to send 
 *                              with the notification
 *
 * @throws Slack_API_Exception
 */
public function send_notification( $text, $attachments = array() ) {
    if ( ! $this->is_authenticated() ) {
        throw new Slack_API_Exception( 'Access token not specified' );
    }

    // Post to webhook stored in access object
    $headers = array( 'Accept' => 'application/json' );

    $url = $this->access->get_incoming_webhook();
    $data = json_encode(
        array(
            'text' => $text,
            'attachments' => $attachments,
            'channel' => $this->access->get_incoming_webhook_channel(),
        )
    );

    $response = Requests::post( $url, $headers, $data );
		
    if ( $response->body != 'ok' ) {
        throw new Slack_API_Exception( 'There was an error when posting to Slack' );
    }
}

Das Senden einer Benachrichtigung an einen Slack-Kanal erfolgt mithilfe eines Webhooks, einer autorisierungsspezifischen URL, die Slack der Anwendung für das Posten an einen Kanal zur Verfügung stellt.

Wir haben dem Abschnitt "Add to Slack" zuvor nicht viel Aufmerksamkeit geschenkt, aber wenn Sie sich die Daten in Slack_Access noch einmal ansehen, werden Sie feststellen, dass Slack ein Feld namens incoming_webhook zurückgibt. Bei diesem Feld handelt es sich um ein Array mit zwei Feldern: Die URL, an die wir unsere Benachrichtigungen senden sollen, und der Kanal, den der Benutzer für die Nachrichten der Anwendung ausgewählt hat.

Um auf diese Daten zuzugreifen, fügen Sie der Klasse Slack_Access die folgenden zwei Funktionen hinzu:

/**
 * Returns the webhook URL for posting notifications.
 * 
 * @return string   The incoming webhook URL
 */
public function get_incoming_webhook() {
    if ( is_array( $this->incoming_webhook ) && isset( $this->incoming_webhook['url'] ) ) {
        return $this->incoming_webhook['url'];
    }

    return '';
}

/**
 * Returns the channel to which the user has authorized the application
 * to post notifications.
 * 
 * @return string   The selected Slack channel's ID
 */
public function get_incoming_webhook_channel() {
    if ( is_array( $this->incoming_webhook ) && isset( $this->incoming_webhook['channel'] ) ) {
        return $this->incoming_webhook['channel'];
    }

    return '';
}

Gehen wir nun zurück zur send_notification-Funktion und sehen wir uns an, wie diese Funktionen zum Senden der Benachrichtigung verwendet werden.

In Zeile 19 werden Sie feststellen, dass die HTTP-Anforderung an die eingehende Webhook-URL gesendet wird, die in den Berechtigungsdaten gespeichert ist.

Später wird in Zeile 24 der Kanal in den Anforderungsparametern zusammen mit dem Text und allen Anhängen übergeben, die wir veröffentlichen möchten.

Schritt 2: Verwenden Sie die Benachrichtigungssendefunktion in der Beispielanwendung

Nachdem wir nun die Funktion zum Senden von Benachrichtigungen implementiert haben, fügen wir die Funktionalität unserer Benutzeroberfläche hinzu und testen sie.

Fügen Sie der do_action-Funktion in index.php den folgenden neuen case-Zweig hinzu:

// Sends a notification to a Slack channel
case 'send_notification':
    $message = isset( $_REQUEST['text'] ) ? $_REQUEST['text'] : 'Hello!';

    try {
        $slack->send_notification( $message );
        $result_message = 'Notification sent to Slack channel.';	
    } catch ( Slack_API_Exception $e ) {
        $result_message = $e->getMessage();
    }
    break;

Dieses Code-Snippet liest die Nachricht aus den Anforderungsparametern (Zeile 3) und verwendet die soeben erstellte Funktion send_notification, um sie an Slack (Zeile 6) zu senden.

Da das Formular bereits zu Beginn des Tutorials erstellt wurde, können Sie jetzt Ihre erste Nachricht an Ihren Slack-Kanal senden. Geben Sie etwas in das Textfeld ein und drücken Sie die Eingabetaste, um das Formular zu senden.

Dann schauen Sie sich Ihren Slack-Kanal an, um Ihre Nachricht zu sehen:

Schritt 3: Verwenden Sie Anhänge, um Ihre Benachrichtigungen informativer zu gestalten

In der send_notification-Funktion haben Sie wahrscheinlich einen Parameter namens Anhänge bemerkt. Ich habe es noch nicht erwähnt, da es nicht so gut zu der Beispielanwendung passt. Anhänge sind jedoch eine leistungsfähige Methode, um weitere interessante Informationen zu den Ereignissen Ihrer Anwendung an den Slack-Kanal zu übergeben, und Sie möchten sie wahrscheinlich in Ihren Anwendungen verwenden.

Lassen Sie uns also ein wenig mit Anhängen experimentieren, indem Sie den send_notification-Aufruf aus Schritt 2 ein wenig ändern. Ersetzen Sie den Aufruf $slack->send_notification() durch den folgenden Code:

$attachments = array(
    array(
        'fallback' => 'Jarkko just posted a new bread recipe.',

        'title' => 'Sprouted Wheat Bread',
        'title_link' => 'https://bread-magazine.com/sprouted-wheat-flour/',

        'text' => 'Jarkko just posted a new bread recipe. Check it out.',

        'color' => '#7CD197',

        'fields' => array(
            array(
                'title' => 'Preparation time',
                'value' => ':hourglass: 24 hours',
                'short' => true
            ),
            array(
                'title' => 'Difficulty',
                'value' => 'Medium',
                'short' => true
            ),
        ),
        'image_url' => 'https://s3.amazonaws.com/interested/wordpress/wp-content/uploads/2015/02/12093547/sprouted-bread.jpg'
    )
);

$slack->send_notification( $message, $attachments );

Der im obigen Code angegebene Anhang ist eine imaginäre Benachrichtigung über das Hinzufügen eines neuen Brotrezeptes in einer Rezeptdatenbank. Dies ist nur ein Beispiel. Nehmen Sie also eine Änderung vor, um zu sehen, wie sich Änderungen daran auf die Ausgabe im Slack-Kanal auswirken.

fallback: Eine erforderliche Nur-Text-Nachricht, die angezeigt wird, wenn der Anhang nicht angezeigt werden kann.
title: Ein Titel für den Anhang, der mit einer größeren Schrift formatiert ist.
title_link: Eine URL, die geöffnet wird, wenn der Benutzer auf den Link klickt. In unserem Beispiel würde dies das Rezept zeigen.
text: Text, der in der Anlage angezeigt wird.
color: Die Farbe der Linie auf der linken Seite des Anhangs.
fields: Eine Liste von Datenfeldern, die in den Anhängen angezeigt werden sollen. Im Beispiel werden sie zum Anzeigen einiger Informationen zum Rezept verwendet.
image_url: Eine URL zu einem Bild, die im Anhang angezeigt werden soll.

Folgendes wird angezeigt, wenn Sie die Benachrichtigung mit dem oben angegebenen Anhang posten:

Spielen Sie mit den Parametern und sehen Sie, wie sich deren Änderung auf die Nachrichten auswirkt, die in Ihrem Slack-Kanal gepostet werden: Ändern Sie die Attribute, senden Sie eine neue Benachrichtigung und sehen Sie sich die Änderungen an.

Weitere Informationen zu den Anhängen finden Sie in der Slack-Dokumentation.

3. Lassen Sie Ihre Anwendung auf Schrägstrichbefehle reagieren

Ihre Anwendung kann jetzt mit Slack sprechen. Als Nächstes machen wir die Kommunikation auch andersherum: Durch Hinzufügen von Schrägstrichbefehlen können wir Slack als Schnittstelle zu unserer Anwendung verwenden.

In einer realen Anwendung hat dies viele Anwendungsfälle. Einen Fehler als behoben markieren, eine Bestellung als ausgeliefert markieren oder nach einem Witz fragen, das sind nur einige, die mir einfallen.

Machen wir weiter und implementieren die Witzanfrage, um einen Witz zu posten, wenn jemand /joke in den Slack-Kanal eingibt.

Schritt 1: Definieren Sie einen Schrägstrichbefehl

Besuchen Sie zunächst die Einstellungsseite Ihrer Slack-Anwendung, um den neuen Schrägstrichbefehl zu definieren.

Scrollen Sie nach unten zu dem Abschnitt mit dem Titel Slash-Befehle und klicken Sie auf Neuen Befehl erstellen.

Geben Sie im nächsten Bildschirm die erforderlichen Informationen zum Angeben des neuen Befehls ein und klicken Sie auf Speichern.

Hier sind kurze Beschreibungen der Felder auf dieser Seite:

Befehl: Der Schrägstrichbefehl, einschließlich des Schrägstrichs. Zum Beispiel /joke.
Anforderungs-URL: Die URL auf Ihrem Server, die aufgerufen werden soll, wenn jemand diesen Schrägstrichbefehl in einem Slack-Kanal eingibt. Hier ist localtunnel von Nutzen: Die URL muss HTTPS sein und für die Verbindung aus dem Internet verfügbar sein. Verwenden Sie das folgende URL-Format, um die Anforderungs-URL mit der Funktionalität, die wir in Schritt 2 erstellen, kompatibel zu machen:YOUR_SERVER/index.php?Action=command.
Kurzbeschreibung: Eine Beschreibung, die im Autocomplete-Popup angezeigt wird, wenn jemand den Befehl eingibt.
Verwendungshinweis: Wenn der Befehl Parameter verwendet, können Sie diese hier beschreiben. Dieser Text ist auch im Autovervollständigungsdialog sichtbar.

Nach dem Speichern des Befehls finden Sie Ihren neuen Befehl im Abschnitt Slash-Befehle. Sie können die Schaltflächen zum Bearbeiten oder Löschen verwenden.

Slash Commands now include the joke command

Unter der Befehlsliste befindet sich eine Zeichenfolge mit der Bezeichnung Bestätigungs-Token.

Sie können dieses Token verwenden, um zu überprüfen, ob die Befehle tatsächlich von Slack stammen, bevor Sie sie ausführen. Speichern Sie das Token in Ihrer Anwendung auf dieselbe Weise, wie Sie es zuvor für die Client-ID und das Secret-Programm getan haben. Fügen Sie beispielsweise eine Konstante am Anfang von index.php hinzu:

1	define( 'SLACK_COMMAND_TOKEN', 'Paste your command verification token here' );

Schritt 2: Erstellen Sie ein System zum Nachverfolgen von Schrägstrichbefehlen in Ihrer Anwendung

Jetzt erkennt Slack den Befehl, wenn jemand ihn in das Slack-Chat-Fenster eingibt (Sie können jetzt versuchen, das Popup für die automatische Vervollständigung anzuzeigen).

Wenn der Benutzer den Befehl übergibt, ruft Slack unseren Server unter der im vorherigen Schritt angegebenen Anforderungs-URL an. Jetzt müssen wir die Funktionalität implementieren, damit unsere Anwendung korrekt darauf reagiert.

Da Sie Ihrer Slack-Anwendung mehr als einen Slash-Befehl hinzufügen können, ist es ratsam, eine variable Anzahl von Slash-Befehlen zu unterstützen. Aus diesem Grund erstellen wir zunächst ein System, um Slash-Befehle in der Anwendung zu verfolgen.

Fügen Sie in der Slack-Klasse zunächst die folgende Variable hinzu, um die Befehle aufzunehmen:

/**
 * @var array $slash_commands   An associative array of slash commands 
 *                              attached to this Slack interface
 */
private $slash_commands;

Fügen Sie im Konstruktor der Klasse eine Zeile hinzu, um das Array zu initialisieren:

1	$this->slash_commands = array();

Erstellen Sie dann eine Funktion zum Hinzufügen eines neuen Schrägstrichbefehls zum Array:

/**
 * Registers a new slash command to be available through this
 * Slack interface.
 *
 * @param string    $command    The slash command
 * @param callback  $callback   The function to call to execute the command
 */
public function register_slash_command( $command, $callback ) {
    $this->slash_commands[$command] = $callback;
}

Da Sie nun eine Liste von Schrägstrichbefehlen haben, fügen Sie eine Funktion zum Ausführen eines Befehls hinzu:

/**
 * Runs a slash command passed in the $_POST data if the
 * command is valid and has been registered using register_slash_command.
 *
 * The response written by the function will be read by Slack.
 */
public function do_slash_command() {
    // Collect request parameters
    $token      = isset( $_POST['token'] ) ? $_POST['token'] : '';
    $command    = isset( $_POST['command'] ) ? $_POST['command'] : '';
    $text       = isset( $_POST['text'] ) ? $_POST['text'] : '';
    $user_name  = isset( $_POST['user_name'] ) ? $_POST['user_name'] : '';

    // Use the command verification token to verify the request
    if ( ! empty( $token ) && $this->get_command_token() == $_POST['token'] ) {
        header( 'Content-Type: application/json' );

        if ( isset( $this->slash_commands[$command] ) ) {
            // This slash command exists, call the callback function to handle the command
            $response = call_user_func( $this->slash_commands[$command], $text, $user_name );
            echo json_encode( $response );
        } else {
            // Unknown slash command
            echo json_encode( array(
                'text' => "Sorry, I don't know how to respond to the command."
            ) );
        }
    } else {
        echo json_encode( array(
            'text' => 'Oops... Something went wrong.'
        ) );
    }

    // Don't print anything after the response
    exit;
}

Gehen wir die Funktion durch, um zu sehen, was sie bewirkt:

Zunächst sammelt die Funktion in den Zeilen 8-12 Daten aus den Anforderungsparametern:

token wird verwendet, um zu überprüfen, ob es sich bei der Anforderung um eine gültige Slack-Befehlsanforderung handelt.
command enthält den Slash-Befehl, der ausgeführt werden soll.
text ist die Zeichenfolge, die nach dem Befehl eingegeben wurde. Es kann verwendet werden, um Parameter an Ihren Schrägstrichbefehl zu übergeben.
user_name ist der Benutzername des Benutzers, der den Schrägstrichbefehl gesendet hat.

In Zeile 15 führt die Funktion die Überprüfung durch, indem sie das in den Anforderungsparametern übergebene Token mit dem im vorherigen Schritt gespeicherten Token vergleicht.

Wenn das Token gültig ist, führt die Funktion den Befehl weiter aus, wenn einer mit dem angegebenen Befehlsnamen in der Slack-Klasse registriert wurde. Die Ausführung des Befehls erfolgt in Zeile 20, wo die Funktion die für den Befehl angegebene Callback-Funktion aufruft.

Dann wird in Zeile 21 die Antwort in eine JSON-Zeichenfolge codiert und ausgedruckt. Beachten Sie, dass die Funktion mit einem exit-Aufruf endet, um sicherzustellen, dass nach der Antwort nichts mehr gedruckt wird.

Um die Funktionalität abzuschließen, fügen Sie die Funktion get_command_token hinzu, um das Befehlsüberprüfungstoken für die Anwendung abzurufen:

/**
 * Returns the command verification token.
 *
 * @return string   The command verification token or empty string if not configured
 */
private function get_command_token() {
    // First, check if command token is defined in a constant
    if ( defined( 'SLACK_COMMAND_TOKEN' ) ) {
        return SLACK_COMMAND_TOKEN;
    }

    // If no constant found, look for environment variable
    if ( getenv( 'SLACK_COMMAND_TOKEN' ) ) {
        return getenv( 'SLACK_COMMAND_TOKEN' );
    }

    // Not configured, return empty string
    return '';
}

Die Slash-Befehlsfunktionalität in der Slack-Klasse ist nun abgeschlossen. Bevor wir unseren ersten Befehl implementieren können, müssen Sie nur noch die Callback-URL mit diesem Code verbinden.

Fügen Sie dazu einen neuen case-Zweig in der do_action-Funktion in index.php hinzu:

// Responds to a Slack slash command. Notice that commands are 
// registered at Slack initialization.
case 'command':
    $slack->do_slash_command();
    break;

Schritt 3: Registrieren und testen Sie den Schrägstrichbefehl

Nachdem wir nun ein System für die Behandlung von Schrägstrichbefehlen in unserer Anwendung erstellt haben, verwenden wir es, um die Funktionalität für den Befehl /joke zu implementieren.

Fügen Sie am Ende der Funktion initialize_slack_interface die folgenden Codezeilen hinzu, um den Befehl zu registrieren, und übergeben Sie den Namen der Funktion, die den Befehl verarbeiten soll:

1	// Register slash commands
2	$slack->register_slash_command( '/joke', 'slack_command_joke' );

Dann erstellen Sie die Funktion:

/**
 * A simple slash command that returns a random joke to the Slack channel.
 *
 * @return array    A data array to return to Slack
 */
function slack_command_joke() {
    $jokes = array(
        "The box said 'Requires Windows Vista or better.' So I installed LINUX.",
        "Bugs come in through open Windows.",
        "Unix is user friendly. It’s just selective about who its friends are.",
        "Computers are like air conditioners: they stop working when you open Windows.",
        "I would love to change the world, but they won’t give me the source code.",
        "Programming today is a race between software engineers striving to build bigger and better idiot-proof programs, and the Universe trying to produce bigger and better idiots. So far, the Universe is winning."
    );

    $joke_number = rand( 0, count( $jokes ) - 1 );

    return array(
        'response_type' => 'in_channel',
        'text' => $jokes[$joke_number],
    );
}

Da diese Funktion nur als Demo erstellt wurde, macht sie nicht viel: Sie wählt einen der (eher schlechten) Witze aus und gibt sie in einem von Slack erwarteten Format zurück.

Beachten Sie, dass diese Befehlsfunktion zwar keine Parameter erfordert, Sie jedoch für ein komplexeres Beispiel zwei Parameter hinzufügen können: $text für den Zugriff auf alle Daten, die der Benutzer nach dem Befehl eingegeben hat, und $user_name, um den Namen des Benutzers mit who zu erhalten hat den Befehl übermittelt.

Um den Befehl zu testen, fahren Sie fort und geben Sie /joke in den Slack-Kanal ein.

Fazit und Ideen für die Zukunft

Sie haben nun das Tutorial abgeschlossen und wissen, wie Sie Ihre PHP-Anwendung in Slack integrieren. Während des Lernprogramms haben Sie auch Tools entwickelt, mit denen Sie Benachrichtigungen an einen Slack-Kanal senden und auf Befehle reagieren können, die Ihre Benutzer direkt in Slack eingeben.

Der nächste Schritt ist die Umsetzung dieser Ideen.

Denken Sie über Ihre Anwendung nach und suchen Sie nach Orten, an denen der Umgang mit Slack und das Hören auf Befehle von Slack die Erfahrung für Ihre Benutzer nützlicher und angenehmer machen und implementieren können.

Die Plattform entwickelt sich schnell, ebenso die API. Behalte den Überblick, wohin es geht, und baue etwas Erstaunliches!