# Cómo empezar

¿Quieres construir una extensión de Flarum? ¡Has venido al lugar correcto! Este documento te llevará a través de algunos conceptos esenciales, después de lo cual construirás tu primera extensión de Flarum desde cero.

# Arquitectura

Para entender cómo extender Flarum, primero necesitamos entender un poco cómo está construido Flarum.

Ten en cuenta que Flarum utiliza algunos lenguajes y herramientas modernas. Si sólo has construido plugins para WordPress antes, puede que te sientas un poco fuera de tu alcance. No pasa nada, es un buen momento para aprender cosas nuevas y ampliar tus conocimientos. Sin embargo, te aconsejamos que te familiarices con las tecnologías descritas a continuación antes de continuar.

Flarum se compone de tres capas:

Las extensiones a menudo necesitarán interactuar con estas tres capas para hacer que las cosas sucedan. Por ejemplo, si quieres construir una extensión que añada campos personalizados a los perfiles de los usuarios, tendrías que añadir las estructuras de base de datos apropiadas en el backend, exponer esos datos en la public API, y luego mostrarlos y permitir a los usuarios editarlos en el frontend.

Así que... ¿cómo extendemos estas capas?

# Extensores

Para extender Flarum, usaremos un concepto llamado extensores. Los extensores son objetos declarativos que describen en términos sencillos los objetivos que se pretenden alcanzar (como añadir una nueva ruta a tu foro, o ejecutar algún código cuando se crea una nueva discusión).

Cada extensor es diferente. Sin embargo, siempre tendrán un aspecto similar a este:

// Registrar un archivo JavaScript y un archivo CSS para ser entregado con el frontend del foro
(new Extend\Frontend('forum'))
    ->js(__DIR__.'/forum-scripts.js')
    ->css(__DIR__.'/forum-styles.css')

Primero se crea una instancia del extensor, y luego se llama a los métodos en él para la configuración adicional. Todos estos métodos devuelven el propio extensor, de modo que puedes conseguir toda la configuración simplemente encadenando llamadas a métodos.

Para mantener la coherencia, utilizamos este concepto de extensores tanto en el backend (en la tierra de PHP) como en el frontend (en la tierra de JavaScript). Todo lo que haga en su extensión debe ser hecho a través de extensores, porque son una garantía que le estamos dando de que una futura versión menor de Flarum no romperá su extensión.

Todos los extensores disponibles actualmente en el núcleo de Flarum pueden encontrarse en el espacio de nombres Extend (opens new window) (documentación de la API de PHP) (opens new window) Las extensiones también pueden ofrecer sus propios extensores.

# Hola Mundo

¿Quieres ver un extensor en acción? El archivo extend.php en la raíz de tu instalación de Flarum es la forma más fácil de registrar extensores sólo para tu sitio. Debería devolver un array de objetos extensores. Ábrelo y añade lo siguiente:

<?php

use Flarum\Extend;
use Flarum\Frontend\Document;

return [
    (new Extend\Frontend('forum'))
        ->content(function (Document $document) {
            $document->head[] = '<script>alert("Hello, world!")</script>';
        })
];

Ahora haz una visita a tu foro para un agradable (aunque extremadamente molesto) saludo. 👋

Para personalizaciones sencillas específicas del sitio -como añadir un poco de CSS/JavaScript personalizado, o integrarse con el sistema de autenticación de tu sitio- el archivo extend.php en la raíz de tu foro es genial. Pero en algún momento, tu personalización podría superarlo. O tal vez hayas querido construir una extensión para compartirla con la comunidad desde el principio. ¡Es hora de construir una extensión!

# Empaquetado de extensiones

Composer (opens new window) es un gestor de dependencias para PHP. Permite a las aplicaciones tirar fácilmente de las bibliotecas de código externas y hace que sea fácil mantenerlas actualizadas para que la seguridad y las correcciones de errores se propaguen rápidamente.

Resulta que cada extensión de Flarum es también un paquete de Composer. Eso significa que la instalación de Flarum de alguien puede "requerir" una determinada extensión y Composer la traerá y la mantendrá actualizada. Muy bien.

Durante el desarrollo, puedes trabajar en tus extensiones localmente y configurar un repositorio de rutas de Composer (opens new window) para instalar tu copia local. Crea una nueva carpeta packages en la raíz de tu instalación de Flarum, y luego ejecuta este comando para decirle a Composer que puede encontrar paquetes aquí:

composer config repositories.0 path "packages/*"

Ahora vamos a empezar a construir nuestra primera extensión. Crea una nueva carpeta dentro de packages para tu extensión llamada hello-world. Pondremos dos archivos en ella: extend.php y composer.json. Estos archivos sirven como el corazón y el alma de la extensión.

# extend.php

El archivo extend.php es igual que el que está en la raíz de su sitio. Devolverá un array de objetos extensor que le dicen a Flarum lo que quieres hacer. Por ahora, solo mueve el extensor Frontend que tenías antes.

# composer.json

Necesitamos decirle a Composer un poco sobre nuestro paquete, y podemos hacerlo creando un archivo composer.json:

{
    "name": "acme/flarum-hello-world",
    "description": "Say hello to the world!",
    "type": "flarum-extension",
    "require": {
        "flarum/core": ">=0.1.0-beta.15 <0.1.0-beta.16"
    },
    "autoload": {
        "psr-4": {"Acme\\HelloWorld\\": "src/"}
    },
    "extra": {
        "flarum-extension": {
            "title": "Hello World",
            "icon": {
                "name": "fas fa-smile",
                "backgroundColor": "#238c59",
                "color": "#fff"
            }
        }
    }
}
  • name es el nombre del paquete de Composer en el formato vendedor/paquete.

    • Debes elegir un nombre de proveedor que sea único para ti - tu nombre de usuario de GitHub, por ejemplo. Para los propósitos de este tutorial, asumiremos que estás usando acme como tu nombre de proveedor.
    • Debes anteponer a la parte del package el prefijo flarum- para indicar que se trata de un paquete específicamente destinado a ser utilizado con Flarum.
  • description es una breve descripción de una frase de lo que hace la extensión.

  • type debe ser establecido como flarum-extension. Esto asegura que cuando alguien "requiera" su extensión, será identificada como tal.

  • require contiene una lista de las dependencias propias de su extensión.

    • Querrá especificar la versión de Flarum con la que su extensión es compatible aquí.
    • Este es también el lugar para listar otras bibliotecas de Composer que su código necesita para funcionar.

    Elige cuidadosamente la versión de Flarum

    Mientras Flarum esté todavía en fase beta, le recomendamos que declare la compatibilidad sólo con la versión actual de Flarum:

    "flarum/core": ">=0.1.0-beta.15 <0.1.0-beta.16"
    
  • autoload indica a Composer dónde encontrar las clases de su extensión. El espacio de nombres aquí debe reflejar el nombre del proveedor y del paquete de su extensión en CamelCase.

  • extra.flarum-extension contiene alguna información específica de Flarum, como el nombre de su extensión y el aspecto de su icono.

Consulte el esquema composer.json (opens new window) para obtener información sobre otras propiedades que puede añadir a composer.json.

TIP

Utilice el FoF extension generator (opens new window) para crear automáticamente el andamiaje de su extensión.

# Instalación de la extensión

Lo último que tenemos que hacer para empezar a funcionar es instalar tu extensión. Navega al directorio raíz de tu instalación de Flarum y ejecuta el siguiente comando:

composer require acme/flarum-hello-world *@dev

Una vez hecho esto, sigue adelante y activa la extension en la página de administración de tu foro, luego navega de nuevo a tu foro.

¡Listo!

Estamos haciendo buenos progresos. Hemos aprendido a configurar nuestra extensión y a utilizar los extensores, lo que nos abre muchas puertas. Sigue leyendo para aprender a extender el frontend de Flarum.