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: ./typo3/cli_dispatch.phpsh extbase schema:generate <extension key> genera el archivo XSD para los ViewHelpers de una extensión.

Además del TYPO3 Core, Extbase y Fluid, Schemaker necesita la extensión vhs. 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 genera el esquema por clave de extensión y solo encuentra ViewHelpers en la carpeta Classes/ViewHelpers/ de esa extensión. Los ViewHelpers de otras extensiones van en su propio esquema. Solución: lanzar una generación propia para cada extensión con ViewHelpers propios.

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 hasta TYPO3 7.6; la última versión es la 3.2.0. No hay forks para v10 y v11; el más reciente en GitHub llega hasta TYPO3 8.7.

Para TYPO3 v13 se recomienda como alternativa el comando vendor/bin/typo3 fluid:schema:generate, que el Core incluye desde la versión 13.2; genera archivos XSD para todos los ViewHelpers del proyecto. 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.