Crear un Bundle desde cero

Esta guía tiene como objetivo mostrar como crear un bundle propio e integrado al portal SIU-Huarpe. Los bundles son el mecanismo mediante el cual se implementan servicios en el portal de autogestión.

Para mayores detalles, ver la sección de conceptos generales.

Requerimientos

1. Acceso al código fuente del portal alojado en hub
2. Un repositorio Git, propio y privado, donde alojar el desarrollo
3. Opcional. Realizar un fork propio del portal

Tipos de bundles

Si bien los bundles son plugins o extensiones del portal, aquí se identifica los tipos de bundles.

Buenas prácticas

Existen recomendaciones a seguir para que un bundle se condidere buen ciudadano dentro del portal. Permiten que en el desarrollo de bundles sea fluido y en paralelo, evitando situaciones conflictivas.

Puede consultar la guía de buenas prácticas aquí.

Desarrollar

Vamos a suponer que la institución UUNN creará el bundle llamado ServicioBundle.

Una vez determinado el tipo de bundle a crear y elegimos entre alternativas para mantener en el tiempo el bundle, nuestro ServicioBundle será:

1. generado a partir de un bundle-base
2. alojado en el directorio src-bundles de un fork propio del portal y gestionado en dicho repositorio
3. configurado para quedar activo por defecto
4. empaquetado junto el fork del portal en una imagen Docker

Crear el bundle

Vamos a crear el directorio UUNN que representa nuestra institución. Allí adentro podremos alojar otros bundles

mkdir /tmp/UUNN

Descargamos el bundle-base que tomaremos como referencia para la estructura inicial del bundle, descomprimiendolo

wget https://gitlab.siu.edu.ar/siu-arai/bundle-base/-/archive/master/bundle-base-master.zip \
  && unzip bundle-base-master.zip

Hay que mover el bundle-base a la ruta creada previamente

mv bundle-base-master /tmp/UUNN/ServicioBundle

Deberá contar con una estructura similar a esta:

    UUNN
    |_ ServicioBundle
        |_ Controller
        |_ DependencyInjection
        |_ Resources
            |_ assets
            |_ config
            |_ public
                |_ css
                |_ images
            |_ views
                |_ Default
        |_ Security
            |_ Role
        |_ Service
        |_ Tests
        |_ DefaultBundle.php

Finalmente, hay que ejecutar un cambio de nombre masivo de SIU\Default a UUNN\Servicio. Para lo cual podemos ayudarnos del siguiente comando:

/tmp/UUNN/ServicioBundle/bin/cambiar-nombre-bundle.sh Default Servicio UUNN

Alojar el bundle

Se asume que se ha iniciado un fork propio del portal. Lo que haremos es clonar el repositorio donde ya tenemos alojado dicho fork del portal y alojar allí adentro nuestro nuevo bundle.

git clone https://uunn.local/huarpe.git huarpe

Inmediatamente, copiamos el bundle ServicioBundle que acabamos de generar a su ubicación.

mv /tmp/UUNN huarpe/src-bundles/UUNN

La carpeta UUNN funciona como namespace en PHP, lo que permite agrupar otros bundles de la misma institución.

Finalmente, subimos nuestros cambios al fork del portal

git add huarpe/src-bundles/UUNN

y

git commit -m "creación de ServicioBundle"

Listo! El bundle ServicioBundle ya está generado. En la siguiente sección se lo configura en una instancia del código del portal SIU-Huarpe.

Configurar el bundle

Estos pasos se deben hacer para agregar un bundle que aún NO estén en el código del proyecto ofrecido por el SIU.

En estos momentos, el bundle ServicioBundle ya se encuentra en el directorio src-bundles del código fuente, ya sea porque:

1. seguimos los pasos previos y lo alojamos en nuestro propio fork
2. lo copiamos manualmente al directorio src-bundles
3. lo consumimos como librería vía Composer

En cualquiera de estos casos, lo que sigue es decirle a SIU-Huarpe que debe activar el bundle. Para ello se crea el archivo config/bundles_local.php quedando así:

<php

return [
    UUNN\ServicioBundle\UUNNServicioBundle::class => ['all' => true],
];

Nota: este archivo config/bundles_local.php no existe por defecto, sólo es de utilidad cuando se realiza un fork de SIU-Huarpe.

Si el bundle debe ser distribuido con SIU-Huarpe, normalmente se deberá incluir una sección que permita su activación mediante una variables de entorno en el archivo config/bundles.php, quedando asi:

...
$dinamicBundles = [
    // otros bundles ...
    'BUNDLE_UUNNServicio_ACTIVO' => UUNN\ServicioBundle\UUNNServicioBundle::class,
];
...

Configurar el comportamiento

Si nuestro bundle posee modulos JS que proveen comportamiento durante las interacciones, de acuerdo a los lineamientos especificados, incorporaremos dichos modulos haciendo uso del plugin webpack-encore.

Dentro de su archivo de configuración webpack.config.js generaremos una o varias entrada/s addEntry para nuestro bundle, donde especificaremos los archivos JS necesarios en cada caso.

Estas entradas las colocaremos sobre el final del archivo pero de manera previa a la sentencia de exportación del módulo de configuración.

...
Encore
    .addEntry('miServicio_js', [
        './src-bundles/UUNN/ServicioBundle/Resources/assets/common.js',
        './src-bundles/UUNN/ServicioBundle/Resources/assets/index.js',
    ]);
...

module.exports = Encore.getWebpackConfig();    

Luego podremos incorporar en los templates del bundle los archivos necesarios mediante la invocacion a la función encore_entry_js_files.

Para que las modificaciones a los archivos JS se vean reflejadas en runtime, es necesario cumplimentar con estos procesos

Configurar conexión a servicios externos

Si nuestro bundle consume alguna api, siguiendo los lineamientos para armar un bundle, nuestro ServicioBundle consume una api de un nuevo sistema, con lo cual vamos a tener que configurarlo de la siguiente manera en el archivo config/services.yaml quedando así:

parameters:
  ...
  uunn.servicio.api: { auth: [user, pass, basic], base_uri: 'http://url.servicio/api/' }

La entrada uunn.servicio.api está estandarizada y su contenido representa:

• en auth, user y pass son las credenciales de acceso a la api y basic es el tipo de autenticación de dicha api. Se soporta basic, digest.
• en base_uri se coloca la URL completa al servicio o backend al cual nos conectaremos vía api RESTFull.

Deberá construir estas entradas para que sean parametrizables vía variables de entorno.

Ajustes finales

Si todo está listo, resta por ejecutar:

• una limpieza de caché
• generación de assets
• corrección de permisos

@TODO quizá el bundle necesite adicionar cosas

Pasaje a producción

1. con fork propio del portal, solo build docker image
2. repo aislado del bundle, extendiendo imagen docker existente