mask_export para TYPO3

Sin mask_export los elementos Mask dependen de Mask y cada despliegue es un riesgo

Mask es uno de los frameworks más utilizados para Custom Content Elements en TYPO3. Pero Mask almacena su configuración en un archivo JSON y genera campos de base de datos en tiempo de ejecución. En un proceso de desarrollo profesional con múltiples entornos (local, staging, producción) esto genera un problema: cómo llevar los nuevos elementos de contenido del equipo de desarrollo al servidor productivo. Recrearlos manualmente en el backend. Copiar el mask.json por FTP y ejecutar Database Compare. Ambas opciones son propensas a errores y no reproducibles.

mask_export resuelve este problema. La extensión exporta todas las definiciones Mask como extensión TYPO3 independiente con su propio ext_tables.sql, configuraciones TCA y plantillas Fluid. Esta extensión se instala vía Composer, se versiona en Git y se despliega por CI/CD, exactamente como cualquier otra extensión TYPO3. Así Mask se convierte en una solución enterprise.

Escenarios de uso habituales

Agencias con pipeline CI/CD. Agencias que despliegan proyectos TYPO3 mediante GitLab CI, GitHub Actions o Deployer necesitan artefactos versionables. mask_export genera una extensión que se instala con composer require. Cada cambio en un elemento de contenido genera un nuevo commit que pasa por la pipeline: lint, tests, despliegue a staging, despliegue a producción. Sin intervención manual en el backend.

Proyectos multi-site con elementos compartidos. Corporaciones con 5 a 20 instancias TYPO3 (filiales, marcas, subsidiarias) quieren elementos de contenido uniformes en todos los sitios. mask_export genera una extensión central que se integra en todas las instancias. Los cambios se hacen una vez y se distribuyen a todos los sitios. Sin mask_export, los elementos Mask tendrían que recrearse manualmente en cada instancia.

Traspaso entre desarrollo y redacción. Los desarrolladores definen elementos de contenido en el sistema local, los exportan con mask_export y hacen commit del resultado. Los editores trabajan en staging o producción y usan los elementos sin necesitar la GUI de Mask. La propia extensión Mask puede incluso desinstalarse en sistemas productivos donde solo se necesita la extensión exportada.

Arquitectura técnica

mask_export lee la configuración de Mask desde la ruta definida en Mask y genera una extensión TYPO3 completa. La estructura generada contiene: ext_emconf.php (metadatos), ext_tables.sql (definiciones de base de datos para todos los campos Mask), Configuration/TCA/Overrides/tt_content.php (configuración TCA), Resources/Private/Templates/ (plantillas Fluid, generadas a partir de la configuración de campos) y TypoScript setup para el renderizado en frontend.

La exportación se realiza en el módulo de backend de mask_export, no hay comando CLI: allí la extensión se descarga como ZIP o se instala directamente. El resultado es un directorio que se integra como paquete Composer o como extensión local en typo3conf/ext/. La extensión Mask ya no se necesita tras la exportación, siempre que no se creen o modifiquen elementos.

Importante: mask_export exporta solo la definición (campos, plantillas, TCA), no los contenidos (los textos, imágenes reales en tt_content). Los datos permanecen en la base de datos y se migran independientemente.

Problemas frecuentes y soluciones

Olvido de exportar tras un cambio. Un desarrollador modifica un campo Mask en el sistema local pero solo hace commit del mask.json, no de la nueva exportación. En staging falta entonces la configuración TCA. Solución: repetir la exportación en el módulo de backend tras cada cambio y hacer commit de ella junto con el mask.json. Gosign usa una verificación en la pipeline de despliegue que compara si mask.json y la última exportación están sincronizados.

Las plantillas Fluid no se incluyen en la exportación. mask_export no incorpora las plantillas propias, sino que genera para cada elemento una plantilla de ejemplo a partir de la configuración de campos. Por eso las plantillas propias faltan en la exportación, estén donde estén. Solución: colocar las plantillas propias en un site package, como recomienda el README de mask_export, e integrarlas mediante la constante TypoScript templateRootPath de la extensión exportada.

Conflictos al usar Mask y la extensión exportada simultáneamente. Si en el sistema productivo están instalados tanto Mask como la extensión exportada, pueden producirse registros TCA duplicados. Solución: en sistemas donde los editores no crean elementos nuevos, instalar solo la extensión exportada y desinstalar Mask. En sistemas de desarrollo, ambos funcionan en paralelo; la exportación sobrescribe la versión anterior.

Migración y compatibilidad de versiones

Desde mayo de 2022 no ha salido ninguna versión nueva de mask_export: la última, 4.0.2, admite Mask hasta 7.x y no hay ninguna para Mask 8 o 9. Solo es compatible con TYPO3 v9.5 a v11.5; para TYPO3 v12 y v13 no hay versión. La extensión exportada es compatible con la misma versión TYPO3 que la versión de Mask desde la que se generó.

Para proyectos que quieran pasar a la extensión Content Blocks con TYPO3 v13 o v14, mask_export puede servir como paso intermedio antes de la actualización: primero exportar los elementos Mask (estructura limpia basada en archivos), luego traducir las configuraciones TCA exportadas a definiciones Content Block. El esfuerzo por elemento es reducido (30 a 60 minutos) cuando la extensión exportada sirve de referencia.

Una ventaja frecuentemente pasada por alto de mask_export es la testabilidad. Cuando los elementos de contenido existen como extensión independiente, se pueden escribir tests automatizados: verificar la configuración TCA (están todos los campos correctamente definidos), probar el renderizado de plantillas (produce la plantilla Fluid HTML válido) y validar el esquema de base de datos (coinciden los tipos de columna). En una pipeline CI, estos tests detectan errores antes de que lleguen a staging o producción.