k3n_dvemoji para TYPO3: Suporte a emoji e migração UTF-8mb4

Emojis como pontos de interrogação não são um problema de exibição, mas um erro de configuração de banco de dados

Quando no backend TYPO3 um editor insere um emoji e no frontend aparece um ponto de interrogação ou um quadrado vazio, o problema não está no navegador nem no TYPO3. Está no banco de dados MySQL ou MariaDB, configurado com o charset utf8 em vez de utf8mb4. A diferença: utf8 armazena no máximo 3 bytes por caractere, emojis precisam de 4 bytes. k3n_dvemoji é uma extensão TYPO3 que endereça esse problema estendendo a configuração do banco de dados com suporte UTF-8mb4. Desde TYPO3 v10, o Core está preparado para utf8mb4, então a extensão só é necessária em instalações mais antigas ou mal configuradas.

Para administradores TYPO3 e agências que mantêm instalações mais antigas, k3n_dvemoji é uma ferramenta de diagnóstico e correção ao mesmo tempo. A extensão identifica tabelas com charset incorreto e as converte.

Cenários típicos de uso envolvem instalações antigas, migrações e conteúdo internacional

O cenário mais frequente é uma instalação TYPO3 v8 ou v9 que roda há anos e cujo banco de dados ainda está configurado como utf8 (não utf8mb4). Estimadamente 30% de todas as instalações TYPO3 configuradas antes de 2018 têm esse problema, porque a rotina de instalação na época definia utf8 como padrão. Enquanto editores usam apenas caracteres latinos, não se percebe. Assim que um post de mídia social com emoji é incorporado no site ou um editor coloca um emoji em um título, a exibição quebra.

Segundo cenário: migrações de banco de dados entre servidores. Na mudança de um banco TYPO3 de um servidor antigo para um novo, o charset pode se perder por um comando mysqldump incorreto. Um dump com —default-character-set=utf8 em vez de utf8mb4 corta todos os caracteres de 4 bytes.

Terceiro cenário: sites internacionais com idiomas asiáticos. Caracteres chineses, japoneses e coreanos necessitam parcialmente de 4 bytes. Sem utf8mb4, caracteres individuais são exibidos de forma corrompida, o que em páginas de conteúdo CJK leva a texto ilegível.

Arquitetura técnica analisa e converte tabelas do banco de dados no nível de coluna

k3n_dvemoji trabalha em dois níveis: análise e conversão. No modo de análise, a extensão escaneia todas as tabelas TYPO3 e verifica o charset de cada coluna. O resultado é um relatório que mostra quais tabelas e colunas ainda estão em utf8 (3 bytes) em vez de utf8mb4 (4 bytes). Um sistema TYPO3 típico tem 100 a 300 tabelas, das quais frequentemente 20 a 50 têm charset incorreto.

No modo de conversão, a extensão gera ALTER TABLE statements para cada coluna afetada e os executa. Isso parece trivial, mas tem armadilhas: índices em colunas varchar com utf8mb4 podem exceder o comprimento máximo de índice do MySQL (767 bytes no InnoDB com formato antigo). A extensão verifica esses limites e adapta as definições de índice.

Adicionalmente, a configuração TYPO3 em LocalConfiguration.php deve declarar o charset utf8mb4: ['DB']['Connections']['Default']['charset'] = 'utf8mb4' e ['DB']['Connections']['Default']['tableoptions']['collate'] = 'utf8mb4_unicode_ci'.

Problemas frequentes são restrições de comprimento de índice, erros de backup e colunas inconsistentes

Problema um: restrição de comprimento de índice MySQL. No InnoDB com formato Compact antigo (padrão até MySQL 5.6), o comprimento máximo de índice é 767 bytes. Um varchar(255) com utf8mb4 precisa de 1.020 bytes de espaço de índice. A conversão falha com “Specified key was too long”. A solução: mudar ROW_FORMAT para DYNAMIC (padrão a partir do MySQL 5.7) ou reduzir o comprimento varchar nas colunas afetadas.

Problema dois: backup antes da conversão. Um ALTER TABLE em tabelas grandes (100.000+ linhas) trava a tabela e pode causar indisponibilidade em bancos de produção. A solução: realizar a conversão fora do horário comercial e criar um backup completo antes. Para tabelas grandes, recomenda-se pt-online-schema-change da Percona para conversão sem lock.

Problema três: colunas inconsistentes após conversão parcial. Se apenas partes do banco foram convertidas, JOINs entre colunas utf8 e utf8mb4 podem causar problemas de performance porque MySQL faz uma conversão de charset implícita. A Gosign verifica após cada conversão todas as tabelas quanto à consistência.

A partir do TYPO3 v10, a extensão é desnecessária se o banco de dados estiver corretamente configurado

TYPO3 v10 e todas as versões seguintes esperam utf8mb4 como charset padrão. Em uma nova instalação com v10 ou superior, o banco de dados é automaticamente configurado corretamente e k3n_dvemoji não é necessário. A extensão permanece relevante para instalações migradas de v7, v8 ou v9 para v12 ou v13 cujo banco nunca foi convertido. A Gosign resolve isso no âmbito de cada migração TYPO3 automaticamente: scan de banco assistido por IA, conversão completa e verificação de consistência como parte do processo padrão de upgrade.