mask_export para TYPO3

Sem mask_export, elementos Mask dependem do Mask e cada deployment é um risco

Mask é um dos frameworks mais usados para Custom Content Elements no TYPO3. Mas Mask armazena sua configuração em um arquivo JSON e gera campos de banco de dados em tempo de execução. Em um processo de desenvolvimento profissional com múltiplos ambientes (local, staging, produção), isso cria um problema: como levar novos elementos de conteúdo da máquina de desenvolvimento para o servidor produtivo? Recriando manualmente no backend? Copiando a mask.json via FTP e executando Database Compare? Ambas as opções são suscetíveis a erros e não são reproduzíveis.

mask_export resolve esse problema. A extensão exporta todas as definições Mask como extensão TYPO3 independente com ext_tables.sql próprio, configurações TCA e templates Fluid. Essa extensão é instalada via Composer, versionada via Git e implantada via CI/CD - exatamente como qualquer outra extensão TYPO3. Assim, Mask torna-se pronto para uso empresarial.

Cenários típicos de uso

Agências com pipeline CI/CD. Agências que implantam projetos TYPO3 via GitLab CI, GitHub Actions ou Deployer precisam de artefatos versionáveis. mask_export gera uma extensão instalável via composer require. Cada alteração em um elemento de conteúdo gera um novo commit que passa pela pipeline: lint, testes, deploy staging, deploy produção. Nenhuma intervenção manual no backend necessária.

Projetos multi-site com elementos compartilhados. Corporações com 5 a 20 instâncias TYPO3 (filiais nacionais, marcas, subsidiárias) querem elementos de conteúdo uniformes em todos os sites. mask_export gera uma extensão central incorporada em todas as instâncias. Alterações são feitas uma vez e distribuídas para todos os sites. Sem mask_export, elementos Mask teriam que ser recriados manualmente em cada instância.

Transferência entre desenvolvimento e redação. Desenvolvedores definem elementos de conteúdo no sistema local, exportam via mask_export e fazem commit do resultado. Editores trabalham no sistema staging ou produtivo e utilizam os elementos sem precisar da GUI do Mask. A extensão Mask pode até ser desinstalada em sistemas produtivos, se apenas a extensão exportada for necessária.

Arquitetura técnica

mask_export lê a configuração do Mask no caminho definido no Mask e gera uma extensão TYPO3 completa. A estrutura gerada contém: ext_emconf.php (metadados da extensão), ext_tables.sql (definições de banco de dados para todos os campos Mask), Configuration/TCA/Overrides/tt_content.php (configuração TCA), Resources/Private/Templates/ (templates Fluid, gerados a partir da configuração dos campos) e TypoScript Setup para renderização frontend.

A exportação é feita no módulo de backend do mask_export, não existe comando CLI: lá a extensão é baixada como ZIP ou instalada diretamente. Importante: mask_export exporta apenas a definição (campos, templates, TCA), não os conteúdos (textos, imagens em tt_content). Os dados permanecem no banco de dados e são migrados independentemente.

Problemas frequentes e soluções

Exportação esquecida após alteração. Um desenvolvedor altera um campo Mask no sistema local, mas faz commit apenas da mask.json, não da nova exportação. No staging falta a configuração TCA. Solução: refazer a exportação no módulo de backend após cada alteração e fazer commit dela junto com a mask.json.

Templates Fluid não são exportados junto. mask_export não aproveita os templates próprios, mas gera para cada elemento um template de exemplo a partir da configuração dos campos. Por isso os templates próprios ficam fora da exportação, estejam onde estiverem. Solução: colocar os templates próprios em um site package, como recomenda o README do mask_export, e integrá-los pela constante TypoScript templateRootPath da extensão exportada.

Conflitos no uso simultâneo de Mask e extensão exportada. Se no sistema produtivo tanto Mask quanto a extensão exportada estão instalados, podem ocorrer registros TCA duplicados. Solução: em sistemas onde editores não criam novos elementos, instalar apenas a extensão exportada e desinstalar Mask.

Migração e compatibilidade de versões

Desde maio de 2022 não saiu nenhuma versão nova do mask_export: a última, 4.0.2, suporta o Mask até a 7.x, e não há nenhuma para o Mask 8 ou 9. São suportados apenas TYPO3 v9.5 a v11.5; para TYPO3 v12 e v13 não há versão.

Para projetos que desejam migrar para TYPO3 v13 ou v14 com a extensão Content Blocks, mask_export pode servir como etapa intermediária antes do upgrade: primeiro exportar elementos Mask (estrutura limpa baseada em arquivos), depois traduzir as configurações TCA exportadas em definições Content Block. O esforço por elemento é baixo (30 a 60 minutos) quando a extensão exportada serve como referência.

Uma vantagem frequentemente negligenciada do mask_export é a testabilidade. Quando elementos de conteúdo existem como extensão independente, é possível escrever testes automatizados: verificar configuração TCA, testar renderização de templates, validar esquema de banco de dados. Em uma pipeline CI, esses testes capturam erros antes de chegarem ao staging ou produção.

Para projetos com mais de 20 elementos Mask, a Gosign recomenda incorporar o processo de exportação no workflow de desenvolvimento desde o início. O esforço de setup inicial (configurar a pipeline CI para a extensão exportada, criar repositório Git para a extensão exportada, ajustar configuração Composer) é de aproximadamente 2 a 4 horas. Depois disso, cada alteração no Mask, uma vez exportada no módulo de backend, segue para o deploy sem outros passos manuais.