blog
Painéis

Como instalar Redis e Imagick por PECL no PHP do WHM

Como instalar o módulo PECL na versão exata de PHP do EasyApache 4, provar que o site do cliente carregou a extensão e evitar que ela suma quando a versão muda.

JR · · 6 min de leitura · 1 tabela · 3 blocos de código

Resposta curta: pelo WHM, selecione a versão exata do EasyApache 4 (ex.: ea-php82) no instalador de módulos PECL, instale redis, imagick, memcached ou mongodb e confirme com phpinfo na conta. O módulo pertence à versão: ao trocar o PHP do site, instale de novo na nova.

Neste artigo
  1. Por que o pecl no terminal pode instalar no PHP errado
  2. O que cada extensão precisa antes de instalar
  3. Instalando pelo WHM, versão por versão
  4. Confirmando o módulo na conta do cliente com phpinfo
  5. O que acontece quando a versão de PHP muda
  6. Checklist reutilizável para a equipe
  7. Como explicar ao cliente por que a troca de PHP leva um passo a mais

Por que o pecl no terminal pode instalar no PHP errado

Quem administra um servidor com WHM costuma ter mais de uma versão de PHP instalada pelo EasyApache 4, e cada conta de cliente pode estar em uma versão diferente pelo MultiPHP Manager. Rodar pecl install redis no terminal sem pensar instala o módulo no PHP que estiver primeiro no PATH. Esse PHP corresponde à versão padrão do sistema, que pode não ser a versão configurada para o domínio do cliente.

O WHM tem uma interface para isso, documentada pela cPanel em PHP Extensions and Applications Package. Nela você escolhe a versão de PHP do EasyApache 4 antes de instalar o módulo PECL. O resultado é a extensão compilada contra aquela versão específica, com a configuração registrada no lugar que aquela versão lê.

Três motivos práticos para preferir a interface:

Este guia não traz medição própria. Ele se apoia na documentação oficial citada e organiza o processo para quem mantém vários servidores ou vários sites.

O que cada extensão precisa antes de instalar

Redis, Memcached, MongoDB e Imagick são extensões cliente. Elas permitem que o PHP converse com um serviço ou com uma biblioteca, mas não instalam esse serviço. Ignorar essa diferença gera retrabalho: a extensão aparece no phpinfo e o site continua sem cache porque o servidor Redis nunca foi iniciado.

Extensão PECL O que ela faz O que precisa existir além dela
redis Cliente PHP para servidor Redis Um servidor Redis acessível (local ou remoto)
memcached Cliente PHP para Memcached Biblioteca libmemcached no sistema e um servidor Memcached rodando
mongodb Driver PHP para MongoDB Um servidor MongoDB acessível; a biblioteca PHP do projeto costuma vir pelo Composer
imagick Manipulação de imagem via ImageMagick Biblioteca ImageMagick e seus arquivos de desenvolvimento no sistema

Se a biblioteca de sistema estiver faltando, a compilação PECL falha, seja pela interface do WHM ou pelo terminal. A mensagem de erro na saída da instalação costuma citar o cabeçalho ou a biblioteca ausente. Instale a dependência pelo gerenciador de pacotes do sistema e repita.

Instalando pelo WHM, versão por versão

O fluxo descrito na documentação da cPanel é o mesmo para qualquer módulo PECL.

Descubra qual versão de PHP o site usa

No WHM, abra o MultiPHP Manager e localize o domínio do cliente. Anote a versão (por exemplo, ea-php82). Se a conta herda a versão padrão do sistema, anote a padrão. Se o módulo for instalado em outra versão, o site do cliente não vai enxergá-lo.

Como abrir o instalador de módulos PECL no WHM

Na área Software do WHM, acesse a interface de módulos PHP descrita em PHP Extensions and Applications Package. Escolha a opção de PECL e selecione, no menu de versões, exatamente a versão anotada no passo anterior.

Como instalar o módulo e ler a saída da compilação

Digite o nome do módulo (redis, imagick, memcached ou mongodb) e instale. A tela mostra a saída da compilação. Leia o final dela: uma linha de sucesso indica que o módulo foi construído; um erro de compilação indica dependência de sistema faltando.

Por que cada versão de PHP precisa do seu próprio módulo

Se você tem sites em ea-php81 e ea-php82, são duas instalações. O módulo instalado em uma versão não aparece na outra.

Para quem prefere terminal, o equivalente é chamar o pecl da própria versão do EasyApache 4, não o do sistema:

# exemplo: instalar redis no PHP 8.2 do EasyApache 4
/opt/cpanel/ea-php82/root/usr/bin/pecl install redis

# conferir se a versão carregou o módulo
/opt/cpanel/ea-php82/root/usr/bin/php -m | grep -i redis

O segundo comando valida pelo PHP de linha de comando daquela versão. Isso confirma que a extensão foi carregada, mas o site roda via PHP-FPM ou outro handler, então a confirmação final é a da próxima seção.

Ordem de instalação de módulo PECL pelo WHMAnotar versão do domínioMultiPHP ManagerInstalar pelo WHMMesma versão anotadaValidar com php -mVersão de CLI corretaValidar com phpinfoDentro da conta do cliente
Sequência para instalar um módulo PECL na versão certa.

Confirmando o módulo na conta do cliente com phpinfo

O php -m no terminal não prova que o site enxerga a extensão. A prova é um phpinfo executado dentro da conta, pelo mesmo handler que serve o site.

Crie um arquivo temporário na raiz do site, com nome difícil de adivinhar:

<?php phpinfo();

Salve como, por exemplo, info-7k2q.php, acesse pelo navegador e use a busca da página para procurar redis, imagick, memcached ou mongodb. Cada extensão carregada tem um bloco próprio com a versão do módulo. Confira também, no topo, a linha da versão de PHP: ela precisa bater com a versão onde você instalou.

Apague o arquivo logo depois. phpinfo exposto revela caminhos, versões e variáveis de ambiente.

Se a extensão aparece no php -m mas não no phpinfo do site, o processo PHP-FPM daquela versão provavelmente ainda está com a configuração antiga em memória. Reinicie o serviço:

/scripts/restartsrv_apache_php_fpm

Depois recarregue o phpinfo. Se continuar ausente, confira de novo no MultiPHP Manager se o domínio está mesmo na versão onde o módulo foi instalado.

O que acontece quando a versão de PHP muda

Extensão PECL pertence a uma versão de PHP, não à conta. Isso gera três situações que vale prever.

Troca de versão no MultiPHP Manager. Você ou o cliente muda o domínio de ea-php81 para ea-php82. Se o módulo só existe na 8.1, o site passa a rodar sem ele na hora. Com cache de objeto Redis, o plugin costuma cair para modo sem cache ou exibir erro de conexão; com Imagick, o WordPress volta a usar GD e a qualidade ou os formatos suportados mudam.

Nova versão instalada pelo EasyApache 4. Uma versão recém-adicionada não herda os módulos PECL das outras. Ela começa limpa e precisa de instalação própria.

Remoção de versão. Ao remover uma versão de PHP do EasyApache 4, os módulos daquela versão deixam de existir junto com ela. Se reinstalar a versão depois, reinstale os módulos.

Regra prática: antes de trocar a versão de qualquer site, liste os módulos PECL que ele usa e instale todos na versão de destino. Só então troque. Assim a migração não tem janela sem extensão.

Antes de trocar a versão de PHP do siteListar módulos PECL que o site usaInstalar na versão de destinoValidar com php -m e phpinfoTrocar a versão no MultiPHP Manager
Ordem que evita o site ficar um momento sem a extensão.

Checklist reutilizável para a equipe

Use esta sequência em cada servidor ou cada pedido de cliente:

  1. Anotar a versão de PHP do domínio no MultiPHP Manager.
  2. Confirmar que o serviço por trás existe (Redis, Memcached ou MongoDB rodando) ou que a biblioteca de sistema está instalada (ImageMagick, libmemcached).
  3. Instalar o módulo PECL na versão anotada pela interface do WHM.
  4. Validar com php -m da versão.
  5. Validar com phpinfo na conta e apagar o arquivo.
  6. Reiniciar o PHP-FPM se o phpinfo não refletir a mudança.
  7. Registrar no documento do cliente: módulo, versão de PHP, data.
  8. Antes de qualquer troca de versão, repetir na versão nova a instalação do módulo, as duas validações (php -m e phpinfo) e o reinício do PHP-FPM, se necessário.

O registro no documento do cliente economiza tempo meses depois, quando alguém pergunta por que o cache parou após uma atualização.

Como explicar ao cliente por que a troca de PHP leva um passo a mais

O cliente não precisa saber o que é PECL. Ele precisa entender por que a troca de PHP exige um passo a mais. Uma frase que funciona:

"A extensão de cache do seu site é instalada separadamente para cada versão do PHP. Antes de atualizarmos a versão, instalamos a extensão na versão nova e testamos, para o site não ficar nenhum momento sem ela."

Se o cliente está em hospedagem compartilhada sem acesso ao WHM, o caminho é pedir ao provedor que instale o módulo na versão usada pelo site, informando o nome exato da extensão e a versão de PHP. Em muitos casos isso resolve sem mudar de plano.

Referências

  1. Documentação oficial (cpanel) — PHP Extensions and Applications Package. Consultado em 2026-10-13.
Leia também