Análise estática em PHP legado: plano seguro de modernização

Introduzir análise estática em PHP legado não consiste em ativar o nível mais estrito de uma ferramenta e corrigir milhares de avisos. Numa aplicação com regras de negócio dispersas, dependências antigas e poucos testes, essa abordagem mistura defeitos potencialmente graves com dívida histórica, trava a equipa e pode induzir alterações inseguras.

O objetivo inicial é diferente: tornar cada nova modificação mais verificável, reduzir a incerteza nos fluxos importantes e dispor de um caminho explícito para tratar a dívida existente. A análise estática fornece informação estrutural sobre o código; a modernização exige também decisões de produto, testes e controlos de entrega.

Porque ativar todas as regras de uma vez costuma paralisar a manutenção

Um projeto legado pode acumular tipos implícitos, valores nulos não documentados, métodos com demasiadas responsabilidades, acesso direto a variáveis globais, código inalcançável e contratos ambíguos entre camadas. Se todo o repositório for analisado com regras estritas desde o primeiro dia, o resultado costuma ser uma lista demasiado extensa para priorizar.

O problema não é apenas o volume. Cada aviso exige contexto: uma chamada aparentemente incorreta pode estar protegida por uma condição externa, uma dependência pode usar anotações incompletas ou uma convenção local pode não estar representada no código. Corrigir sem compreender esse contexto pode alterar um comportamento de negócio que ninguém tinha documentado.

Também convém separar dois objetivos que frequentemente se confundem:

• Visibilidade: conhecer riscos e zonas com contratos incertos.
• Controlo de alterações: impedir que uma modificação introduza novos problemas detetáveis.
• Redução da dívida: eliminar incidências históricas de forma priorizada.

O segundo objetivo é o melhor ponto de partida. Permite melhorar a qualidade da entrega sem transformar a correção em massa num requisito prévio para continuar a desenvolver produto.

O que a análise estática deteta e que controlos não substitui

Um analisador pode inferir tipos, seguir chamadas, detetar argumentos incompatíveis, retornos impossíveis, propriedades não definidas, variáveis que podem ser nulas, ramos inalcançáveis e discrepâncias entre uma interface e a respetiva implementação. Também ajuda a localizar dependências acopladas, APIs usadas de forma inconsistente e limites de arquitetura violados quando são definidas regras para esse efeito.

Estes sinais são especialmente valiosos em refatorizações. Por exemplo, alterar um método para que devolva Customer|null permite encontrar consumidores que assumem sempre uma instância. O aviso não demonstra que exista um erro em produção, mas obriga a decidir o que deve acontecer quando não existe cliente.

No entanto, a análise não valida por si só uma regra como a de que uma encomenda só pode ser cancelada antes de ser faturada, que um desconto deve ser calculado de acordo com uma política comercial ou que uma integração externa responde dentro de um prazo aceitável. Também não observa permissões reais, migrações de dados, concorrência, desempenho nem configurações de produção.

Uma refatorização segura combina três perspetivas:

• Análise estática para verificar contratos e percursos de código.
• Testes automatizados para preservar comportamentos conhecidos, começando pelos fluxos críticos.
• Revisão funcional e observação para validar regras de negócio, efeitos externos e comportamento após o deploy.

Preparar o piloto antes de medir incidências

O primeiro âmbito deve ser um módulo de negócio delimitado, com alterações frequentes ou risco relevante, mas não o núcleo mais opaco de toda a aplicação. Um piloto útil tem responsáveis identificáveis e permite saber se as regras geram descobertas compreensíveis.

Antes de executar a análise, crie um inventário breve:

1. Rotas críticas: autenticação, pagamentos, encomendas, faturação, dados pessoais ou outras operações cuja falha tenha elevado impacto.
2. Entradas e saídas: controladores, comandos, consumidores de filas, APIs, ficheiros importados e tarefas agendadas.
3. Dependências: versão do PHP, pacotes abandonados, extensões, código gerado e bibliotecas sem informação de tipos.
4. Convenções atuais: uso de classes de valor, exceções, coleções, nulos, arrays associativos e acesso a dados.
5. Testes disponíveis: que cenários cobrem, que dados preparam e quais são os seus limites de confiança.

Este inventário evita interpretar cada aviso de forma isolada. Também permite decidir onde faz sentido adicionar tipos nativos e onde convém manter adaptadores em torno de uma dependência antiga para não propagar a sua ambiguidade por toda a aplicação.

Criar uma linha de base sem a transformar numa amnistia permanente

A linha de base regista as incidências já existentes para que a equipa possa exigir um padrão superior no código novo ou modificado. É uma ferramenta de transição, não uma declaração de que a dívida é aceitável.

Gere-a após rever uma amostra representativa de descobertas. Se o resultado contiver erros de configuração, caminhos que não deveriam ser analisados ou código de terceiros incluído por acidente, corrija-os primeiro. Uma linha de base inflacionada por ruído perde valor desde o início.

Para que seja útil, associe-a a regras operacionais:

• Não são adicionadas novas entradas à linha de base sem uma justificação passível de revisão.
• Uma incidência corrigida é removida da linha de base na mesma alteração.
• As entradas são revistas ao intervir no ficheiro ou módulo afetado.
• As exceções têm proprietário, motivo técnico e data ou condição de revisão.

É preferível registar uma supressão muito localizada com explicação do que ocultar uma categoria completa de erros. Se um aviso não puder ser resolvido porque uma biblioteca externa não expressa os seus contratos, encapsule essa biblioteca num adaptador tipado e limite a exceção a esse limite.

Classificar descobertas por risco e custo de decisão

Nem todos os diagnósticos justificam bloquear uma entrega. A classificação deve refletir o impacto potencial e o grau de certeza, não apenas a severidade atribuída por uma ferramenta.

Prioridade alta: contratos e dados críticos

Trate primeiro retornos incompatíveis, argumentos mal tipados em operações de negócio, possíveis acessos a nulos, valores não validados em limites externos e violações de contratos entre módulos. Costumam revelar defeitos que um teste insuficiente pode não percorrer.

Prioridade média: incerteza que amplia o âmbito

Os arrays sem forma conhecida, valores mistos que atravessam várias camadas e métodos que devolvem tipos demasiado amplos nem sempre causam uma falha imediata. Ainda assim, aumentam o custo de cada alteração. Convém resolvê-los ao tocar no fluxo, definindo objetos de transferência, classes de valor ou contratos explícitos quando fizer sentido.

Prioridade baixa: limpeza sem impacto demonstrado

Estilo, código redundante ou convenções internas podem melhorar a legibilidade, mas não devem competir com riscos de domínio nem com entregas urgentes. Agrupe-os em tarefas separadas ou aplique regras automáticas apenas quando a sua modificação for mecânica e verificável.

Ordem de intervenção: impedir nova dívida e proteger fluxos ativos

Uma sequência prática começa por executar a análise em integração contínua sobre as modificações propostas. O critério de bloqueio inicial pode ser simples: não introduzir erros novos fora da linha de base e não piorar o nível de um ficheiro modificado.

Depois, torne as regras mais rigorosas por diretório ou módulo. É habitual começar por código de domínio novo, serviços de aplicação e adaptadores recentes, mantendo critérios mais tolerantes nas camadas históricas de infraestrutura. Esta divisão não é uma desculpa para abandonar o legado: torna visível onde está o limite e permite deslocá-lo gradualmente.

Em cada alteração ativa, priorize um âmbito pequeno:

1. Adicione testes de caracterização para o comportamento que precisa de preservar.
2. Declare o contrato de entrada e saída mais relevante.
3. Corrija os avisos que afetam esse percurso.
4. Refatore em passos curtos e reveja diferenças funcionais.
5. Ative regras mais estritas quando o módulo puder suportá-las.

Os tipos e as anotações devem descrever conhecimento real. Declarar um tipo não nulo apenas para silenciar um aviso transfere o risco para o consumidor seguinte. Se um valor puder faltar por conceção, represente-o como tal e obrigue o código chamador a decidir como o tratar.

Integrar controlos na entrega contínua sem bloquear por ruído

O resultado da análise deve ser legível para quem abre uma alteração. Publique os novos erros, o ficheiro afetado, a regra e uma indicação do motivo pelo qual importa. Evite relatórios extensos sem responsável nem relação com a modificação efetuada.

Defina critérios proporcionais: os defeitos de contrato num fluxo crítico podem bloquear; uma melhoria cosmética pode tornar-se acompanhamento; um alerta incerto de uma dependência deve resultar num adaptador, numa configuração documentada ou numa exceção temporária. A revisão de código decide se a correção respeita a intenção de negócio; o analisador não substitui essa decisão.

Meça o progresso com indicadores que orientem decisões: incidências relevantes abertas por módulo, entradas de linha de base eliminadas, percentagem de alterações analisadas com regras exigentes, número de contratos ambíguos em rotas críticas e proporção de refatorizações cobertas por testes de caracterização. O objetivo não é chegar a zero avisos globais, mas reduzir o âmbito incerto das alterações.

Antipadrões que confundem limpeza com modernização

• Suprimir avisos sem motivo: elimina informação sem reduzir o risco que a originou.
• Perseguir zero descobertas: pode dedicar capacidade a detalhes irrelevantes enquanto os processos importantes continuam inseguros.
• Corrigir todos os ficheiros próximos: aumenta a dimensão da alteração e dificulta a revisão de regressões.
• Tipar dados desconhecidos como se fossem fiáveis: oculta a incerteza em vez de a modelar.
• Bloquear toda a entrega por regras novas: gera rejeição e leva a equipa a procurar exceções permanentes.

Lista de verificação para iniciar o piloto

• Escolher um módulo com responsável técnico, relevância de negócio e âmbito delimitado.
• Identificar as suas entradas, saídas, dependências e cenários críticos.
• Executar a análise, eliminar erros de configuração e rever uma amostra dos resultados.
• Criar uma linha de base limitada à dívida existente e definir quem a pode modificar.
• Bloquear incidências novas de alto risco em alterações do piloto.
• Adicionar testes de caracterização antes de refatorar percursos sensíveis.
• Rever semanalmente descobertas repetidas, exceções e regras que geram ruído.
• Tornar o padrão mais rigoroso apenas quando os resultados forem compreensíveis e acionáveis.

Com esta abordagem, a análise estática deixa de ser um relatório de defeitos herdados e torna-se um mecanismo de controlo: cada modificação contribui com contratos mais claros, menor incerteza e uma base mais segura para modernizar PHP de forma progressiva.