Microtemplate para TYPO3

O Fluid às vezes é exagero quando só é preciso preencher uma string com variáveis

Nem todo problema de template exige o motor Fluid completo. Se o assunto de um e-mail deve dizer “Olá, {name}, seu pedido #{orderNumber}” ou se um trecho no rodapé deve mostrar “Última atualização: {date}”, o Fluid, com ViewHelpers, layouts e partials, vira sobrecarga de arquitetura. Um motor de microtemplates só substitui variáveis em trechos de texto. Sem Fluid, sem caminho de objeto TypoScript, sem arquivo de template. Uma string com placeholders, um array com valores, pronto. Sob a chave de extensão microtemplate, porém, o TER traz outro produto: um template one-page da Brightside, atualmente na versão 6.0.0 para o TYPO3 14. Um motor de microtemplates com esse nome não está publicado lá.

O micro-templating é uma ferramenta de nicho para desenvolvedores que precisam de substituições simples de strings em extensões ou configurações TypoScript sem acionar o pipeline de renderização do Fluid. Para os redatores, ele não aparece: trabalha nos bastidores como utilitário. O campo de aplicação é propositalmente estreito. Onde o Fluid é a escolha certa para templates complexos, com laços, condições e herança, o micro-templating cobre o caso simples, em que uma string pronta precisa de um valor dinâmico em três pontos.

Os cenários típicos são textos de e-mail, trechos dinâmicos e templates de configuração

O cenário mais comum é a geração de textos de e-mail dentro de extensões. Uma extensão customizada envia e-mails de confirmação, e o assunto e o corpo devem ser configuráveis sem que o desenvolvedor precise criar templates Fluid. A extensão lê o texto de uma constante TypoScript (“Pedido #{orderNumber} confirmado”) e substitui os placeholders pelos valores atuais.

Segundo cenário: trechos de texto dinâmicos em configurações TypoScript. Um padrão de título de página como “{siteName} - {pageTitle} | {category}” é resolvido por micro-templating. Isso é mais simples do que um COA com vários objetos TEXT e funções stdWrap.

Terceiro cenário: templates de configuração para integrações com terceiros. Quando uma extensão torna configurável um endpoint de API (https://api.example.com/{version}/users/{userId}), o micro-templating pode substituir os placeholders antes da chamada à API. Isso é especialmente útil para extensões que atendem a vários ambientes de API (staging, produção) e querem manter a estrutura do endpoint na configuração TypoScript, e não no código.

Um quarto cenário, que aparece de vez em quando na prática: mensagens de log com formato estruturado. Uma extensão grava no log do TYPO3 “Importação de {count} registros de {source} concluída às {time}”. O micro-templating torna o texto do log configurável, sem que o desenvolvedor precise manter chamadas sprintf com argumentos posicionais.

A arquitetura técnica se resume a uma única classe PHP que substitui strings

Em essência, um motor de microtemplates é uma única classe PHP que executa str_replace ou preg_replace sobre uma string de template. Os placeholders seguem uma sintaxe configurável (padrão: {variableName}). Um array associativo fornece os valores. A classe não tem dependências além do tratamento de strings do próprio PHP.

A integração com o TYPO3 acontece por um serviço ou por um método estático, chamado a partir de outras extensões ou de configurações TypoScript. Não há plugin de frontend, módulo de backend nem elemento de conteúdo. O motor é pura infraestrutura para desenvolvedores.

O custo de performance é desprezível: um str_replace numa string de 500 caracteres com 5 variáveis leva menos de 0,01 ms. Para chegar ao mesmo resultado, o Fluid inicia um ciclo completo de renderização, com parsing do template, instanciação de ViewHelpers e caching, o que fica entre 1 e 5 ms. Num processo típico de renderização de página, essa diferença passa despercebida; em laços que geram 1.000 e-mails ou 500 entradas de log, a vantagem se torna mensurável.

Um motor desse tipo dispensa tabelas no banco de dados, módulos de backend e plugins de frontend; ele pode ser colocado como uma única classe em qualquer extensão própria.

Os problemas frequentes são a falta de escaping, conflitos de sintaxe e documentação escassa

Primeiro problema: não há escaping automático de HTML. Um motor de microtemplates substitui os placeholders 1:1, sem aplicar escaping ao valor inserido. Se um nome de usuário contém tags HTML (<script>alert('XSS')</script>), isso vai direto para a saída. A solução: aplicar escaping manual aos valores antes de inseri-los (htmlspecialchars) ou usar micro-templating apenas com dados internos, nunca com dados gerados por usuários.

Segundo problema: conflitos de sintaxe com o Fluid. Se placeholders de microtemplates ({variable}) forem usados num contexto em que o Fluid também renderiza, o Fluid tenta resolvê-los e lança um erro. A solução: usar outra sintaxe de placeholder (por exemplo, {{variable}} ou %variable%) ou garantir que a substituição rode antes do Fluid.

Terceiro problema: documentação escassa e pouco suporte da comunidade. Uma classe de microtemplates feita em casa ou herdada de projetos existentes não tem base de usuários: quando surge um problema, não há comunidade, issue tracker nem respostas no Stack Overflow. O desenvolvedor precisa ler o código-fonte para entender o comportamento. Na prática, cada desenvolvedor do time acaba usando a classe de um jeito diferente, porque nenhuma convenção está documentada.

Outro tema é o debugging. Quando um placeholder não é substituído porque a chave no array não coincide exatamente com o nome do placeholder (maiúsculas e minúsculas, espaços), uma substituição simples não emite nenhum aviso. O placeholder simplesmente fica no texto, e o desenvolvedor procura o erro no lugar errado. Por isso, um modo de debug que registre em log os placeholders não resolvidos deve fazer parte de qualquer implementação própria.

O micro-templating não precisa de extensão, o PHP já traz os meios

Um motor de microtemplates usa apenas funções padrão do PHP e, por isso, não depende de nenhuma versão do TYPO3; como não há versão publicada de um motor com esse nome, não dá para comprovar para quais versões ele estaria liberado. A questão, de qualquer forma, é se ele é necessário: o PHP oferece a mesma funcionalidade sem extensão com strtr() ou str_replace() e um array de substituições, algo possível muito antes do PHP 8.0; named arguments não ajudam aqui, porque o sprintf() só conhece marcadores posicionais. Para templates mais complexos, o Fluid continua sendo a melhor escolha apesar da sobrecarga, porque traz caching, escaping e herança de templates. A Gosign não usa extensões de microtemplates ativamente em projetos existentes e, em implementações novas, recomenda resolver a funcionalidade diretamente na própria extensão ou no TypoScript com stdWrap.