mask_export para TYPO3

Sin mask_export los elementos Mask no son versionables y cada despliegue es un riesgo

Mask es el estándar 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 el mask.json (o config/mask.json desde Mask 8) 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, copiadas desde la ruta configurada de plantillas Mask) y opcionalmente TypoScript setup para el renderizado en frontend.

El proceso de exportación se ejecuta como comando TYPO3 CLI: php typo3/sysext/core/bin/typo3 mask:export. 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: integrar el comando mask_export en un hook Git (pre-commit) o en la pipeline CI. 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 copia por defecto las plantillas de la ruta configurada. Si las plantillas están fuera de esa ruta (por ejemplo, en un paquete de tema propio), no se capturan. Solución: colocar todas las plantillas Mask en un directorio unificado y referenciarlo en la configuración de Mask.

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

mask_export sigue el ciclo de releases de Mask: cuando Mask soporta una nueva versión TYPO3, mask_export se actualiza oportunamente. Actualmente son compatibles TYPO3 v11, v12 y v13. 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 migrar a la Content Block API nativa en TYPO3 v13, mask_export puede servir como paso intermedio: 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.