# Drush na hospedagem compartilhada cPanel sem quebrar o site

Como invocar o binário ea-php ou alt-php certo, instalar o Drush via Composer sem estourar memória e rodar cr, updb e updates com backup e reversão.

> instale o Drush como dependência do projeto via Composer e invoque sempre o binário correto, do tipo /opt/cpanel/ea-php83/root/usr/bin/php vendor/bin/drush, em vez do php do shell. O PHP padrão do SSH raramente é o mesmo que roda o site.

João Rizzon · 2026-10-21 · Infraestrutura web

---

## Por que o PHP do shell não é o PHP que roda o site

Quando você entra por SSH numa conta cPanel e digita `php -v`, o que responde quase sempre é o binário padrão do sistema, em `/usr/bin/php`. O site, por outro lado, roda sob o handler configurado no MultiPHP Manager, que aponta para um pacote EasyApache 4 (`ea-php83`) ou CloudLinux alt-php (`alt-php83`). São instalações diferentes: extensões diferentes, `php.ini` diferente, `memory_limit` diferente.

O Drush lê a configuração do Drupal, abre conexão com o MySQL, carrega o container de serviços e executa hooks de update. Se o binário que invoca o Drush não tiver `pdo_mysql`, `gd`, `mbstring` ou a versão mínima que o `composer.json` do projeto exige, o erro vai aparecer em lugares que não têm nada a ver com a causa: `Class "PDO" not found`, `Drupal\Core\Database\DatabaseExceptionWrapper`, ou simplesmente um fatal silencioso. O `opcache` é caso à parte: ele é cache de bytecode, a ausência dele não impede o bootstrap do Drupal nem a execução do Drush, só deixa cada chamada mais lenta porque todo arquivo PHP é recompilado.

A documentação do cPanel sobre instalação do Drush ([docs.cpanel.net](https://docs.cpanel.net/knowledge-base/web-services/how-to-install-drush/)) trata o Drush como ferramenta de linha de comando instalada na conta do usuário, não como pacote do servidor. Isso é o ponto de partida: em conta compartilhada você não instala Drush globalmente, você instala dentro do projeto.

## Como descobrir o caminho do binário de PHP que o domínio usa

Antes de qualquer coisa, descubra três coisas: qual versão o site roda, onde está o binário dessa versão e se ele tem as extensões necessárias.

```bash
# 1. versão que o shell oferece por padrão
php -v
which php

# 2. binários disponíveis na conta (EasyApache 4)
ls -d /opt/cpanel/ea-php*/root/usr/bin/php

# 3. binários alt-php (servidores CloudLinux)
ls -d /opt/alt/php*/usr/bin/php
```

O caminho canônico de um pacote EasyApache 4 é `/opt/cpanel/ea-php83/root/usr/bin/php`. O do CloudLinux é `/opt/alt/php83/usr/bin/php`. Troque o `83` pela versão que o MultiPHP Manager mostra para o domínio.

Confirmado o caminho, verifique as extensões e os limites daquele binário específico, não do `php` genérico:

```bash
PHP=/opt/cpanel/ea-php83/root/usr/bin/php

$PHP -v
$PHP -m | grep -E 'pdo_mysql|gd|mbstring|opcache|json|curl|zip'
$PHP -i | grep -E '^(memory_limit|max_execution_time|disable_functions)'
```

Se `disable_functions` incluir `proc_open`, `proc_get_status` ou `putenv`, o Composer vai reclamar e o Drush pode falhar ao chamar subprocessos. Nesse caso, ajuste pelo `php.ini` da conta (MultiPHP INI Editor) ou peça o ajuste ao suporte, em vez de tentar contornar com código.

### Colocar o binário certo no PATH sem quebrar os outros sites da conta

Para não digitar o caminho inteiro em cada comando, coloque o binário certo no início do `PATH` da sessão. Evite colocar isso no `.bashrc` sem pensar: se a conta hospeda mais de um site em versões diferentes de PHP, um `PATH` global vira armadilha. E o `PATH` da sessão não vale para o cron, que roda com ambiente próprio: lá o caminho absoluto é obrigatório.

```bash
export PATH=/opt/cpanel/ea-php83/root/usr/bin:$PATH
hash -r
php -v   # agora deve responder 8.3.x
```

`hash -r` limpa o cache de caminhos do bash. Sem ele, o shell continua chamando o binário antigo mesmo com o `PATH` novo.

## Por que o Drush vai no composer.json do projeto, e não em ~/bin

Drush moderno é uma dependência Composer do site, versionada junto com o Drupal. Instalar global em `~/bin` dá conflito assim que você mantém dois sites em versões diferentes do Drupal.

Dentro da raiz do projeto (onde está o `composer.json`, normalmente um nível acima de `public_html` ou `web`):

```bash
PHP=/opt/cpanel/ea-php83/root/usr/bin/php

$PHP -d memory_limit=-1 /usr/local/bin/composer require drush/drush
```

Três detalhes que resolvem a maioria das falhas aqui:

- **Chamar o Composer pelo PHP certo.** `composer require` sozinho usa o shebang do script, que aponta para o PHP padrão. Ao escrever `$PHP ... composer`, você força o interpretador.
- **`-d memory_limit=-1`.** O resolvedor de dependências do Composer é guloso em projetos Drupal, com dezenas de pacotes e restrições cruzadas. É o override padrão para o erro `Allowed memory size ... exhausted`. O limite vale só para aquele processo, não altera o `php.ini` do site.
- **Localizar o Composer.** Se `which composer` não retorna nada, baixe o `composer.phar` para a conta e chame `$PHP composer.phar require drush/drush`.

Se a conta tiver limite de processos ou o `require` morrer sem mensagem, rode com `--prefer-dist -vvv` para ver em que pacote travou. Atenção: `--no-dev` não é opção válida de `composer require`, o Composer 2 aborta com erro de opção desconhecida antes de resolver qualquer coisa. Essa flag só existe em `install` e `update`. Se quiser manter os pacotes de `require-dev` fora do vendor, faça em duas etapas: `$PHP -d memory_limit=-1 /usr/local/bin/composer require drush/drush --no-update` para só gravar a restrição no `composer.json` e depois `$PHP -d memory_limit=-1 /usr/local/bin/composer update drush/drush --with-all-dependencies --no-dev` para resolver e baixar. Em último caso, resolva as dependências numa máquina local e suba o `composer.lock`, executando no servidor apenas `composer install --no-dev`.

### Rodar drush status e ler o que ele diz sobre o banco

O binário fica em `vendor/bin/drush`. Como ele também tem shebang para o PHP padrão, invoque pelo caminho completo do interpretador:

```bash
cd ~/meusite
$PHP vendor/bin/drush status
```

`drush status` é o teste de fumaça: ele mostra a versão do Drupal, o caminho da raiz, o banco conectado e o diretório de arquivos. Se o campo `Database` aparecer vazio ou como `Not connected`, o problema é credencial em `settings.php` ou extensão PDO faltando no binário escolhido, não o Drush.

## Seis erros comuns do Drush em cPanel, a causa e o comando que confirma

| Sintoma no terminal | Causa provável | Como confirmar |
|---|---|---||
| `PHP Parse error: syntax error, unexpected '?'` | binário de PHP antigo demais para o código do Drupal | `$PHP -v` e comparar com o exigido no `composer.json` |
| `Class "PDO" not found` | binário sem `pdo_mysql` | rodar `$PHP -m` e procurar `pdo_mysql` na saída |
| `Allowed memory size exhausted` no Composer | `memory_limit` do CLI | repetir com `-d memory_limit=-1` |
| `proc_open(): Function is disabled` | `disable_functions` no `php.ini` da conta | rodar `$PHP -i` e procurar `disable_functions` na saída |
| `The Drupal root directory could not be found` | comando rodado fora da raiz do projeto | `pwd` e checar onde está o `composer.json` |
| `Drush command terminated abnormally` | OOM do processo ou timeout do shell | repetir com `--debug` e ver a última etapa registrada |

## A sequência que destrava um /admin em tela branca

Com o `/admin` em tela branca ou erro 500, a ordem importa. Faça backup antes de qualquer um deles.

### Dump do banco e dos arquivos antes de qualquer update

```bash
$PHP vendor/bin/drush sql:dump --result-file=$HOME/backup-$(date +%F).sql --gzip
tar czf $HOME/files-$(date +%F).tar.gz web/sites/default/files
```

Sem dump, `updb` não tem volta. Hooks de update escrevem no banco e não são reversíveis por comando. Use `$HOME` e não `~` depois do `=`: o bash só expande o til em atribuição de variável, então `--result-file=~/backup.sql` cria um diretório literal chamado `~` dentro do diretório atual.

### Quando o drush cr não basta e você precisa truncar as tabelas de cache

```bash
$PHP vendor/bin/drush cr
```

`cr` (cache:rebuild) reconstrói o container de serviços e os caches de render, rota e plugin. Boa parte das telas brancas depois de ativar ou remover um módulo cai aqui. Se `cr` falhar por o próprio container estar corrompido, apague os bins de cache direto no banco e repita:

```bash
$PHP vendor/bin/drush sql:query "TRUNCATE TABLE cache_bootstrap;"
$PHP vendor/bin/drush sql:query "TRUNCATE TABLE cache_container;"
$PHP vendor/bin/drush cr
```

### Conferir os updates pendentes antes de rodar o updb

```bash
$PHP vendor/bin/drush updatedb:status
$PHP vendor/bin/drush updb -y
$PHP vendor/bin/drush cr
```

`updatedb:status` lista o que está pendente antes de executar. Leia a lista: se aparecer update de um módulo contribuído que você não sabia que estava desatualizado, pare e verifique a versão do código antes de aplicar.

### Quem atualiza o código é o Composer, não o Drush

Em Drupal moderno, quem atualiza código é o Composer. O Drush entra depois, para aplicar os updates de banco. O alvo é o glob `"drupal/core-*"`, entre aspas para o shell não tentar expandir: `drupal/core-recommended` sozinho deixa `drupal/core-composer-scaffold` e `drupal/core-project-message` presos na versão anterior, o que trava a resolução ou roda o scaffold antigo por cima de `index.php` e `.htaccess`. Se o Composer não estiver no PATH como `/usr/local/bin/composer`, troque pelo `composer.phar` que você baixou na conta.

```bash
$PHP -d memory_limit=-1 /usr/local/bin/composer update "drupal/core-*" \
  --with-all-dependencies
$PHP vendor/bin/drush updb -y
$PHP vendor/bin/drush cr
$PHP vendor/bin/drush status
```

`pm:update` e amigos foram removidos ou reduzidos nas versões recentes do Drush justamente porque duplicavam o papel do Composer. Se o seu projeto ainda não é gerenciado por Composer, migrar para Composer é um projeto à parte, e tentar atualizar por outro caminho em produção costuma terminar em restore.

## Como voltar atrás no código e no banco depois de um update ruim

Defina o plano de volta antes de executar, não depois. O `$PHP` não procura script no `PATH`: sem caminho absoluto, `$PHP composer` responde `Could not open input file: composer`. Se o Composer não estiver em `/usr/local/bin/composer`, troque pelo `composer.phar` baixado na conta.

```bash
# código: volta ao estado travado pelo lock anterior
git checkout composer.json composer.lock
$PHP -d memory_limit=-1 /usr/local/bin/composer install --no-dev

# banco: restaura o dump feito no passo 1
gunzip -c $HOME/backup-2026-10-08.sql.gz | \
  $PHP vendor/bin/drush sql:cli

$PHP vendor/bin/drush cr
```

A restauração do banco desfaz também o conteúdo criado entre o dump e o rollback. Em site com tráfego de escrita, coloque o site em manutenção antes da janela:

```bash
$PHP vendor/bin/drush state:set system.maintenance_mode 1 --input-format=integer
$PHP vendor/bin/drush cr
# ... updates ...
$PHP vendor/bin/drush state:set system.maintenance_mode 0 --input-format=integer
$PHP vendor/bin/drush cr
```

## Linha de cron no cPanel com caminho absoluto e log de erro

O cron do cPanel roda num ambiente ainda mais enxuto que o do seu SSH: sem `.bashrc`, sem `PATH` customizado. Escreva o caminho absoluto dos dois binários, do PHP e do Drush, e redirecione a saída.

```
*/15 * * * * /opt/cpanel/ea-php83/root/usr/bin/php /home/usuario/meusite/vendor/bin/drush --root=/home/usuario/meusite/web core:cron >> /home/usuario/logs/drush-cron.log 2>&1
```

O `--root` evita depender do diretório de trabalho do cron. O `2>&1` manda o stderr para o mesmo arquivo: sem isso, o erro vai para o e-mail do cron ou para lugar nenhum. Se usar cron do Drupal, desative o cron automático na interface (`Automated Cron`) para não duplicar execução.

## O que coletar antes de abrir chamado, e o que resolve sem trocar de plano

Se algo falhar, junte esta saída antes de pedir ajuda. Ela normalmente já contém a resposta.

```bash
$PHP -v
$PHP -m | sort | tr '\n' ' '
$PHP -i | grep -E '^(memory_limit|disable_functions)'
cd ~/meusite && $PHP vendor/bin/drush status
$PHP vendor/bin/drush updatedb:status
```

Três observações que economizam tempo e, às vezes, dispensam troca de plano:

- Erro de memória no Composer quase nunca é falta de RAM no servidor, é `memory_limit` do CLI. Teste com `-d memory_limit=-1` antes de considerar outra coisa.
- Tela branca no `/admin` com `drush status` respondendo normalmente indica problema de PHP do web handler ou de módulo, não de banco. Olhe o log de erro do domínio.
- `drush cr` resolve muito, mas se o site volta a quebrar minutos depois, o problema é código, não cache. Repetir `cr` em loop só esconde o sintoma.

Fonte consultada para o contexto de instalação do Drush em cPanel: [How to Install Drush](https://docs.cpanel.net/knowledge-base/web-services/how-to-install-drush/), documentação oficial do cPanel, consultada em 08/10/2026. Os comandos de Composer e Drush acima refletem a documentação oficial de cada ferramenta; os caminhos com nome de usuário e datas são exemplos, troque pelos seus.

