Substituir uma aplicação PHP legada não exige reescrevê-la de uma só vez. Uma substituição gradual permite transferir capacidades enquanto o negócio continua operando, mas só funciona quando se decide com precisão qual sistema atende a cada operação e qual tem autoridade sobre cada dado. Sem esses limites, as duas aplicações podem acabar executando regras diferentes, aceitando gravações incompatíveis e gerando resultados difíceis de reconciliar.
O objetivo não é manter duas implementações em paralelo indefinidamente. É transferir responsabilidades de forma controlada, verificar se a nova solução preserva o comportamento necessário e retirar dependências antigas quando houver evidências suficientes. Para isso, são necessárias fronteiras funcionais, observabilidade, uma única fonte de verdade por domínio de dados e critérios de avanço acordados pelas equipes de tecnologia e produto.
Por que duas aplicações em paralelo não são suficientes
Ter uma aplicação antiga e outra nova disponíveis não define uma migração. Se ambas aceitarem a mesma operação, poderão aplicar regras diferentes a validações, permissões, preços, estados ou efeitos colaterais. O problema costuma aparecer tarde: uma fatura é calculada de duas maneiras, uma notificação é enviada duas vezes ou uma mudança de estado não se reflete em todos os sistemas.
Uma substituição gradual de um sistema legado em PHP precisa descrever explicitamente qual capacidade está sendo transferida, quem recebe as solicitações e onde a autoridade sobre os dados é mantida. A fronteira deve ser funcional, não apenas uma lista de controllers ou tabelas. Uma capacidade como “gerenciar uma devolução” pode envolver autorização, atualização do estoque e reembolso; dividi-la sem entender essas dependências cria uma fronteira enganosa.
Antes de alterar o roteamento, documente o comportamento observável: entradas, saídas, erros relevantes, permissões, efeitos colaterais e dependências externas. Diferencie regras de negócio de detalhes acidentais da implementação. Nem todo comportamento histórico precisa ser preservado, mas qualquer mudança intencional deve ser aprovada e testada como tal, e não atribuída silenciosamente à migração.
Escolher uma primeira capacidade que possa ser verificada
A primeira candidata não precisa ser a menor nem a mais visível. Vale priorizar uma capacidade com limites compreensíveis, acoplamento razoável e resultado verificável. O valor operacional também importa: uma migração pode reduzir um risco, viabilizar mudanças frequentes ou melhorar uma parte que o negócio precisa evoluir.
- Acoplamento: identifique chamadas a outros módulos, acesso direto a tabelas compartilhadas, tarefas agendadas e dependências de estado global. Muitos vínculos não impedem a migração, mas aumentam o custo de definir a fronteira.
- Verificabilidade: confira se é possível formular casos representativos e observar o resultado sem depender de interpretações subjetivas.
- Impacto e reversibilidade: avalie o que acontece se a capacidade falhar e se é possível voltar à rota anterior sem perder dados nem repetir efeitos externos.
- Preparação operacional: confirme que há responsáveis, métricas e procedimentos para investigar discrepâncias antes de expor tráfego real.
Um inventário breve ajuda: capacidade, consumidores, dados lidos e modificados, efeitos externos, responsável de produto e responsável técnico. Se não for possível responder quem usa uma operação ou qual sistema atualiza um dado, primeiro é preciso melhorar o conhecimento do sistema; migrá-la imediatamente não reduz a incerteza.
Definir o roteamento e a autoridade sobre os dados
O roteador deve decidir explicitamente qual implementação atende a uma solicitação. Isso pode ser feito por uma camada de aplicação, um gateway ou uma decisão no ponto de entrada, dependendo da arquitetura. O importante é que o critério seja observável e consistente: por capacidade, cliente, operação ou uma coorte controlada. Evite permitir que duas rotas processem o mesmo pedido sem coordenação.
Em cada fronteira, atribua um proprietário a cada dado ou agregado. Se o novo sistema for responsável pelos pedidos, por exemplo, o antigo não deve continuar modificando-os diretamente por meio de acesso compartilhado às tabelas. Os demais componentes podem consultar uma interface definida ou receber alterações por meio de eventos, conforme as necessidades de consistência. Compartilhar um banco de dados pode ser uma etapa de transição, mas não equivale a compartilhar a autoridade.
A sincronização precisa declarar sua direção e finalidade. Uma cópia de leitura pode alimentar relatórios ou consumidores antigos; ela não deve se tornar acidentalmente uma segunda fonte autorizada de gravação. Se houver troca de eventos, defina identificadores, ordenação quando necessária, novas tentativas, deduplicação e tratamento de mensagens com falha. Esclareça também como os atrasos são detectados e quem resolve as divergências.
Evitar gravações duplas ambíguas
Gravar em dois sistemas durante uma solicitação parece uma forma simples de mantê-los alinhados, mas introduz falhas parciais: uma gravação pode ser concluída e a outra não. Repetir a solicitação pode duplicar uma operação. Sem uma estratégia de idempotência, reconciliação e tratamento de erros, não há uma transação única que garanta consistência entre aplicações independentes.
Priorize uma única autoridade de gravação para cada operação. Durante uma transição, o sistema proprietário pode publicar alterações para atualizar uma projeção ou cópia de compatibilidade. Em processos assíncronos, registre a alteração e sua mensagem de forma confiável dentro do mesmo limite transacional, quando a infraestrutura permitir, e projete consumidores idempotentes. Se uma restrição específica exigir gravação dupla, trate-a como uma exceção temporária: especifique a ordem, as falhas possíveis, a reconciliação e a data ou condição para eliminá-la.
Uma cópia de dados históricos também exige regras. Defina como o estado inicial será carregado, como as alterações concorrentes serão aplicadas e como o resultado será verificado antes da mudança de proprietário. Não presuma que uma importação bem-sucedida significa que as relações, os estados derivados e as permissões foram migrados por completo.
Comparar o comportamento sem duplicar efeitos
A comparação reduz o risco quando distingue cálculo de execução. Uma técnica consiste em enviar uma cópia da entrada à nova implementação em modo de observação e comparar sua resposta com a do sistema ativo, sem permitir que a cópia envie e-mails, processe cobranças, altere o estoque ou invoque outros efeitos externos. Essa execução deve usar dados e dependências controlados ou substituir os efeitos por adaptadores que apenas registrem a intenção.
Compare os resultados semanticamente: estados, valores, decisões e erros relevantes, não necessariamente a ordem dos campos ou as marcas temporais. Use casos representativos que incluam limites, dados incompletos, permissões e falhas de dependências. Adicione testes automatizados para regras críticas e mantenha exemplos anonimizados ou sintéticos quando os dados reais não forem adequados para avaliação.
A execução em sombra, por si só, não demonstra que o novo sistema possa operar. Ela pode não reproduzir latências, concorrência ou integrações reais, e uma diferença pode revelar tanto um defeito quanto uma regra antiga não documentada. Cada discrepância precisa de classificação, responsável e resolução: corrigir, aceitar uma mudança aprovada ou excluir o caso com uma justificativa verificável.
Instrumentar o avanço e preparar a reversão
Registre a rota escolhida, a versão da implementação, o identificador de correlação e o resultado de cada operação. Meça erros, latência, novas tentativas, atrasos de sincronização e discrepâncias, segmentados por capacidade. Evite registrar segredos ou dados pessoais desnecessários; defina controles de acesso e períodos de retenção para os registros.
Antes de aumentar a exposição, acorde limites de interrupção e defina quem pode interromper o avanço. Uma reversão nem sempre significa mudar o roteamento: se o novo sistema já aceitou gravações, voltar à aplicação antiga pode deixá-la sem o estado mais recente. O procedimento deve indicar o que fazer com operações em andamento, mensagens pendentes e dados gravados; ensaie-o em um ambiente adequado. A reversibilidade depende do estado e dos efeitos, não apenas de uma opção de configuração.
Desativar o sistema antigo com condições verificáveis
A desativação deve se basear em evidências, não em uma data isolada. Para uma capacidade, confirme que todas as rotas previstas chegam ao novo proprietário; que as operações críticas e seus casos de erro estão cobertos; que os consumidores e trabalhos agendados deixaram de depender do componente antigo; e que não há gravações diretas nem processos de reconciliação sem responsável.
Depois, observe o funcionamento durante um período acordado com as equipes de produto e operações, considerando a carga e os ciclos relevantes para essa capacidade. Verifique os dados pendentes, as cópias de compatibilidade e os requisitos de auditoria ou retenção antes de remover componentes. Atualize a documentação, os alertas e os procedimentos de suporte. Manter uma peça antiga “por precaução” também tem um custo: ela pode preservar permissões, vulnerabilidades e rotas de gravação que confundem a definição de propriedade.
Uma sequência prática é: delimitar a capacidade, atribuir autoridade sobre os dados, documentar o comportamento, preparar testes e observabilidade, carregar ou sincronizar os dados, comparar sem efeitos colaterais, direcionar uma exposição controlada, revisar os resultados e retirar dependências com aprovação explícita. Se uma etapa não tiver critérios de aceitação ou responsável, a migração ainda não está pronta para avançar.
