Cómo conectar tu aplicación web PHP con confluence

Con una simple llamada por get usando la librería de php CURL, podemos conectar con el gestor de documentación Confluence y así enlazar esta documentación en tu página web. Veamos cómo podemos hacerlo.

Lo primero que debemos hacer es leer la Confluence REST API Documentation. En ella podréis ver la estructura que necesitamos en las URLs, los parámetros y los datos que podremos obtener de confluence como por ejemplo el contenido HTML de una página, el menú de árbol, etc…

La REST API de Confluence está protegida por las mismas restricciones que se proporcionan a través de la interfaz web estándar de Confluence. Esto significa que, si no iniciamos sesión, está accediendo a Confluence de forma anónima. Además, si iniciamos sesión y no tiene permiso para ver algo en Confluence, tampoco podrá verlo utilizando la REST API de Confluence.

El modo de autenticación de confluence se basa es basic authentication. Este método envía un usuario y contraseña en las cabeceras de la request para conectarse.

Veamos un ejemplo. Imagina que tu usuario es user_confluence y tu contraseña !con_pass_957:

1- Crea una cadena con el usuario y la contraseña: user_confluence:!con_pass_957,Ahora codifica la cadena usando base64.

2- Para codificar la cadena en base64 utilizamos la función base64_encode:

<?php
echo base64_encode("user_confluence:!con_pass_957");
?>

curl -D- \
   -X POST \
   -H "Authorization: Basic dXNlcl9jb25mbHVlbmNlOiFjb25fcGFzc185NTc" \
   -H "Content-Type: application/json" \
   "https://confluenc.domain/rest/api/content/123?expand=body.view"

Esta request devolverá en formato JSON el contenido HTML de página con el ID 123.

Podemos hacer una prueba de connexión usando el programa gratuito Advanced REST client:

Una vez que sabemos como conectar con confluence, vamos a pasar este comando curl a código PHP. En el siguiente ejemplo se muestra como obtener el contenido HTML de una página:

$ch = curl_init();

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_VERBOSE, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_COOKIEFILE, '');
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_ENCODING, '');

$header = array();
$header[] = "Authorization: Basic " . base64_encode("user_confluence:!con_pass_957");
$header[] = "Content-Type: application/json";

$page_id = 123;

$url = "https://confluence.domain.com/rest/api/content/" . $page_id . "?expand=body.view";

curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
curl_setopt($ch, CURLOPT_URL, $url);

$result = curl_exec( $ch );

print_r(json_decode($result, true));

Como veis, en el ejemplo, hacemos una llamada a confluence usando curl y la url https://confluence.domain.com/rest/api/content/123?expand=body.view

Las REST API de confluence ofrece diferentes estructuras en las URLs y parámetros para obtener los diferentes contenidos. Por ejemplo:

• Obtener el contenido HTML de una pagina: https://confluence.domain.com/rest/api/content/123?expand=body.view
• Obtener las páginas hijas de una página padre: https://confluence.domain.com/rest/api/content/123/child?expand=page
• Obtener adjuntos: https://confluence.domain.com/rest/api/content/123/child/attachment. Los ficheros adjuntos de una página normalmente son las imágenes que se incluyen dentro de ella.
• Obetener las etiquetas de una página: https://confluence.domain.com/rest/api/content/123/label

Así podemos obtener el contenido de todas las páginas, imágenes y etiquetas de un espacio completo de confluence.

En el código HTML que se obtiene de la página de confluence, la url de las imágenes apuntan a la url de confluence. Ej: https://confluence.domain.com/download/attachments/123456789/image2020-2-18_12-54-33.png?version=1&modificationDate=1584111935000&api=v2

Nota: Estas imágenes no podrán ser accesibles ya que no estarás conectado a confluence directamente. Para solucionar esto podemos descargarnos todas las imágenes de página y modificar las url usando DOM. Ej:

/**
 * GET CONTENT
 * Function to get the content of page in confluence
 * @param int $page_id
 * @return array
 */
public function getContent($page_id = null)
{
    $response = array();
    if($page_id) {

        $url = $confluence_url . "/rest/api/content/" . $page_id . "?expand=body.view";

        $page = $this->get_result($url); //Connect to confluence to get the content

        if($page) {

            $this->getAttachements($page_id); //Here we donwload the images of the page

            //Use DOM to modify the url of the images
            $doc = new DOMDocument();
            $doc->loadHTML(mb_convert_encoding($page['body']['view']['value'], 'HTML-ENTITIES', 'UTF-8'), LIBXML_NOWARNING);

            $tags = $doc->getElementsByTagName('img');//Get all img tags
            foreach ($tags as $tag) {
                $filename = $tag->getAttribute('data-linked-resource-default-alias'); //Get file name
                $new_src_url = $this->confluence_images_dir . $page_id . '/' . $filename ; //We add the new url
                $tag->setAttribute('src', $new_src_url); //Apply the new url
            }
            $response['content'] = $doc->saveHTML();
            $response['title'] = $page['title'];
        }
    }
    return $response;
}

Aquí tenéis una clase completa usada como librería en el framework de php CodeIgniter.

https://github.com/fjfran/php_connect_confluence