blog
Infraestrutura web

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.

JR · · 8 min de leitura · 1 tabela · 14 blocos de código

Resposta curta: 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.

Neste artigo
  1. Por que o PHP do shell não é o PHP que roda o site
  2. Como descobrir o caminho do binário de PHP que o domínio usa
  3. Por que o Drush vai no composer.json do projeto, e não em ~/bin
  4. Seis erros comuns do Drush em cPanel, a causa e o comando que confirma
  5. A sequência que destrava um /admin em tela branca
  6. Como voltar atrás no código e no banco depois de um update ruim
  7. Linha de cron no cPanel com caminho absoluto e log de erro
  8. O que coletar antes de abrir chamado, e o que resolve sem trocar de plano

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) 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.

# 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:

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.

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.

Como achar o PHP certo da conta cPanelVer versão do domínioMultiPHP Manager mostra o handlerLocalizar o binárioea-php ou alt-php, caminho absolutoChecar extensõespdo_mysql, gd, mbstring, curl, zipChecar limitesmemory_limit e disable_functionsFixar PHP na sessãoexport PATH e hash -r
Ordem de verificação antes de instalar o Drush. No cron, use sempre caminho absoluto.

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):

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:

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:

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

$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

$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:

$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

$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.

$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.

Ordem segura de update em produçãoDump do banco e filessql:dump com --gzip e tarLimpar cachedrush cr, truncar bins se falharVer updates pendentesdrush updatedb:status antes de aplicarAtualizar códigoComposer update drupal/core-*Aplicar e conferirupdb -y, cr, status
Sequência de atualização com plano de volta definido antes da execução.

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.

# 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:

$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.

$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:

Fonte consultada para o contexto de instalação do Drush em cPanel: 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.

Referências

  1. Documentação oficial (cpanel) — How to Install Drush. Consultado em 2026-10-08.
Leia também