Cómo crear una interfaz Slack para tu aplicación PHP

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

Si has estado siguiendo el desarrollo de herramientas de comunicación de la oficina en los últimos años, estoy seguro que has oído hablar bastante sobre Slack. En el nivel superficial, Slack es sólo otra aplicación de chat diseñada para las empresas, pero debido a su atención al detalle y su extensibilidad, muchos comentaristas están diciendo que la herramienta cambiará dramáticamente cómo trabajaremos en el futuro.

Como desarrolladores, nos encontramos en una buena posición para saltar en la tendencia y pensar en que manera podemos utilizar Slack como una interfaz de usuario basada en chat para nuestras aplicaciones.

Es por eso, en este tutorial, aprenderás cómo comenzar a integrar tu aplicación PHP para Slack, enviando mensajes a un canal de Slack y responder a los comandos slash.

Puedes descargar el código fuente para el tutorial desde el repositorio de GitHub, o crearlo tu mismo mientras avanzas en el tutorial.

Código del tutorial consta de dos partes:

una escueta pero completa interfaz para comunicarse con Slack
un simple script de ejemplo que utiliza la clase de Slack para enviar notificaciones y responder a un comando de slash

Vamos a empezar.

1. Crear tu aplicación y conectarla a Slack

Una rápida búsqueda en Google para el término "Slack PHP" nos da varias interfaces Slack diferentes creados por otros desarrolladores, Así que podrías comenzar con un proyecto existente y engancharlo a tu aplicación.

Pero la API no es complicada en lo absoluto, por lo que no hay razón para no tener algo de diversión y enfoque del proyecto de inicio a fin. De esta manera, sabrás lo que está en la API (y su integración). Siempre es bueno desmitificar un poco las cosas.

El núcleo de este tutorial es la construcción de una interfaz de Slack, pero para utilizarla y probarla, también necesitaremos una aplicación. Para ello, decidí ir con una simple aplicación de PHP que no utiliza ningún framework.

Aquí es cómo funciona la aplicación de ejemplo:

La primera vez que ejecutas la aplicación, verás un botón de "Añadir a Slack" para conectar la aplicación a un canal de Slack.
Clic en el botón te guiará a través de la autenticación basada en Slack OAuth. Cuando la aplicación recibe un token de acceso de Slack, lo guardará en un archivo de texto para que posteriormente puede utilizarlo para comunicarse con Slack.
Cuando la autenticación basada en OAuth es completada, la aplicación mostrará un simple campo de texto que puede utilizarse para enviar simpáticas notificaciones ("Oh sí, soy un robot!") a tu canal de Slack.
Por último, detrás de escenas, la aplicación responderá a comandos slash que tu o tus compañeros de equipo escriban en el canal vinculado a Slack.

This is what our example application will look like

Puedes ejecutar la aplicación en un servidor habilitado con PHP en la web, o sigue las instrucciones de este tutorial para ejecutarlo en tu máquina de desarrollo personal.

El demo de la aplicación es solo para fines demostrativos, por lo que al final, probablemente tomarás la interfaz de Slack y la conectarás a tu WordPress, Laravel u otro proyecto PHP existente. A lo largo del tutorial, voy a compartir algunas ideas acerca de cómo puedes utilizar la clase de interfaz en una aplicación real en lugar de nuestra simple aplicación demo.

Paso 1: Crea tu aplicación PHP

En primer lugar, vamos a comenzar creando la arquitectura básica del proyecto y poner todos los ficheros en su lugar.

Si has descargado el código fuente de GitHub, puedes observar rápidamente estos pasos para estar seguro que entiendes como está organizado el código y despues puedes moverte al proximo paso.

Dentro del directorio del proyecto, crea la estructura de archivos siguiente:

index.php: El archivo de la aplicación de ejemplo descrito anteriormente.
slack-interface: Un directorio que contendrá la interfaz de Slack que voy a ir creando en este tutorial. El directorio tendra tres archivos:

slack-interface/class-slack.php: La clase interfaz de Slack.
slack-interface/class-slack-access.php Una clase para mantener la información de acceso de Slacky pasarla a la aplicación mediante la interfaz.
slack-interface/class-slack-api-exception.php Una clase de excepción para pasar errores desde la interfaz al código usado.

Luego, con los archivos en su lugar, vamos a añadir contenidos a cada uno de ellos por lo que contamos con el framework para el desarrollo de la funcionalidad actual.

Comienza agregando el formulario principal en HTML enel archivo index.php:

<?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>

Echemos un vistazo al contenido del script y lo que hay en él en este momento:

En las líneas 7-13, primero se incluyen los archivos de librería y luego se notifica a PHP que vamos a utilizar las clases Slack y Slack_API_Exception del namespace (nombre reservado) Slack_Interface La clase y los archivos no existen todavía, pero vamos a llegar pronto a ellos.
A continuación, hay dos placeholders (marcadores) para funciones auxiliares. La primera función de ayuda, initialize_slack_interface (líneas 19-26), establecerá la clase Slack para la sesión actual.
La segunda función auxiliar, do_action (líneas 28-45) se utilizará para manejar otras acciones menos procesar la página, por ejemplo, publicar el mensaje enviado a su canal de Slack, pero también recibe entrada de comandos slash de Slack.
Después de las funciones de ayuda, está la "principal" funcionalidad de nuestra pequeña aplicación. En primer lugar, la aplicación inicializa el objeto Slack (línea 52). Luego, en las líneas 54-59, comprueba si se ha solicitado una acción mediante el parámetro action (acción). Si es así, la aplicación ejecuta la acción utilizando nuestra función de ayuda do_action.
El resto del script es HTML básico (y algunos CSS, que escribí en el mismo archivo para mantener las cosas simples) esto muestra el formulario que ves en la imagen de arriba.

A continuación, añade algunos contenidos en los archivos de la clase que conformarán nuestra interfaz de Slack.

En class-slack.php, agrega el código siguiente:

<?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() {
        
    }

}

La clase no contiene ninguna funcionalidad aun, excepto en el constructor y la definición de la URL raíz de la API de Slack. En la línea 2, también notarás que la clase se coloca en un namespace (espacio de nombre), Slack_Interface.

Del mismo modo, en class-slack-access.php, agregue el código siguiente:

<?php
namespace Slack_Interface;

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

    public function __construct( $data ) {

    }

}

Por último, agregue el siguiente contenido a class-slack-api-exception.php:

<?php
namespace Slack_Interface;

use Exception;

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

}

Ahora, hemos creado el framework para nuestra aplicación de Slack y estamos listos para comenzar a añadir funcionalidad.

Pero primero, necesitamos poner la aplicación disponible en la web para que Slack puede comunicarse con ella.

Paso 2: Haz que tu servidor est disponible en Internet

Antes de poder registrar tu aplicación con Slack y hacer que reciba llamadas de Slack, primero necesitas que esté accesible en internet.

Los comandos de slash también requieren que la aplicación está utilizando HTTPS. Si no te preocupan los comandos y simplemente deseas que tu aplicación pueda enviar notificaciones, puedes omitir esta parte. Para este tutorial, sin embargo, como recibirá comandos de slash es una gran parte de lo que queremos hacer, necesitamos una solución que nos de soporte HTTPS.

Si su servidor web ya tiene configurado HTTPS, es una forma natural de proceder.

Otra opción, en la fase de desarrollo, es utilizar un servicio de túnel como localtunnel. Localtunnel da a tu servidor una dirección URL segura en la web que puede ser apuntada a tu servidor web, ejecutado en tu máquina local. Mientras que no es una solución para aplicaciones de en vivo, cuando se prueba la funcionalidad, simplifican tu flujo de trabajo (sin necesidad de subir archivos a un servidor) y le da soporte HTTPS.

Para empezar, instala localtunnel según las instrucciones en la Página Web.

Luego, inicia tu servidor web, observa los puertos que están escuchando en tu servidor.

Y por último, una vez que el servidor esté corriendo, inicia localtunnel desde terminal de comandos usando el siguiente comando. Reemplaza your_subdomain con tu subdominio y your_port con el puerto del servidor web que prefieras:

1	lt -s your_subdomain -p your_port

Si tu subdominio solicitado está disponible, localtunnel inicia, y puedes acceder a tu servidor a través de la direccin https://your_subdomain.localtunnel.me.

Paso 3: Registrar una nueva aplicación Slack

Una vez que el servidor pueda ser accedido desde internet, es tiempo de registrar una nueva aplicacion Slack.

Para crear una aplicación Slack, inicia sesión con tu cuenta de Slack y visite la página de New Application (nueva aplicación). También puedes encontrar el enlace a esta página haciendo clic en My Apps (mis aplicaciones) en la esquina superior derecha de tu consola Slack API.

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

La página de la nueva aplicación se ve así:

En esta página, especifique la información sobre tu aplicación y haga clic en crear aplicación para guardarlo:

Nombre de aplicación: Un nombre para identificar tu aplicación en la lista de aplicaciones, pero también en cualquier mensaje envíes a Slack. Yo escogí "Slack Tutotorial".
Equipo: El equipo para que la aplicación estará disponible. Cuando tu aplicación esté lista, puedes enviarla al directorio de la aplicación. En ese momento, el equipo de Slack revisará y, si todo sale bien, hará tu aplicación disponible a todo el mundo.
Breve descripción: Una descripción que se mostrará a los usuarios cuando ellos estén conectando tu aplicación a sus canales de Slack. Si solo estás probando, puedes dejar esto vacío por ahora. Lo mismo pasa con el enlace a las instrucciones de instalación y campo de información de la aplicación.
Icono: Un ícono que se mostrará a los usuarios cuando vayan a conectar tu aplicación a sus canales de Slack, así como cada mensaje publicado por tu aplicación.
Redirect URI(s): Una dirección URL que Slack redirigirá a los usuarios cuando hayan completado la autenticación. Veremos esto en más detalle en los pasos 5 y 6, pero ahora, sólo tienes que configurar el campo para que apunte a index.php?action=oauth en tu aplicación, por ejemplo, https://your_subdomain.localtunnel.me/slack-integration/index.php?action=oauth.

Cuando se ha creado la definición de aplicación Slack, verás que aparece en la página de My Apps. Allí, puedes editar la información de la aplicación si es necesario y copiar sus credenciales de la API (listadas en una sección denominada información de OAuth) para su integración:

Paso 4: Almacenar las credenciales de la API en tu aplicación

A continuación, como almacenarás las credenciales de la API en tu aplicación PHP, es bueno tomar algún tiempo para pensar acerca de cómo hacerlo lo mas seguro posible.

En general, no se considera como una buena práctica para cometer tal información sensible al control de versiones. En cambio, puedes ir con una de las siguientes opciones:

Almacenar las credenciales en una base de datos puede ser una buena idea, por ejemplo, en un plugin para WordPress donde cada usuario tendrá su propias credenciales de la API y que deseas que sea capaz de establecer sus credenciales directamente en el panel de Admin.
Otra opción (Un poco más segura que la anterior) es definir las credenciales como constantes en un archivo de configuración directamente en el servidor (de nuevo, si trabajas con WordPress, wp-config.php sería una elección natural). Sólo asegúrate de que el archivo de configuración no está expuesto al mundo exterior (o comprometidos con control de versiones).
Por último, puede establecer el identificador de cliente y el secreto como variables de entorno en el servidor. Esta manera, la información no es almacenada en un archivo que puede ser filtrado accidentalmente fuera de la aplicación.

En nuestra implementación, lo haremos con una combinación de los dos últimos métodos. Para hacer que la interfaz de Slack conozca sobre las credenciales de la API, agrega dos nuevas funciones a la clase Slack:

/**
 * 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 '';
}

Las dos funciones son copias casi exactas de cada una, así que vamos a ir a través de la primera, get_client_id, para tener una idea de lo que hacen:

En primer lugar, en las líneas 7-10, la función comprueba si el ID del cliente se ha almacenado en una constante llamada SLACK_CLIENT_ID. Si se define esta constante, la función devuelve su valor.
Si la constante no ha sido definida, la función continúa comprobando si existe una variable de entorno con el mismo nombre (líneas 12-15).
Por último, si no se ha encontrado ningún ID de cliente, la función devuelve una cadena vacía.

Para utilizar esto, agrega tus credenciales de acceso al inicio del index.php, o mejor aún, un archivo PHP aparte que incluirás en index.php pero excluyelo de tu control de versiones:

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

Paso 5: Crear una estructura de datos para almacenar información de autorización

Ahora que hemos guardado las credenciales de la aplicación, es tiempo de pasar al siguiente nivel de autenticación: permitiendo a los usuarios a agregar la aplicación a sus cuentas de Slack.

El flujo de autenticación consta de tres pasos:

Si el usuario aún no ha agregado la aplicación a Slack, un boton "Add to Slack" se mostrará en la aplicación.
Después de hacer clic en el botón, el usuario deberá autorizar a la aplicación para publicar notificaciones y responder a los comandos en un canal de Slack.
Cuando el usuario autoriza la aplicación, tu aplicación recibe un código temporal que luego intercambia a un sistema de información de autenticación permanente usando la API de Slack.

Empezaremos a implementar pronto el flujo, pero en primer lugar, necesitaremos un método para almacenar y utilizar la información de autenticación una vez que hemos recibido de Slack.

Para ello, usaremos la clase Slack_Access, que hemos creado anteriormente en el tutorial.

En la parte superior de la clase, primero definimos las variables para almacenar los datos de la autorización:

// Slack OAuth data

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

A continuación, implementa el constructor para leer los valores de estas variables de un arreglo que se pasa como parámetro:

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

El constructor inicializa las variables a los valores pasados en el arreglo $data, o valores vacíos si el dato no está presente en los atributos del arreglo.

Después de el constructor, agrega una función para comprobar si se ha inicializado el objeto con datos válidos:

/**
 * 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 != '';
}

Entonces, para almacenar los datos de autenticación, agrega la siguiente función:

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

La función devuelve una cadena con formato JSON que contiene los datos de autorización.

En una aplicación real, probablemente querrás atar la información de autorización a las cuentas de usuario y guardar los datos JSON junto con la información de usuario. Sin embargo, en nuestra aplicación de ejemplo, una vez más, vamos a ir con un enfoque simple: asumiremos que sólo un usuario (usted) usará la aplicación, y tan sólo tendremos que almacenar un conjunto de credenciales de OAuth.

Pero primero, vamos a pasar a la clase Slack y aprovechar la funcionalidad que acabas de agregar a Slack_Access.

Implementa el constructor para configurar el objeto de acceso para la instancia actual de Slack:

/**
 * @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 );
    }
}

Después el constructor, agrega una función para comprobar si los datos de autorización del objeto Slack se han establecido:

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

Paso 6: Mostrar el botn de Agregar a Slack

Con la estructura de datos en su lugar, podemos empezar a utilizar los controles de autorización en la aplicación principal y mostrar el botón de "Añadir a Slack".

Observe que mientras la propia clase Slack_Access se puede utilizar en la mayoría de las aplicaciones más o menos como es, la solución utilizada en index.php es sólo con fines de demostración: como no tenemos una base de datos o gestión de usuarios, simplemente se salvan las credenciales de acceso con formato JSON de to_json en un archivo de texto.

En este punto, el archivo aún no existe, que significa que la aplicación todavía no ha añadido ninguna cuenta de Slack, y debe mostrar el botón de "Añadir a Slack" en lugar del campo de texto.

Para implementar el sistema de almacenamiento sencillo, empieza por cambiar index.php función initialize_slack_interface con los siguientes:

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

En las líneas 9-14, la función lee los datos de la autorización como una cadena de un archivo de texto denominado access.txt si el archivo existe. Si el archivo no existe, se inicializa la cadena JSON con un hash vacio.

Luego, en la línea 17, los datos se analizan en un arreglo para pasarlos a la interfaz de Slack (en la línea 19).

Ahora, estamos listos para poner todo junto y hacer nuestra pequeña aplicación mostrar el botón de "Añadir a Slack" si no se encuentran datos de autorización.

Al final del index.php, reemplaza el formulario con el siguiente fragmento de código:

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

En el fragmento de código, en la línea 1, notará que el formulario está ahora rodeado de un control is_authenticated para que un usuario no pueda verlo antes de autorizar la aplicación.

Luego, en el else, en las líneas 8-12, el código muestra ahora el botón "Añadir a Slack".

Vamos a echar un vistazo a lo que está dentro de la etiqueta a del botón:

En primer lugar, el botón apunta al usuario hacia la autorización OAuth de Slack (oauth/autorizar).
Usando el parámetro scope, la aplicación puede definir los permisos que necesita el usuario para permitir que: en nuestro caso, necesitamos webhooks entrante (incoming-webhook) para publicar las notificaciones y la posibilidad de añadir nuevos comandos slash (commands). Para una lista completa de los permisos disponibles, consulte la documentación de la API.
Por último, el enlace debe incluir la clave pública de la aplicación (clinet_id), que almacenamos en nuestra aplicación anteriormente en el tutorial.

El resto es sólo HTML básico para mostrar la imagen del botón.

Ahora, cuando abra la aplicación en su navegador, esto es lo que deberías ver:

Paso 7: Completar la autenticación OAuth

Ahora, el botón de "Añadir a Slack" está situado. ¿Pero qué sucede cuando el usuario hace clic en él?

Primero, el usuario verá la página de autenticación de la aplicación de Slack, que se ve así:

Give the Slack application access to one your Teams channels

Entonces, si todo se luce bien al usuario, él o ella hará clic en el botón Autorizar, en este momento la ejecución te devuelve a tu aplicación.

Te recuerdas cuando definimos la aplicación de Slack, establecimos una dirección URL para callback (devolución de llamada) (YOUR_URL/index.php?action=oauth).

Para manejar este callback (devolución de llamada), vamos a usar el sistema de acciones que hemos creado anteriormente en este tutorial. En tu aplicación real, deberás aplicar el callback URL de una manera que funcione bien para la plataforma que estás utilizando. Por ejemplo, en WordPress, podrías crear un permalink personalizado utilizando el rewrite engine (motor de reescritura).

Sin embargo, mientras que la forma de recibir el callback se difiere de acuerdo con la aplicación, lo que hacemos con los datos recibidos de Slack sigue siendo lo mismo.

Reemplaza la función aun vacía do_action con lo siguiente:

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

Cuando el usuario regresa de la lógica de autorización, esta función se llama con $action con el valor de 'oauth'. Junto con la solicitud, la aplicación recibe un token una sola vez, que se lee en la línea 17.

Luego, en la línea 21, para completar la autorización, la función llama a una función en nuestra clase Slack, do_oauth.

Como recordarás, al inicializar la interfaz de Slack, tratamos de cargar los datos de autenticación desde un archivo de texto access.txt. Cuando no encuentra el archivo, la aplicación decidió que el usuario todavía no había autenticado la solicitud y mostraba el botón "Añadir a Slack".

Ahora, después de la autenticación OAuth ha sido completada con éxito, en la línea 23, la función guarda los datos en ese archivo.

Pero antes de llegar allí, para completar el flujo de autenticación, todavía tenemos que implementar la función do_oauth en la clase de Slack.

Esta función llamará a la API de Slack para intercambiar el código que se pasa a la función de callback de OAuth con datos de autentificación que pueden ser almacenados permanentemente y utilizamos para comunicarnos con Slack hasta que el usuario revoque la autorización.

Para ello, necesitamos una manera de hacer una petición HTTP al servidor de Slack. Hay muchas maneras de hacer las solicitudes HTTP en PHP, y lo que presento aquí no es la única manera. Por ejemplo, si estás desarrollando para WordPress, puedes escoger wp_remote_get y wp_remote_post.

Esta vez, sin embargo, para mantener todo independiente de cualquier framework en particular, decidí hacerlo una librería gratuita con una sintaxis hermosa y limpia, Request.

Instala la biblioteca de acuerdo con las instrucciones en su página web. En el código fuente en el repositorio de GitHub Tuts +, encontrarás la configuración para composer para incluir la libreria a nuestra aplicación.

Una vez que haya instalado Request (o la opción de librería HTTP), agregue la función de do_oauth a la clase de Slack:

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

Veamos la función línea por línea:

En las líneas 14-18, la función inicializa los parámetros de la solicitud HTTP. Cabe destacar el identificador del cliente y el secreto se pasan como opciones de solicitud para utilizar el mecanismo de autenticación básica de HTTP.

En la línea 21, te darás cuenta de que nos envía solo una vez el token recibido en la función de callback a la API de Slack para identificar la solicitud.

La solicitud POST se envía en la línea 23. Entonces, la función procede analizando de la respuesta y ajusta los datos de autorización (líneas 33-44) si todo fue bien, o devuelveuna excepción (líneas 28-31) si hubo un error con la solicitud.

Ahora, el flujo de "Añadir a Slack" está listo. Cuando lo intentes, veras lo siguiente:

The authentication flow was completed successfully

También, si te fijas en tu directorio del proyecto, debes encontrar un archivo de texto denominado access.txt, con los datos de autenticación almacenados en ella.

Ahora, estamos listos para la parte más divertida: hacer que la aplicación envíe a tu canal de Slack.

2. Enviar una notificación a un canal de Slack

Publicar notificaciones a un canal de Slack es una manera poderosa de mantener un equipo actualizado sobre los eventos que son importantes para ellos. Una tienda web puede enviar notificaciones de nuevas compras, un software de seguimiento de fallos automáticamente podría notificar a los desarrolladores, y la lista continúa.

En nuestro ejemplo, como ya se ha visto en la interfaz de usuario anterior, enviaremos cualquier notificación que el usuario envía usando el campo de texto.

Pero la funcionalidad para el envío de cualquier otro tipo de notificaciones es el mismo, por lo que una vez que esté listo, puedes usar el mismo código para enviar tus propias notificaciones más complejas.

Paso 1: Crear una función para el envío de una notificación

En la clase Slack, agrega la siguiente función:

/**
 * 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' );
    }
}

La publicación de una notificación a un canal de Slack se hace usando un webhook (gancho web), una URL de autorización específica que Slack expone a la aplicacion para publicar en el canal.

No prestamos mucha atención a lo anterior en el flujo de "Añadir a Slack", pero si nos fijamos en los datos en Slack_Access otra vez, notarás que Slack devuelve un campo llamado incoming_webhook. Este campo es un arreglo con dos campos dentro de ella: la URL donde debemos publicar nuestras notificaciones y el canal que el usuario seleccion para los mensajes de la aplicacion.

Para acceder a esos datos, agrega las siguientes dos funciones a la clase Slack_Access:

/**
 * 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 '';
}

Ahora, volvamos a la función anterior send_notification y mira cómo estas funciones son utilizadas para enviar la notificación.

En la línea 19, notarás que la solicitud HTTP es enviada una URL incoming webhook (gancho web entrante) guardada en los datos de autorizacion.

Y más tarde, en la línea 24, el canal es pasado en los parámetros de la petición, junto con el texto y los datos adjuntos que desea publicar.

Paso 2: Utilizar la notificación que envía la función en la aplicación de ejemplo

Ahora que hemos implementado la función de envío de notificaciones, vamos a agregarle la funcionalidad a nuestra interfaz de usuario y prueba.

Agrega la siguiente nuevo case (caso) a la función do_action en index.php:

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

Este fragmento de código lee el mensaje de los parámetros de la petición (línea 3) y utiliza la función send_notification que acabamos de crear para publicar en Slack (línea 6).

Como formulario se creó ya al principio del tutorial, ahora estás listo para enviar tu primer mensaje a tu canal de Slack. Escribe algo en el campo de texto y Pulsa Intro para enviar el formulario.

Entonces, echa un vistazo a tu canal Slack para ver tu mensaje:

Paso 3: Use los adjuntos para hacer tus notificaciones más informativas

En la función de send_notification, probablemente notaste un parámetro llamado attachments (archivos adjuntos). No lo mencioné aun como no encaja tan bien con la aplicación de ejemplo. Sin embargo, los attachments (adjuntos) son una potente forma de pasar información más interesante sobre eventos de la aplicación al canal de Slack, y probablemente querrás utilizarlos en tus aplicaciones.

Por lo tanto, vamos a experimentar un poco con los adjuntos modificando un poco la llamada send_notification del paso 2. Reemplaza la llamada $slack->send_notification() con el siguiente código:

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

El archivo adjunto especificado en el código anterior es una notificación imaginaria acerca de la adición de una nueva receta de pan en una base de datos de recetas. Está allí sólo como un ejemplo, así que Anímate y modifícalo para ver cómo los cambios realizados afectan el resultado en el canal de Slack.

fallback: un mensaje de texto requerido que se muestra si no se puede mostrar el archivo adjunto.
title: un título para el adjunto, estilo usando una tipografía más grande.
title_link: una dirección URL que se abre cuando el usuario hace clic en el enlace. En nuestro ejemplo, Esto demostraría la receta.
text: texto que aparecerá dentro del adjunto.
color: el color de la línea en el lado izquierdo del adjunto.
fields: una lista de campos de datos para mostrar en los adjuntos. En el ejemplo, se utilizan para mostrar información acerca de la receta.
image_url: Una dirección URL a una imagen para mostrar en el archivo adjunto.

Esto es lo que verás cuando publiques la notificación con el adjuntos especificado arriba:

Jugar con los parámetros y verás cómo los cambios afectan los mensajes publicados en tu canal de lack: modifica los atributos, envia una nueva notificación y echa un vistazo a lo que ha cambiado.

Para obtener más información acerca de los adjuntos, mira la documentación de Slack.

3. Has tu aplicación responda a comandos Slash

La aplicación ahora puede hablar con Slack. A continuación, vamos a hacer que la comunicación funcione también al revés: añadiendo comandos slash, podemos hacer que Slack trabaje como interfaz para nuestra aplicación.

En una aplicación del mundo real, esto tiene muchos casos de uso. Marca un error como solucionado, marcar un pedido como enviado, o pidiendo un chiste son unos vienen a la mente.

Vamos a seguir adelante y poner en práctica la solicitud de la broma a publicar una broma cuando alguien escriba /broma en el canal de Slack.

Paso 1: Definir un comando de slash

En primer lugar, visite la página de configuración de la aplicación de Slack para definir el nuevo comando slash.

Desplázate hacia abajo hasta la sección con el título, Slash Commands (barra de comandos) y has clic en Create new command (crear nuevo comando).

En la siguiente pantalla, introduce la información necesaria para especificar el comando nuevo y has clic en Save (guardar).

Aquí están breves descripciones de los campos de esta página:

Command: El comando slash, incluido el carácter slash (/ barra). Por ejemplo, /joke.
Request URL: La URL en el servidor que debe llamarse cuando alguien escribe este comando slash en un canal de Slack. Aquí es donde localtunnel nos ayuda: la URL debe ser HTTPS y disponible para internet. Utilice el siguiente formato de dirección URL para hacer que la URL que solicita sea compatible con la funcionalidad que construiremos en el paso 2: YOUR_SERVER/index.php?action=command.
Short Description: Una descripción que se muestra en la ventana emergente de autocompletar cuando alguien está escribiendo el comando.
Usage Hint: Si el comando toma parámetros, usted puede describirlos aquí. Este texto también es visible en el cuadro de diálogo de autocompletar.

Después de guardar el comando, usted encontrará su nuevo comando que se muestra en la sección Slash Commands (barra de comandos). Puedes utilizar los botones para editarlo o borrarlo.

Slash Commands now include the joke command

A continuación la lista de comandos, encontrarás una cadena etiquetada Verification Token (Token de verificación).

Puede utilizar este token para comprobar que los comandos ciertamente vienen de Slack antes de ejecutarlos. Almacena el símbolo (token) en la aplicación de la misma manera que hiciste con el ID de cliente y el secreto anteriormente en el tutorial, por ejemplo mediante la adición de una constante al inicio del index.php:

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

Paso 2: Crea un sistema para realizar un seguimiento de barra de comandos en tu aplicación

Ahora, Slack permitirá identificar el comando cuando alguien escribe en la ventana de chat Slack (puedes probarlo ahora para que veasla ventana emergente de autocompletar).

Cuando el usuario envía el comando, Slack llamará nuestro servidor en la URL de solicitud especificada en el paso anterior. Ahora, tendremos que implementar la funcionalidad para hacer que nuestra aplicación responda a él correctamente.

Puedes añadir más de un comando de barra para la aplicación de Slack, es bueno tener un varios comandos de barra. Por eso comenzaremos por crear un sistema para realizar un seguimiento de comandos en la aplicación.

En primer lugar, en la clase Slack, agrega la siguiente variable que contenga los comandos:

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

En el constructor de la clase, agrega una línea para inicializar el arreglo:

1	$this->slash_commands = array();

A continuación, crea una función para añadir un nuevo comando de barra al arreglo:

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

Ahora que tienes una lista de comandos de barra, agrega una función para ejecutar un comando:

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

Vamos a ir a través de la función para ver lo que hace:

En primer lugar, en las líneas 8-12, la función recoge datos de los parámetros de petición:

token se utiliza para verificar que la solicitud es una comando válida de Slack.
command contiene el comando de barra que debe ser ejecutado.
text es la cadena de texto que se ha escrito después del comando. Puede ser utilizado para pasar parámetros a tu comando de barra.
user_name es el nombre de usuario del usuario que envió el comando de barra.

En la línea 15, la función hace la verificación comparando el token que se pasó en los parámetros de la petición a la que tenemos almacenadas en el paso anterior.

Si el token es válido, la función continua ejecutando el comando, si alguno con el nombre del comando especificado ha sido registrado en la clase de Slack. La ejecución del comando se realiza en la línea 20, donde la función hace una llamada a la función de callback especificada para el comando.

Luego, en la línea 21, la respuesta es codificada en una cadena JSON y la muestra. Observe que la función termina con una llamada de exit para asegurarse de que nada más llega impreso después de la respuesta.

Para completar la funcionalidad, agregue la función get_command_token para recuperar el token de verificación del comando de la aplicación:

/**
 * 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 '';
}

La funcionalidad de comando de barra en la clase Slack está ahora completada, y todo lo que queda por hacer antes de que podamos implementar nuestro primer comando es conectar la URL de callcbak a este código.

Para ello, añade una nuevo case en la función de do_action en index.php:

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

Paso 3: Registre y compruebe el comando de barra

Ahora que hemos creado un sistema para el manejo de comandos de barra en nuestra aplicación, vamos a utilizarlo para implementar la funcionalidad del comando /joke.

En primer lugar, al final de la función initialize_slack_interface, agregue las siguientes líneas de código para registrar el comando y pasar el nombre de la función que manejará el comando:

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

A continuación, cree la función:

/**
 * 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],
    );
}

Como esta función se creó como una demo, no hace mucho: al azar escoge uno de los chistes y devuelvelos en un formato esperado por Slack.

Nota que aunque esta función de comando no tiene ningún parámetro, para un ejemplo más complejo, se pueden añadir dos parámetros: $text para acceder a los datos que el usuario escribió después del comando y $user_name para obtener el nombre del usuario que ha enviado el comando.

Para probar el comando, siga adelante y escriba /joke en el canal de Slack.

Conclusión e Ideas para el futuro

Has completado el tutorial y sabes como integrar tu aplicación PHP con Slack. Durante el tutorial, también has construido herramientas para el envío de notificaciones a un canal de Slack, así como responder a los comandos que los usuarios escriben directamente en Slack.

El siguiente paso es poner estas ideas a trabajar de verdad.

Pensar sobre tu aplicación y busca lugares donde hablar con Slack y escuchar a los comandos de Slack podrían hacer la experiencia más útil y agradable para tus usuarios y ponlos en práctica.

La plataforma está evolucionando rápidamente, y así es la API. Mantén la vista hacia dónde va y construye algo increíble!

¡Sé el primero en conocer las nuevas traducciones–sigue @tutsplus_es en Twitter!