mask_export para TYPO3

Sem mask_export, elementos Mask não são versionáveis e cada deployment é um risco

Mask é o padrão 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 mask.json (ou config/mask.json desde Mask 8) 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) e opcionalmente TypoScript Setup para renderização frontend.

O processo de exportação roda como comando CLI TYPO3: php typo3/sysext/core/bin/typo3 mask:export. 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: integrar o comando mask_export em um hook Git (pre-commit) ou na pipeline CI.

Templates Fluid não são exportados junto. mask_export copia por padrão os templates do caminho configurado. Se templates ficam fora desse caminho, não são capturados. Solução: manter todos os templates Mask em um diretório unificado referenciado na configuração Mask.

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

mask_export acompanha o ciclo de release do Mask: quando Mask suporta uma nova versão TYPO3, mask_export é atualizado em breve. Atualmente TYPO3 v11, v12 e v13 são suportados.

Para projetos que desejam migrar para TYPO3 v13 com a API nativa Content Block, mask_export pode servir como etapa intermediária: 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 (integrar comando CLI na pipeline CI, criar repositório Git para a extensão exportada, ajustar configuração Composer) é de aproximadamente 2 a 4 horas. Depois disso, o workflow é completamente automatizado.