# Mudar a versão do PHP no VPS sem painel em 4 etapas

Como achar o binário que o Apache ou o NGINX realmente usa, instalar a versão nova em paralelo e virar só o vhost daquele cliente, com rollback de um comando.

> num VPS sem painel, a versão que vale é a do pool PHP-FPM que o host virtual chama, não a que o `php -v` mostra. O processo tem 4 etapas: descobrir o socket no vhost, instalar a nova versão lado a lado com as extensões, trocar uma linha e provar por página de teste no document root.

João Rizzon · 2026-11-01 · Servidores

---

## O `php -v` responde pelo seu shell, não pelo site do cliente

Num VPS de imagem pronta (Ubuntu com LAMP, Debian com NGINX, imagem LiteSpeed, AlmaLinux com Apache) não existe MultiPHP Manager. E a primeira armadilha é sempre a mesma: você entra por SSH, roda `php -v`, lê `PHP 8.3.x` e informa ao cliente que está tudo certo. Está errado.

`php -v` mostra o binário CLI que está no seu `PATH`. Esse binário atende cron, WP-CLI e Composer. O site, em uma requisição HTTP, é servido por outra coisa: um pool do PHP-FPM, um módulo do Apache ou um processo `lsphp`. São instalações independentes, com `php.ini` independente e conjunto de extensões independente.

Na prática isso significa que um VPS pode ter o WP-CLI rodando em 8.3 enquanto o `wp-admin` do cliente roda em 7.4. E o 7.4 é o que quebra plugin, o que aparece no Site Health e o que o scanner de segurança do cliente aponta.

A regra para trabalhar: **a versão que vale é a do processo que o servidor web chama**. Todo o resto é curiosidade.

## Como descobrir qual PHP o vhost chama de verdade

Faça nesta ordem. Cada passo leva segundos e você só desce para o próximo se o anterior não deu resposta.

### Pergunte ao próprio site pelo cabeçalho HTTP

```
curl -sI https://exemplo.com.br/ | grep -i -E 'x-powered-by|server'
```

Se o `expose_php` estiver ligado, `X-Powered-By: PHP/8.1.2` já encerra a investigação. Muitos stacks removem esse cabeçalho, então a ausência não prova nada.

### Liste as versões instaladas e os sockets que estão de pé

```
ls /etc/php/            # Debian/Ubuntu: versões instaladas
systemctl list-units 'php*-fpm*' --no-pager
ls /run/php/*.sock
```

Em imagens LiteSpeed o equivalente são diretórios por versão, no padrão `/usr/local/lsws/lsphpXX/bin/lsphp`, conforme a [documentação das imagens LiteSpeed](https://docs.litespeedtech.com/shared/cloud/FAQ-PHP/).

### Leia o vhost daquele site, não a configuração global

```
grep -R -n -E 'fastcgi_pass|SetHandler|lsphp|php[0-9]' /etc/nginx/sites-enabled/ /etc/apache2/sites-enabled/ 2>/dev/null
```

É aqui que a resposta aparece em texto puro: um `fastcgi_pass unix:/run/php/php7.4-fpm.sock;` ou um `SetHandler "proxy:unix:/run/php/php7.4-fpm.sock|fcgi://localhost"`. Anote o caminho exato do socket. Ele é o endereço da versão antiga e será a única coisa que você vai trocar.

| Stack do VPS | Quem escolhe o PHP da requisição | Onde se troca a versão |
|---|---|---||
| NGINX + PHP-FPM | `fastcgi_pass` do `location ~ \.php$` | server block do site |
| Apache + PHP-FPM (proxy_fcgi) | `SetHandler ... proxy:unix:` | VirtualHost do site |
| Apache + mod_php | módulo carregado no servidor inteiro | `a2dismod`/`a2enmod`, afeta todos os sites |
| LiteSpeed/OpenLiteSpeed | handler externo `lsphp` | configuração do vhost |
| CLI, cron, WP-CLI | `PATH` / alternatives | independente do site |

A linha do `mod_php` é a que mais dói em VPS de agência: ela não é por site. Se o VPS hospeda cinco clientes com `mod_php`, trocar a versão troca para os cinco ao mesmo tempo. Nesse caso o trabalho real é migrar aquele vhost para PHP-FPM primeiro, e só depois escolher a versão. É mais serviço do que parece no orçamento, cobre por isso.

## Instalar a versão nova lado a lado com o site no ar

Nada de "atualizar o PHP". Você instala a nova versão ao lado da antiga, sem desligar nada. O site continua no ar na versão velha enquanto você prepara a nova.

Em Debian e Ubuntu o caminho padrão é o repositório mantido por Ondřej Surý; em RHEL, AlmaLinux e Rocky, o Remi. Ambos entregam pacotes versionados que convivem: `php8.2-fpm` não remove `php7.4-fpm`.

Depois de habilitar o repositório da sua distribuição:

```
# Debian/Ubuntu (exemplo com 8.2)
sudo apt install php8.2-fpm php8.2-mysql php8.2-curl php8.2-gd \
                 php8.2-mbstring php8.2-xml php8.2-zip php8.2-intl
sudo systemctl enable --now php8.2-fpm
```

O conjunto de extensões não se adivinha: copie o do que está rodando hoje.

```
php7.4 -m > /tmp/ext-74.txt
php8.2 -m > /tmp/ext-82.txt
diff /tmp/ext-74.txt /tmp/ext-82.txt
```

O `diff` é o seu checklist de instalação. Extensões que somem silenciosamente e quebram site de cliente: `intl` (WooCommerce e traduções), `imagick`, `soap` (integrações com ERP), `zip` (atualização de plugin), `bcmath` e `gmp` (gateways de pagamento). Se o site usa Redis ou Memcached como object cache, instale o pacote correspondente da nova versão antes da troca, senão o cache cai e o site fica lento no mesmo minuto em que você vira a chave.

Em imagens LiteSpeed, a lógica é a mesma: instalar o pacote `lsphpXX` da versão desejada e os módulos equivalentes, mantendo a versão anterior no disco, conforme a [FAQ de PHP das imagens LiteSpeed](https://docs.litespeedtech.com/shared/cloud/FAQ-PHP/).

### Um pool por site em vez de jogar todo mundo no `www`

Em VPS com mais de um cliente, não jogue todo mundo no pool `www` da nova versão. Copie `/etc/php/8.2/fpm/pool.d/www.conf` para `cliente.conf`, troque o nome do pool, o `user`/`group` e o caminho do socket (por exemplo `/run/php/cliente-8.2.sock`). Ganha isolamento de permissão, log separado e a possibilidade de reverter um site sem tocar nos outros.

## Trocar uma linha no vhost e recarregar sem derrubar conexão

A edição é de uma linha. Faça backup antes, sempre, porque é o arquivo que você vai restaurar às pressas se der errado.

```
sudo cp /etc/nginx/sites-available/exemplo.conf{,.bak-$(date +%F)}
```

NGINX, dentro do `server` do site:

```
location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    fastcgi_pass unix:/run/php/cliente-8.2.sock;
}
```

Apache, antes de qualquer coisa, garanta os módulos de proxy FastCGI. Sem `proxy_fcgi` o `configtest` pode passar e o site responder erro, bem no passo mais arriscado:

```
sudo a2enmod proxy proxy_fcgi setenvif
```

Se o vhost vinha de `mod_php`, desabilite o handler antigo para esse site (ou `sudo a2dismod php7.4`, lembrando que isso afeta todos os vhosts que ainda dependem dele). Feito isso, dentro do `<VirtualHost>`:

```
<FilesMatch \.php$>
    SetHandler "proxy:unix:/run/php/cliente-8.2.sock|fcgi://localhost"
</FilesMatch>
```

Valide a sintaxe antes de recarregar. Esse par de comandos evita derrubar todos os sites do VPS por causa de uma chave esquecida:

```
sudo nginx -t && sudo systemctl reload nginx
# ou
sudo apachectl configtest && sudo systemctl reload apache2
```

O `reload` não derruba conexão em andamento. Com o pool da versão nova já em execução desde o `enable --now`, virar o vhost é só reload do servidor web: a indisponibilidade tende a zero. Janela real só aparece se você precisar reiniciar o FPM, por exemplo depois de mexer no `php.ini` ou na configuração do pool.

## Provar a versão no document root do cliente e apagar o teste

Teste no document root do cliente, não no `/var/www/html` padrão. É a diferença entre provar e supor.

```
sudo -u www-data tee /var/www/exemplo/public_html/zz-check-9f3a.php >/dev/null <<'PHP'
<?php
header('Content-Type: text/plain');
echo PHP_VERSION, PHP_EOL;
echo php_sapi_name(), PHP_EOL;
echo php_ini_loaded_file(), PHP_EOL;
foreach (['mysqli','curl','gd','intl','mbstring','zip','imagick'] as $e) {
    echo $e, ': ', extension_loaded($e) ? 'ok' : 'FALTA', PHP_EOL;
}
PHP
```

Abra `https://exemplo.com.br/zz-check-9f3a.php`, leia, e apague o arquivo no mesmo minuto:

```
sudo rm /var/www/exemplo/public_html/zz-check-9f3a.php
```

Nome aleatório e remoção imediata não são frescura: arquivo de diagnóstico esquecido em raiz pública é item de relatório de pentest e vetor de fingerprint. O `php_ini_loaded_file()` entrega de brinde qual `php.ini` está valendo, o que resolve em segundos a dúvida de "editei o upload_max_filesize e não mudou nada".

Depois disso, confirme pelo lado do WordPress: **Ferramentas > Saúde do site > Informações > Servidor**. Se a tela do WordPress continuar mostrando a versão antiga, o cache de página ou de object cache está servindo conteúdo velho; limpe antes de desconfiar da configuração.

## Checklist de inventário, rollback e o que olhar no 502

O valor aqui não é fazer uma vez, é fazer em quinze VPS sem pensar. Padronize:

- Inventário: por VPS, uma linha com domínio, document root, socket atual, versão atual, versão alvo.
- Backup de arquivos e banco antes de tocar na configuração, com restauração testada.
- Instalar a nova versão e as extensões do `diff`, sem apontar nada ainda.
- Subir o pool por site e conferir que o socket existe em `/run/php/`.
- Clonar o vhost em staging ou subdomínio e apontar o clone primeiro.
- Virar o vhost de produção, `configtest`, `reload`.
- Página de teste, Site Health, carrinho/checkout/formulário, log de erro.
- Remover a página de teste e registrar no inventário a data da troca.
- Ajustar cron e WP-CLI para a mesma versão (`php8.2 /usr/local/bin/wp ...` ou `update-alternatives`), senão você fica com dois PHPs divergentes no mesmo site.

Rollback: restaurar o `.bak` do vhost, `configtest`, `reload`. Volta em menos tempo do que leva para explicar. Mantenha a versão antiga instalada por alguns dias; só remova o pacote quando o site estiver estável e você tiver acompanhado o log de erro.

Onde olhar quando quebrar:

```
sudo tail -f /var/log/php8.2-fpm.log /var/log/nginx/exemplo.error.log
```

Erro 502 logo após a troca quase sempre é socket errado ou permissão do socket, não incompatibilidade do código. Confirme que o caminho no vhost é idêntico ao `listen` do pool, incluindo o nome do arquivo.

## A frase que explica a troca para o cliente final

Use esta, adaptando a versão e o horário:

> **** "A versão do PHP que roda o seu site saiu do suporte oficial e não recebe mais correção de segurança. Vamos instalar a versão nova em paralelo, testar em cópia e virar a chave no dia X, entre 7h e 8h. A indisponibilidade prevista é de poucos segundos no momento da troca, e temos retorno imediato à configuração anterior caso algo apresente erro. Vocês não precisam fazer nada, só evitar publicar conteúdo nesse intervalo."

Funciona porque responde às três perguntas que o cliente faz: por que mexer, quanto tempo fica fora e o que acontece se der errado. Se o cliente pedir prova do fim de suporte, mostre o calendário oficial de versões suportadas da linguagem. É um argumento de terceiro, não seu, e isso encurta a conversa.

Uma observação contra o nosso próprio interesse comercial: se o site do cliente está lento e você espera que a troca de 7.4 para 8.2 resolva, meça antes. Versão nova melhora o tempo de CPU do PHP, mas não conserta consulta lenta no banco, plugin que faz requisição externa síncrona nem imagem de 4 MB na home. Troque a versão porque sem suporte não há correção de segurança. Ganho de desempenho, quando vier, é bônus, e você deve medi-lo no site em questão antes de prometer.

