typo3db_legacy para TYPO3

Por que typo3db_legacy é um risco de segurança para cada extensão desde TYPO3 v12

TYPO3 substituiu completamente a abstração de banco de dados por Doctrine DBAL na versão 8. A antiga API via $GLOBALS['TYPO3_DB'] foi marcada como deprecated a partir da v9 e completamente removida desde a v12. Mesmo assim, na prática milhares de instalações TYPO3 rodam com extensões que ainda são baseadas na API legacy. typo3db_legacy mantém essas extensões funcionando ao simular a API antiga como camada de compatibilidade.

O problema: a extensão não é uma solução permanente, mas uma ponte. Cada nova versão TYPO3 aumenta o risco de que a própria camada de compatibilidade quebre. Quem hoje ainda usa typo3db_legacy enfrenta uma decisão clara - migrar ou arriscar o upgrade para v13.

Cenários típicos de uso

Extensões desenvolvidas internamente com acessos diretos ao banco de dados. Muitas agências escreveram entre 2012 e 2018 extensões que chamam diretamente $GLOBALS['TYPO3_DB']->exec_SELECTquery(). Em uma instalação típica de médio porte encontram-se 3 a 8 dessas extensões. Sem typo3db_legacy, elas falhariam com Fatal Errors após um update para v10+.

Extensões de terceiros sem mantenedor ativo. Extensões como versões antigas de addons tt_address, diretórios setoriais ou ferramentas de importação especializadas foram frequentemente mantidas por desenvolvedores solo. Se o mantenedor não está mais ativo, typo3db_legacy é a única opção para preservar a funcionalidade durante o upgrade.

Migração gradual de grandes instalações. Empresas com mais de 50 extensões não podem migrar tudo simultaneamente. typo3db_legacy permite uma abordagem gradual: primeiro realizar o upgrade do Core, depois converter extensão por extensão para Doctrine DBAL. A Gosign planeja essas migrações em sprints de 3 a 5 extensões, priorizadas por criticidade de negócio.

Arquitetura técnica

typo3db_legacy se registra como extensão TYPO3 e disponibiliza a classe DatabaseConnection que implementa os mesmos métodos da antiga API: exec_SELECTquery(), exec_INSERTquery(), exec_UPDATEquery(), exec_DELETEquery().

Internamente, a camada encaminha todas as chamadas para Doctrine DBAL. Isso funciona de forma confiável para queries padrão. Problemas surgem com funções MySQL diretas em queries, prepared statements no formato antigo, transaction handling e performance (cada query passa por uma camada de abstração adicional com 5-15% de overhead).

Aspecto arquitetural importante: typo3db_legacy foi concebido como medida temporária. O código deliberadamente não contém otimizações que o tornariam mais longevo. Não há caching de queries na camada de compatibilidade, sem integração de connection pooling.

Problemas frequentes e soluções

Extensão não funciona apesar do typo3db_legacy após o upgrade. A causa geralmente é que a extensão não usa apenas $GLOBALS['TYPO3_DB'], mas também outras APIs removidas. A solução requer análise completa do código da extensão. Um scan com o TYPO3 Extension Scanner fornece uma lista priorizada. A Gosign realiza tais scans como levantamento prévio - esforço típico: 2 a 4 horas por instalação.

Queries retornam resultados diferentes de antes do upgrade. Doctrine DBAL trata tipos mais rigorosamente que a antiga API baseada em mysqli. Um WHERE uid = '5' (string em vez de integer) pode levar a comportamento inesperado em edge cases. Solução: verificar tipos PHP corretos em todas as queries.

Queda de performance após instalação. Instalações com mais de 100.000 registros e queries frequentes sentem o overhead da dupla abstração de forma mensurável. Aqui só ajuda a migração completa para Doctrine DBAL com QueryBuilder.

Migração e compatibilidade de versões

typo3db_legacy era componente oficial do TYPO3 Core até a versão 9.5 LTS. Para TYPO3 v10 e v11 existia como pacote Composer separado. Para TYPO3 v12 LTS não existe mais release oficialmente suportado.

Para TYPO3 v13 nenhuma camada de compatibilidade é planejada ou realista. A camada de banco de dados mudou demais com o upgrade para Doctrine DBAL 4.0. Quem usa typo3db_legacy e quer fazer upgrade para v13 não escapa de uma migração completa.

O caminho de migração recomendado: cada chamada exec_SELECTquery() é reescrita para o Doctrine DBAL QueryBuilder. Uma extensão típica com 10 a 20 chamadas de query pode ser migrada em 4 a 8 horas. A Gosign usa análise de código automatizada que identifica todas as chamadas de API legacy e sugere código de migração. Para extensões complexas com queries construídas dinamicamente, o esforço sobe para 2 a 3 dias por extensão.