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 pública 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: ./typo3/cli_dispatch.phpsh extbase schema:generate <extension key> gera o arquivo XSD para os ViewHelpers de uma extensão. 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 gera o schema por chave de extensão e só encontra ViewHelpers na pasta Classes/ViewHelpers/ dessa extensão. ViewHelpers de outras extensões ficam no schema delas. Solução: rodar uma geração separada para cada extensão com ViewHelpers próprios.

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 mantido até o TYPO3 7.6; a última versão é a 3.2.0. Não há forks para TYPO3 v10 e v11; o mais recente no GitHub vai até o TYPO3 8.7.

Para TYPO3 v13, recomenda-se como alternativa o comando vendor/bin/typo3 fluid:schema:generate, que o Core traz desde a versão 13.2; ele gera arquivos XSD para todos os ViewHelpers do projeto. 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.