# Como mudar a versão do PHP no cPanel sem derrubar o site

O procedimento reversível, apoiado na documentação oficial do cPanel: o que anotar antes, o que conferir depois e como voltar atrás sem improviso.

> a troca em si são 3 cliques no MultiPHP Manager do cPanel, mas o que evita o site fora do ar é o antes e o depois: inventário de versão, extensões, php.ini e .htaccess por domínio, teste em subdomínio e checklist de verificação nos 10 minutos seguintes.

João Rizzon · 2026-09-09 · Painéis

---

Trocar a versão do PHP é uma das poucas ações de painel que mudam o comportamento do site no request seguinte, sem propagação, sem cache de DNS e sem janela de tolerância. Você clica em Apply e a próxima requisição já roda no binário novo. Se um plugin do cliente chama uma função removida, o visitante vê erro 500 antes de você trocar de aba.

Este guia documenta o procedimento inteiro, incluindo a parte que quase nenhum tutorial cobre: o que anotar antes, o que verificar depois e como voltar atrás em menos de dois minutos. A referência de painel é a [documentação oficial do MultiPHP Manager do cPanel](https://docs.cpanel.net/cpanel/software/multiphp-manager-for-cpanel/).

Um aviso de honestidade, porque este texto não é um teste de laboratório: **não houve benchmark próprio para esta pauta**. Nenhum número aqui é medição da Napoleon. Os tempos citados (dois minutos para reverter, dez minutos de verificação) são estimativas de procedimento, úteis como janela de trabalho, não como dado.

## O que realmente quebra quando a versão muda

O PHP não é uma peça só. Ao selecionar outra versão para o domínio, você troca ao mesmo tempo três coisas que o site depende:

- **O binário e a linguagem.** Funções depreciadas viram fatal error, sintaxe antiga para de compilar, avisos que antes eram warning viram exceção.
- **O conjunto de extensões carregadas.** Cada versão instalada tem seu próprio conjunto de módulos. `imagick`, `soap`, `intl`, `zip`, `mysqli` podem estar habilitados na versão antiga e ausentes na nova. O código nem chega a rodar: o plugin morre no `class_exists()`.
- **O `php.ini` efetivo.** Limites como `memory_limit`, `max_execution_time`, `upload_max_filesize` e `post_max_size` são definidos por versão. Um `memory_limit` que você subiu para 512M meses atrás pode voltar ao padrão da versão nova, e o site fica lento ou trava só na importação de produtos.

O terceiro item é o mais traiçoeiro, porque não derruba o site na hora. Ele derruba na terça-feira, quando o cliente sobe um catálogo.

## O inventário que evita a ligação de emergência

Antes de mudar qualquer coisa, registre o estado atual em algum lugar fora do servidor (planilha, ticket interno, README do repositório do site). Se você atende vários clientes, padronize esse registro: é ele que transforma reversão em rotina em vez de improviso.

| O que anotar | Onde obter | Por que importa |
|---|---|---||
| Versão atual de cada domínio e subdomínio | cPanel > MultiPHP Manager, coluna de versão | Domínios do mesmo cPanel podem estar em versões diferentes; a reversão precisa saber qual era qual |
| Se o domínio herda o padrão do sistema | Mesma tela, opção de herança / System Default | Se herda, mudar o padrão do servidor muda o site sem você tocar no domínio |
| Extensões carregadas | `php -m` no binário da versão em uso, ou uma página com `phpinfo()` no próprio domínio | Lista de módulos que precisam existir na versão de destino |
| Diretivas customizadas | cPanel > MultiPHP INI Editor, no domínio | `memory_limit`, `max_execution_time`, `upload_max_filesize`, `max_input_vars` |
| Diretivas `php_value` / `php_flag` no `.htaccess` | Busca recursiva por essas duas diretivas em todos os `.htaccess` sob `~/public_html/`, incluindo subpastas (comando logo abaixo da tabela) | Sem `mod_php` carregado essas linhas derrubam o site; precisam migrar antes da troca |
| PHP-FPM ligado ou desligado no domínio | MultiPHP Manager, coluna PHP-FPM | Muda como o processo é reciclado e onde o log aparece |
| Versão do WordPress, PHP mínimo do tema e dos plugins críticos | Painel do WP, README dos plugins | Identifica antes qual plugin vai quebrar |

Se você tem SSH, o inventário sai em poucas linhas. Os binários por versão do EasyApache 4 ficam em caminhos separados (`/opt/cpanel/ea-phpXX/root/usr/bin/php`), e o `php` do PATH aponta para o padrão do sistema, que não é necessariamente o do domínio. Por isso vale rodar os comandos com o caminho completo da versão que o domínio usa hoje:

```bash
# versão que responde no shell (padrão do sistema, pode não ser a do domínio)
php -v

# extensões carregadas na versão que o domínio realmente usa
/opt/cpanel/ea-php81/root/usr/bin/php -m

# valores efetivos das diretivas que mais quebram
/opt/cpanel/ea-php81/root/usr/bin/php -i | grep -E "^(memory_limit|max_execution_time|upload_max_filesize|post_max_size|max_input_vars)"

# diretivas de PHP em QUALQUER .htaccess do site, inclusive de subpastas
grep -rnE "php_value|php_flag" ~/public_html/
```

O último comando é o mais importante do inventário e o que mais gente erra. Ele precisa ser recursivo sobre o **diretório** (`~/public_html/`), não sobre o arquivo `~/public_html/.htaccess`: instaladores, plugins de cache e sistemas legados costumam deixar um `.htaccess` próprio em `/wp-admin`, `/wp-content/uploads` ou em subpastas de aplicação, e é exatamente esse que ninguém lembra na hora do erro 500. Se quiser restringir só aos arquivos `.htaccess`, use `grep -rnE --include=".htaccess" "php_value|php_flag" ~/public_html/`.

Guarde a saída de `php -m` inteira. Comparar duas listas depois é trivial; reconstruir de memória qual extensão faltava, não.

Sem SSH, crie um arquivo temporário na raiz do site com `<?php phpinfo();`, abra pelo navegador, salve a página em PDF e **apague o arquivo em seguida**. Essa é, aliás, a leitura mais confiável, porque vem do mesmo handler que serve o domínio. Deixar `phpinfo()` público expõe caminhos, usuário do sistema e módulos para qualquer scanner. Sem shell, a varredura de `.htaccess` em subpastas fica manual: use o Gerenciador de Arquivos do cPanel com "Mostrar arquivos ocultos" ligado e percorra pelo menos a raiz, `/wp-admin` e `/wp-content`.

## Por que testar em subdomínio antes de tocar no site do cliente

O MultiPHP Manager permite definir a versão do PHP por domínio, incluindo subdomínios e domínios adicionais da mesma conta ([documentação do cPanel](https://docs.cpanel.net/cpanel/software/multiphp-manager-for-cpanel/)). Isso é o que torna o teste barato: você não precisa de outro plano nem de outro servidor.

O fluxo que funciona bem em agência:

### Crie o subdomínio de teste com raiz própria

Algo como `staging.dominio.com.br`, com raiz própria (`/home/usuario/staging`). Bloqueie indexação e acesso público (senha de diretório no cPanel resolve).

### Clone arquivos e banco para o staging

Primeiro o dump e os arquivos:

```bash
cd ~/public_html
wp db export /home/usuario/backup-pre-php.sql
cp -a ~/public_html/. ~/staging/
```

O dump `backup-pre-php.sql` vale por si só: é o seu ponto de retorno se algo além do PHP der errado.

Depois, e este é o passo que costuma sumir dos tutoriais, o clone precisa de banco próprio. Em cPanel > Bancos de Dados MySQL, crie um banco novo (`usuario_staging`), crie um usuário e conceda todos os privilégios a ele nesse banco. Só então importe o dump e ajuste a configuração:

```bash
cd ~/staging

# aponte o wp-config.php do clone para o banco novo antes de importar
# (DB_NAME, DB_USER, DB_PASSWORD)

wp db import /home/usuario/backup-pre-php.sql
wp search-replace 'https://dominio.com.br' 'https://staging.dominio.com.br' --skip-columns=guid
```

Confirme com `wp option get siteurl` dentro de `~/staging`: se ele responder o domínio de produção, o clone ainda está lendo o banco errado e qualquer teste a partir daí é perigoso.

### Mude a versão só do subdomínio

No MultiPHP Manager, selecione apenas `staging.dominio.com.br` e aplique a versão de destino. O domínio principal continua intocado.

### Exercite o que o cliente usa, não a home

Home carregando não prova nada. Percorra: login no wp-admin, envio de formulário de contato, checkout de teste no WooCommerce, upload de imagem na biblioteca de mídia, geração de PDF ou boleto se houver, e qualquer integração com API externa. É nessas rotas que moram `soap`, `intl`, `curl` e `openssl`.

## A troca no MultiPHP Manager, passo a passo

### Escolha a janela de troca

Fora do horário de pico do cliente. Para site institucional, começo da manhã. Para e-commerce, madrugada. Evite sexta à noite pela razão óbvia: se quebrar, quem repara é você no sábado.

### Selecione o domínio, não a conta inteira

Na tela do MultiPHP Manager, marque o checkbox do domínio específico, escolha a versão no seletor e confirme. Aplicar na conta inteira muda todos os domínios de uma vez, incluindo aquele sistema legado do cliente que ninguém lembrava que existia.

### Herdar o padrão do sistema ou fixar a versão

Se o domínio está configurado para herdar o padrão do sistema, ele acompanha mudanças futuras do servidor sem aviso. Fixar uma versão explícita dá previsibilidade; herdar dá atualização automática e risco. Para site de cliente com plugins comerciais, prefira a versão explícita e agende a revisão.

### Reaplique as diretivas do `php.ini` e limpe o `.htaccess`

Abra o **MultiPHP INI Editor**, selecione o domínio e confira se `memory_limit` e companhia estão nos valores que você anotou.

Se o site tinha diretivas `php_value` ou `php_flag` no `.htaccess`, resolva isso antes de aplicar, e resolva em **todos** os `.htaccess` que a busca recursiva encontrou, não só no da raiz. Em EA4, quando o domínio roda sob PHP-FPM ou suEXEC/CGI (ou seja, sem `mod_php` carregado), essas linhas não são ignoradas em silêncio: o Apache devolve **erro 500** com `Invalid command 'php_value'` no log, e o site inteiro cai, não apenas a função afetada. Um `php_value` esquecido dentro de `/wp-admin/.htaccess` derruba o painel mesmo com o front-end aparentemente saudável. Migre esses valores para o MultiPHP INI Editor ou para um `.user.ini` na raiz do site e remova as linhas do `.htaccess`.

## Checklist de verificação nos dez minutos seguintes

Não feche o navegador depois do Apply. Este é o roteiro:

| Verificação | Como testar | Sintoma de falha | Ação |
|---|---|---|---||
| Front-end responde | Abrir a home em aba anônima | Tela branca ou erro 500 | Reverter agora, investigar depois |
| wp-admin abre | `/wp-admin` com login real | Fatal error citando arquivo de plugin | Desativar o plugin por FTP/SSH ou reverter |
| Extensão ausente | `/opt/cpanel/ea-phpXX/root/usr/bin/php -m` no binário da versão de destino, ou `phpinfo()` temporário no domínio, comparado com a lista anotada | Plugin reclama de classe inexistente | Habilitar a extensão ou reverter |
| Log de erro do PHP | `tail -n 50 ~/public_html/error_log` | `Uncaught Error`, `Call to undefined function` | Identificar o arquivo culpado |
| Formulário e e-mail transacional | Enviar um teste real e conferir a caixa | Mensagem não chega | Ver se o plugin SMTP exige `openssl` |
| Cron do WordPress | `wp cron event list` | Eventos vencidos acumulando | Ver o cron do cPanel (abaixo) |
| Cron do sistema | cPanel > Cron Jobs | Job apontando para binário antigo | Corrigir o caminho |
| Upload e limites | Subir uma imagem grande na mídia | Erro de tamanho | Reaplicar diretivas no INI Editor |

Não use o `php -m` do PATH para essa comparação. Ele responde pelo padrão do sistema e pode listar módulos de uma versão que não é a do domínio, produzindo um falso negativo tranquilizador.

### O cron e o WP-CLI continuam no binário antigo

Mudar a versão no MultiPHP Manager afeta como o site é servido pelo servidor web. Um cron job configurado com caminho absoluto continua chamando exatamente o binário que você escreveu lá:

```bash
# exemplo fictício de cron que continua na versão antiga
/opt/cpanel/ea-php74/root/usr/bin/php -q /home/usuario/public_html/wp-cron.php
```

Esse job vai rodar em PHP 7.4 mesmo com o site em 8.x, e você terá dois comportamentos diferentes no mesmo site. Confira todos os cron jobs da conta e ajuste o caminho para o binário absoluto da versão nova, por exemplo `/opt/cpanel/ea-php82/root/usr/bin/php`. O symlink `/usr/local/bin/php` existe e funciona, mas ele segue o **padrão do sistema definido pelo servidor**, que pode mudar sem aviso numa manutenção da hospedagem, exatamente o tipo de surpresa que o item 3 recomenda evitar. Se optar por ele, saiba que está abrindo mão de previsibilidade em troca de conveniência.

O mesmo vale para o WP-CLI: `wp --info` mostra qual binário está em uso. Se ele diverge da versão do site, migrations e comandos de plugin podem se comportar de um jeito no shell e de outro no navegador. Para forçar a versão certa, chame o WP-CLI pelo binário completo: `/opt/cpanel/ea-php82/root/usr/bin/php ~/wp-cli.phar --info`.

### O e-mail que para de sair sem ninguém notar

E-mail transacional é a falha silenciosa clássica. O site continua no ar, o formulário mostra "mensagem enviada", e nada chega. As causas típicas depois de troca de versão são o plugin SMTP que precisa de `openssl` para TLS, uma biblioteca de envio que usa função depreciada, ou uma integração de API que quebra no `curl`. Teste enviando de verdade, para um endereço externo, e olhe também a pasta de spam.

## Como reverter em menos de dois minutos

A reversão é o mesmo caminho, invertido. Não tente diagnosticar com o site fora do ar.

- cPanel > MultiPHP Manager.
- Marcar o domínio afetado.
- Selecionar a versão anotada no inventário.
- Aplicar.
- Recarregar a home em aba anônima.

Se o site usa cache de página (plugin ou camada do servidor), limpe o cache depois de reverter, porque uma página de erro 500 pode ter sido armazenada. Se havia OPcache ativo e o comportamento continuar estranho, alternar o PHP-FPM do domínio força a reciclagem dos processos.

Se a reversão não resolve, o problema não era só a versão. Nesse caso o dump `backup-pre-php.sql` e a cópia dos arquivos entram em cena. É por isso que o passo do backup vem antes, e não depois.

### Depois de voltar, isole o plugin culpado

Com o site de novo no ar, volte ao subdomínio de teste. Coloque-o na versão nova e desative os plugins em bloco, reativando um a um até o erro reaparecer. É lento, é chato e é o único método que não depende de sorte. Anote o plugin problemático no registro do cliente: em geral ele reaparece em outros sites da mesma carteira.

## Frase pronta para explicar o incidente ao cliente

Quando o site fica fora do ar, o cliente quer três informações: o que aconteceu, se já voltou e o que impede a repetição. Uma versão que funciona, adapte ao seu tom:

> **** "Atualizamos a versão do PHP do servidor, que é o software que executa o site. Um plugin antigo não é compatível com a versão nova e o site apresentou erro por alguns minutos. Já revertemos para a configuração anterior e o site está normal. Vamos atualizar esse plugin em ambiente de teste e refazer a atualização depois, com validação prévia, porque a versão antiga do PHP deixa de receber correções de segurança."

A última oração importa: ela transforma um incidente em justificativa para o trabalho que vem a seguir, em vez de deixar a impressão de que mexer no PHP é opcional.

### Como transformar isso em processo repetível

Para quem mantém dezenas de sites, o ganho não está no procedimento em si, está em não reinventá-lo a cada cliente. Três hábitos que rendem:

- **Uma planilha única de versões.** Uma linha por domínio, com versão atual, data da última troca, plugins que já deram problema e se o domínio herda o padrão do sistema. Cinco minutos por site, uma vez.
- **Sempre um subdomínio de teste vivo.** Criar e destruir staging a cada atualização custa mais que mantê-lo protegido por senha o ano todo.
- **Auditoria de cron no mesmo dia da troca.** Caminho absoluto de binário é a pendência que ninguém lembra até o relatório mensal do cliente sair vazio.

E a regra que resume tudo: **só mude a versão de PHP quando você souber, sem consultar ninguém, qual era a versão anterior**. Se você não sabe, o problema não é a atualização. É o inventário.

