Schemaker para TYPO3

Por qué la documentación ausente de ViewHelper frena los proyectos TYPO3

Los Fluid ViewHelper son la columna vertebral de todo desarrollo de plantillas TYPO3. Pero en cuanto un proyecto incluye ViewHelpers propios, comienza el problema: ningún desarrollador conoce todos los parámetros, ningún IDE ofrece autocompletado, y la documentación existe en el mejor de los casos como comentario en el código PHP. Schemaker resuelve este problema generando automáticamente archivos de esquema XSD a partir de las clases PHP. Estos esquemas proporcionan a los IDEs la información necesaria para autocompletado, validación y documentación inline directamente en la plantilla Fluid.

Para equipos con más de un desarrollador TYPO3, no es una cuestión de comodidad sino de productividad. Sin archivos de esquema, cada desarrollador dedica entre 15 y 30 minutos diarios a buscar parámetros de ViewHelper en el código fuente.

Escenarios de uso habituales

Proyectos enterprise con más de 20 ViewHelpers propios. Grandes instalaciones TYPO3 suelen incluir ViewHelpers especializados para formato de precios, verificaciones de permisos, llamadas a API o lógica sectorial. Sin Schemaker, cada nuevo desarrollador debe leer el código fuente para entender los parámetros disponibles. Con Schemaker, abre la plantilla Fluid en PhpStorm o VS Code y recibe sugerencias inmediatamente.

Desarrollo de extensiones para el TER. Quien publica extensiones con ViewHelpers propios puede incluir archivos XSD generados con Schemaker. Esto reduce consultas de soporte y mejora la experiencia del desarrollador.

Onboarding de nuevos desarrolladores. En una agencia TYPO3, los desarrolladores cambian regularmente entre proyectos. Los esquemas generados por Schemaker funcionan como documentación viva: siempre están actualizados porque se generan directamente del código. En lugar de 2 días de familiarización, son 2 horas.

Arquitectura técnica

Schemaker analiza clases PHP que heredan de AbstractViewHelper. Lee las anotaciones @param, las llamadas a registerArgument() y los DocBlocks de clase. A partir de ellos genera archivos de esquema XSD asignados al namespace Fluid. La integración funciona vía TYPO3 CLI: vendor/bin/typo3 schemaker:generate genera archivos XSD para todos los namespaces de ViewHelper registrados.

Schemaker no tiene dependencias externas más allá del TYPO3 Core y el paquete Fluid Template Engine. No interviene en el proceso de renderizado ni tiene impacto en el rendimiento del sitio en producción - la generación de esquemas se ejecuta exclusivamente en la CLI del entorno de desarrollo.

Problemas frecuentes y soluciones

El IDE no muestra autocompletado pese al XSD. La causa más frecuente: el namespace en la plantilla Fluid no coincide con el namespace del XSD. Schemaker genera esquemas basados en el namespace PHP de las clases ViewHelper. Si en la plantilla Fluid se usa un alias diferente, el IDE no encuentra la asignación. Solución: xmlns:custom="http://typo3.org/ns/Vendor/Extension/ViewHelpers" debe corresponder exactamente con el esquema generado.

El XSD generado no contiene todos los ViewHelpers. Schemaker solo encuentra ViewHelpers accesibles mediante Composer Autoloading. Extensiones instaladas solo en modo clásico (sin Composer) no se escanean completamente. Solución: migrar a instalación basada en Composer.

El esquema queda desactualizado tras cambios de código. Los archivos XSD no se actualizan automáticamente cuando cambian los parámetros de ViewHelper. Solución: integrar la generación de esquemas en la pipeline CI/CD.

Migración y compatibilidad de versiones

Schemaker fue desarrollado originalmente por Claus Due (equipo FluidTYPO3) y se mantuvo activamente hasta TYPO3 v9. Para v10 y v11 existen forks de la comunidad con funcionalidad limitada.

Para TYPO3 v12 y v13 se recomienda como alternativa el soporte integrado del plugin TYPO3 para PhpStorm, que lee información de ViewHelper directamente del código PHP sin necesidad de archivos XSD separados. El equipo Core de TYPO3 proporciona además esquemas XSD oficiales para los ViewHelper del Core.

Gosign asiste en la evaluación y migra flujos de trabajo de esquemas existentes a toolchains modernos. Esfuerzo típico: 4 a 8 horas por proyecto, incluyendo configuración de IDE para todos los desarrolladores del equipo y documentación de los namespaces de ViewHelper disponibles.