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

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

João Rizzon · 2026-11-12 · Painéis

---

## 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](https://docs.cpanel.net/whm/software/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:

- **Versão certa:** o módulo vai para o PHP escolhido, não para o PHP do sistema.
- **Rastreabilidade:** outra pessoa da equipe abre a mesma tela e vê o que está instalado em cada versão.
- **Menos erro de digitação:** você não precisa lembrar o caminho do binário `pecl` de cada versão.

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](https://docs.cpanel.net/whm/software/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:

```bash
# 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.

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

```bash
/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.

## Checklist reutilizável para a equipe

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

- Anotar a versão de PHP do domínio no MultiPHP Manager.
- Confirmar que o serviço por trás existe (Redis, Memcached ou MongoDB rodando) ou que a biblioteca de sistema está instalada (ImageMagick, libmemcached).
- Instalar o módulo PECL na versão anotada pela interface do WHM.
- Validar com `php -m` da versão.
- Validar com phpinfo na conta e apagar o arquivo.
- Reiniciar o PHP-FPM se o phpinfo não refletir a mudança.
- Registrar no documento do cliente: módulo, versão de PHP, data.
- 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.

