typo3db_legacy para TYPO3

Por que typo3db_legacy é apenas uma ponte para cada extensão

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 na v8 e removida do Core desde a v9. 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 deveria planejar a migração, embora a versão 1.3.0 ainda chegue até o TYPO3 v14.

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 v9+.

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 monta strings SQL e as envia por uma conexão mysqli própria; o Doctrine DBAL apenas abre essa conexão. Isso funciona de forma confiável para queries padrão. Problemas surgem com outros bancos além de MySQL e MariaDB, porque a camada só usa mysqli, com prepared statements, que geram um aviso de deprecation a cada uso, com transaction handling, porque a API antiga usa uma segunda conexão, e com performance (assim que uma query antiga roda, a camada abre uma segunda conexão com o banco).

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. A própria camada envia as queries sem alterações via mysqli, mas os erros de tipo do código antigo continuam. 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 a segunda conexão com o banco que a camada abre. Aqui só ajuda a migração completa para Doctrine DBAL com QueryBuilder.

Migração e compatibilidade de versões

O código de typo3db_legacy fez parte do TYPO3 Core até a versão 8.7 LTS. Desde o TYPO3 v9 existe como extensão separada. A Friends of TYPO3 continua mantendo a extensão: a versão 1.2.0 suporta TYPO3 v10 a v12 e a 1.3.0, v12 a v14.

Também no TYPO3 v13 a camada continua funcionando. A camada de banco de dados do Core passou para o Doctrine DBAL 4.0, mas a camada legacy fala diretamente com o mysqli. Quem usa typo3db_legacy ainda assim não escapa, a longo prazo, 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.