Atualizar a versão do PHP em uma aplicação existente não consiste apenas em alterar a imagem do contêiner ou a configuração do servidor. O runtime interage com o código, as extensões, as bibliotecas do Composer e os processos que executam tarefas agendadas ou trabalhos em segundo plano. Uma mudança pode afetar qualquer um desses componentes, mesmo que a aplicação pareça funcionar normalmente durante um teste manual.
A maneira de reduzir a incerteza é tratar a atualização como uma mudança de compatibilidade: inventariar o que é executado, procurar incompatibilidades, validar fluxos representativos e definir antecipadamente como decidir se o deploy continua ou é revertido. O objetivo é isolar o trabalho necessário para o novo runtime, não transformar a atualização em uma reescrita do produto.
O runtime faz parte da compatibilidade da aplicação
Uma versão do PHP determina qual sintaxe o interpretador aceita e como determinadas funções e tipos se comportam. Também estabelece quais versões de extensões e dependências podem ser instaladas. Por isso, o fato de o código ter funcionado no ambiente atual não demonstra que funcionará no novo: uma função, uma interface, um comportamento de tipos ou a disponibilidade de uma extensão podem mudar.
Convém distinguir três áreas: o código da aplicação, as dependências de terceiros e a configuração do ambiente. Se as três forem modificadas ao mesmo tempo, fica mais difícil atribuir a causa de uma falha. Uma atualização planejada separa essas mudanças sempre que possível e mantém explícito qual componente introduziu cada ajuste.
Faça o inventário do runtime, das dependências e dos processos
Antes de alterar qualquer coisa, registre o ambiente real de execução, não apenas o descrito pelo arquivo de configuração do projeto. Confira a versão do PHP nos contêineres ou servidores que atendem às solicitações e naqueles que executam tarefas agendadas, consumidores de filas e comandos de manutenção. Esses processos podem usar imagens, variáveis ou extensões diferentes.
- Runtime e extensões: identifique as extensões habilitadas, suas versões quando aplicável e as bibliotecas do sistema das quais dependem. Compare os requisitos de produção, CI e desenvolvimento.
- Dependências do Composer: revise o
composer.json, o arquivo de lock e as restrições de PHP declaradas pelos pacotes. Confira também as ferramentas de desenvolvimento, como analisadores e runners de testes. - Configuração: faça o inventário dos valores de
php.ini, dos limites de memória e tempo, da configuração de erros e dos ajustes específicos do servidor. Um novo runtime não garante que os parâmetros relevantes tenham sido preservados. - Trabalho fora das solicitações web: inclua cron, filas, comandos de console, importações, exportações e tarefas de longa duração. Um fluxo web correto não valida automaticamente esses processos.
- Integrações e dados: anote os serviços externos, os formatos trocados e as gravações em bancos de dados ou no armazenamento. Isso ajuda a identificar quais operações exigem atenção especial durante uma reversão.
O inventário pode ser uma lista mantida no repositório ou na documentação operacional, desde que permita comparar os ambientes e detectar discrepâncias. Um sintoma frequente de um inventário incompleto é o CI passar, mas um worker ou uma tarefa agendada falhar após o deploy.
Procure incompatibilidades com vários sinais
Comece pelas ferramentas automatizadas: revise as restrições de plataforma do Composer e execute uma verificação de dependências com a versão-alvo do PHP. Um conflito na resolução indica que algum pacote, inclusive as ferramentas de desenvolvimento, não declara compatibilidade com essa plataforma. Não é recomendável forçar a instalação para ocultar o conflito sem entender qual requisito está sendo contornado.
Complemente essa análise com ferramentas de análise estática e testes de estilo ou de compatibilidade disponíveis no projeto. Elas podem apontar usos suspeitos, APIs obsoletas ou padrões que merecem revisão, mas não demonstram, por si só, que toda a aplicação funciona. Da mesma forma, uma análise sem problemas não substitui a execução real: alguns erros só aparecem ao percorrer uma ramificação pouco usual ou ao carregar uma extensão.
Execute os testes com o runtime-alvo e as extensões esperadas em produção. Se a suíte for limitada, adicione verificações manuais ou automatizadas dos fluxos de maior impacto: autenticação, operações de gravação, cobranças, se houver, geração de documentos e integrações essenciais. Registre também erros e avisos; uma mudança que transforma um aviso em exceção pode interromper um fluxo antes que a suíte o detecte.
Organize o trabalho para isolar o risco
Uma sequência prática é começar confirmando a imagem ou configuração candidata e suas extensões; em seguida, resolver as restrições das dependências; e, por fim, corrigir o código e os ajustes que impeçam a execução dos testes. Mantenha cada grupo de mudanças fácil de revisar. Se uma biblioteca precisar ser atualizada, documente qual requisito exige a mudança e teste as áreas da aplicação que a utilizam.
Evite atualizar indiscriminadamente todas as dependências na mesma etapa. Uma atualização ampla pode ser necessária, mas aumenta o número de causas possíveis se surgir uma regressão. Se não for possível separá-la, registre quais pacotes mudaram e adicione testes direcionados às funcionalidades que dependem deles. Certifique-se também de que o arquivo de lock seja gerado e instalado de maneira consistente entre CI e produção.
A configuração deve refletir o destino real. Validar com uma extensão instalada apenas no CI produz um sinal enganoso; o mesmo ocorre se as tarefas em segundo plano continuarem sendo executadas com o runtime anterior. Compare as imagens, os comandos de inicialização, as variáveis e a configuração entre os ambientes de teste e de produção antes de atribuir um resultado ao código.
Valide em um ambiente representativo e defina os critérios de saída
O CI deve executar a instalação, a análise e os testes com o runtime-alvo, não apenas com o atual. Adicione jobs separados para outros runtimes somente se a aplicação precisar manter uma janela de compatibilidade; nesse caso, cada combinação suportada precisa de uma verificação explícita. Uma matriz de CI pode mostrar quais combinações são testadas, mas não cobre automaticamente as particularidades da produção.
Use um ambiente de pré-produção suficientemente parecido com o real para verificar a inicialização, os fluxos críticos, as integrações, as filas e as tarefas agendadas. Verifique logs, erros, tempos de resposta e consumo de recursos antes e depois. Defina antecipadamente qual comportamento interromperia o deploy, quem tomará essa decisão e por quanto tempo o sistema será observado. Os limites devem se basear nas necessidades e nos sinais disponíveis para a aplicação, não em valores genéricos.
Um critério de saída útil inclui: instalação reproduzível, suíte acordada com resultado positivo, fluxos críticos verificados, ausência de novos erros sem explicação e capacidade de operar os processos em segundo plano. Registre as exceções conhecidas e seus responsáveis. “Os testes passam” é insuficiente se o conjunto não cobre uma integração essencial ou se a equipe não sabe qual métrica deve monitorar.
Faça o deploy com uma reversão compatível com os dados
Se a arquitetura e a plataforma permitirem, exponha o novo runtime gradualmente: primeiro em um ambiente controlado e depois para uma parte do tráfego ou da capacidade de execução. A exposição gradual é uma estratégia de implantação, não uma divulgação de informações. Nem sempre é possível distribuir solicitações entre versões — por exemplo, se houver processos com estado ou diferenças no protocolo interno —; nesse caso, planeje uma transição coordenada e verifique explicitamente os consumidores e produtores de mensagens.
Antes do deploy, verifique se o código anterior pode voltar a ser executado em caso de falha. A reversão não consiste apenas em restaurar uma imagem: uma migração de banco de dados, um novo formato de mensagem ou uma gravação incompatível pode impedir que o runtime anterior leia os dados criados pelo novo. Prefira mudanças de esquema compatíveis em etapas: amplie primeiro, depois faça o deploy de código capaz de coexistir com as duas formas e retire o que é antigo quando não houver mais consumidores que precisem dele. Para cada etapa irreversível, defina uma recuperação específica e uma decisão de interrupção.
Durante o deploy, monitore erros da aplicação e do runtime, falhas de workers, atraso nas filas, tarefas agendadas e sinais de negócio relevantes. Se um critério de reversão for acionado, interrompa a expansão da mudança e siga o procedimento testado. Preserve os logs necessários para determinar a causa; reverter sem diagnosticar pode fazer a mesma falha reaparecer na tentativa seguinte.
Lista de verificação para decidir se está pronta
- O runtime e as extensões de todos os ambientes e processos foram identificados?
- As restrições do Composer e as ferramentas de desenvolvimento foram revisadas?
- As análises e os testes são executados com a configuração-alvo?
- Os fluxos críticos, as integrações, as filas e as tarefas agendadas foram testados?
- As diferenças entre CI, pré-produção e produção são conhecidas?
- Há sinais operacionais, responsáveis e critérios claros para continuar ou interromper?
- O código anterior consegue trabalhar com os dados e as mensagens que o novo produzirá?
- A reversão foi ensaiada e está claro quais mudanças não podem ser desfeitas automaticamente?
A decisão de atualizar a versão do PHP em uma aplicação existente é mais sólida quando a equipe consegue responder a essas perguntas com evidências. Se faltarem testes ou inventário, a próxima etapa não precisa ser uma reescrita: pode consistir em primeiro fechar essas lacunas e reduzir o tamanho da mudança. Assim, possíveis falhas são detectadas antes de afetar os usuários, e cada decisão de deploy tem um critério verificável.
