Schemaker para TYPO3

Por que documentação ausente de ViewHelper freia projetos TYPO3

Fluid ViewHelpers são a espinha dorsal de todo desenvolvimento de templates TYPO3. Mas assim que um projeto traz ViewHelpers próprios, começa o problema: nenhum desenvolvedor conhece todos os parâmetros, nenhuma IDE oferece autocompletar, e a documentação existe no máximo como comentário no código PHP. Schemaker resolve esse problema gerando automaticamente arquivos XSD Schema a partir de classes PHP. Esses schemas fornecem às IDEs as informações necessárias para autocompletar, validação e documentação inline diretamente no template Fluid.

Para equipes com mais de um desenvolvedor TYPO3, isso não é questão de conforto, mas de produtividade. Sem arquivos schema, cada desenvolvedor gasta diariamente 15 a 30 minutos consultando parâmetros de ViewHelper no código-fonte.

Cenários típicos de uso

Projetos enterprise com mais de 20 ViewHelpers próprios. Grandes instalações TYPO3 frequentemente trazem ViewHelpers especializados - para formatação de preço, verificações de permissão, chamadas de API ou lógica específica do setor. Sem Schemaker, cada novo desenvolvedor no projeto precisa ler o código-fonte para entender os parâmetros disponíveis. Com Schemaker, ele abre o template Fluid no PhpStorm ou VS Code e recebe sugestões imediatamente.

Desenvolvimento de extensões para o TER. Quem publica extensões que contêm ViewHelpers próprios pode incluir arquivos XSD gerados pelo Schemaker. Isso reduz consultas de suporte consideravelmente e melhora a experiência do desenvolvedor.

Onboarding de novos desenvolvedores. Em uma agência TYPO3, desenvolvedores alternam regularmente entre projetos. Schemas gerados pelo Schemaker funcionam como documentação viva: sempre atualizados, porque gerados diretamente do código. Em vez de 2 dias de familiarização, são 2 horas.

Arquitetura técnica

Schemaker analisa classes PHP que herdam de AbstractViewHelper. Lê as anotações @param, as chamadas registerArgument() e os DocBlocks das classes. A partir disso, gera arquivos XSD Schema (XML Schema Definition) associados ao namespace Fluid.

A integração funciona via CLI TYPO3: vendor/bin/typo3 schemaker:generate gera arquivos XSD para todos os namespaces de ViewHelper registrados. Os arquivos XSD gerados são colocados no projeto e em cada template Fluid o namespace é declarado com Schema-Location. A IDE lê o XSD e oferece autocompletar.

Schemaker não tem impacto de performance no site live - a geração de schema roda exclusivamente na CLI em contexto de desenvolvimento. Em ambientes produtivos, Schemaker nem precisa estar instalado; os arquivos XSD gerados são distribuídos via sistema de controle de versão (Git).

Problemas frequentes e soluções

IDE não mostra autocompletar apesar do XSD. Causa mais frequente: o namespace no template Fluid não corresponde ao namespace XSD. Schemaker gera schemas baseados no namespace PHP das classes ViewHelper. Solução: garantir que a declaração xmlns no template corresponda exatamente ao schema gerado.

XSD gerado não contém todos os ViewHelpers. Schemaker encontra apenas ViewHelpers acessíveis via Composer Autoloading. Extensões instaladas apenas via modo clássico (sem Composer) não são completamente escaneadas. Solução: migrar para instalação baseada em Composer.

Schema desatualizado após mudanças no código. Arquivos XSD não são atualizados automaticamente quando parâmetros de ViewHelper mudam. Solução: integrar geração de schema na pipeline CI/CD.

Migração e compatibilidade de versões

Schemaker foi originalmente desenvolvido por Claus Due (equipe FluidTYPO3) e foi ativamente mantido até TYPO3 v9. Para TYPO3 v10 e v11 existem forks da comunidade com funcionalidade limitada.

Para TYPO3 v12 e v13, recomenda-se como alternativa o suporte TYPO3 Plugin integrado no PhpStorm, que lê informações de ViewHelper diretamente do código PHP sem necessidade de arquivos XSD separados. A equipe do TYPO3 Core também fornece schemas XSD oficiais para os ViewHelpers Core.

A Gosign auxilia na avaliação e migra workflows de schema existentes para toolchains modernas. Esforço típico para a migração: 4 a 8 horas por projeto, incluindo configuração da IDE para todos os desenvolvedores da equipe.