# Ativar imap, intl, soap ou zip no cPanel na versão certa

A caixa marcada no Select PHP Version só vale para a versão que está aberta ali. Se o domínio roda outra, nada muda. Como descobrir a versão efetiva, ativar no lugar certo e padronizar isso em toda a carteira de sites.

> são cinco passos: confirmar a versão efetiva do domínio no MultiPHP Manager, checar se um AddHandler no .htaccess sobrepõe a escolha, marcar a extensão no Select PHP Version dessa mesma versão, validar em um phpinfo.php temporário e apagá-lo, e esperar o PHP-FPM reciclar.

João Rizzon · 2026-09-20 · Painéis

---

## Por que o aviso continua depois de você marcar a caixa

O roteiro clássico é esse: o instalador do ERP, o plugin de nota fiscal ou o próprio WordPress reclama que falta `imap`, `intl`, `soap` ou `zip`. Você abre o **Select PHP Version**, marca a extensão, salva, recarrega a página do cliente e o aviso continua igual.

Na maioria das vezes não é bug nem cache. É que a conta do cPanel tem uma versão de PHP considerada padrão e cada domínio pode estar rodando outra. O **Select PHP Version** edita as extensões da versão que está selecionada naquela tela. O site, enquanto isso, é atendido por um processo PHP de outra versão, que carrega um `php.ini` diferente e uma lista de módulos diferente. Você ligou o recurso, só que no lugar errado.

A lógica do EasyApache 4 ajuda a entender: cada versão de PHP é um conjunto separado de pacotes, instalado lado a lado. A [documentação do cPanel sobre o módulo imap](https://docs.cpanel.net/ea4/php/php-module-imap/) trata o módulo como um pacote por versão de PHP, não como um recurso único do servidor. Ter `imap` na 8.1 não diz nada sobre a 8.2.

## Roteiro para acertar a versão antes de marcar qualquer coisa

### Descobrir qual versão de PHP o domínio executa agora

No cPanel, abra **MultiPHP Manager**. A tabela lista os domínios e subdomínios da conta com a versão de PHP de cada um. Anote a versão da linha do domínio que está dando problema, não a da conta.

Dois detalhes que custam tempo quando passam despercebidos:

- Subdomínio e domínio addon aparecem como linhas próprias e podem ter versão diferente do domínio principal.
- Quando a linha mostra algo como "inherit" ou "herdado", o domínio segue a versão padrão da conta. Se alguém mudar o padrão depois, esse domínio muda junto, e o conjunto de extensões vai junto com a versão.

### Conferir se um AddHandler no .htaccess sobrepõe o painel

Se o MultiPHP Manager diz 8.2 e o site se comporta como se fosse 7.4, procure um handler antigo no `.htaccess` da pasta do site. É comum sobrar de migração ou de tutorial velho:

```apache
# exemplo de linha que sobrepõe a escolha do painel
AddHandler application/x-httpd-ea-php74 .php .php7 .phtml
```

O caminho prático é abrir o Gerenciador de Arquivos, ativar a exibição de arquivos ocultos e procurar por `AddHandler` ou `AddType` no `.htaccess` da raiz do domínio e da pasta onde fica o sistema. Se achar, comente a linha com `#`, salve e recarregue. Guarde o arquivo original antes de mexer, porque o mesmo `.htaccess` costuma carregar regras de cache e de redirecionamento que você não quer perder.

Vale checar também a pasta da aplicação, e não só a raiz. Um `.htaccess` dentro de `/public_html/loja` vale para aquela pasta e pode apontar para outra versão.

### Marcar a extensão no Select PHP Version, na mesma versão

Abra **Select PHP Version**. A tela mostra a versão atual e a lista de extensões com caixas de seleção. Antes de marcar qualquer coisa, confirme que a versão exibida é exatamente a que você anotou no passo 1. Se não for, troque ali e só depois marque `imap`, `intl`, `soap` ou `zip`.

Dois cuidados: trocar a versão nessa tela pode alterar o PHP da conta, o que não é o que você quer se o problema é de um domínio só. Nesse caso, ajuste primeiro a versão do domínio pelo MultiPHP Manager e volte ao Select PHP Version já com a versão certa carregada. E salve a seleção de extensões antes de sair da página.

### Validar com um phpinfo.php temporário e apagar o arquivo

Não confie no aviso do sistema para dizer se deu certo, porque muitos instaladores guardam o resultado da checagem em cache. Crie um arquivo na pasta pública do domínio, de preferência com nome não óbvio:

```php
<?php
// apagar depois de conferir
phpinfo();
```

Abra `https://dominio.com.br/z-check-9f2.php` e olhe três coisas, nessa ordem:

- O número da versão no topo. Tem que bater com o que você configurou.
- O campo **Loaded Configuration File**. Ele mostra o caminho do `php.ini` que aquele processo carregou de fato. O caminho costuma trazer a versão no nome, e é a prova de qual PHP está atendendo o vhost.
- O bloco da extensão. Use a busca do navegador por `imap`, `intl`, `soap` ou `zip`. Se a extensão está carregada, existe um bloco com o nome dela e uma tabela de diretivas. Se só aparece o nome dentro de outro texto, não conta.

Apague o arquivo assim que terminar. Um `phpinfo()` esquecido expõe caminhos absolutos, versões e módulos do servidor para qualquer um.

Se você tem acesso SSH, dá para conferir pelo binário da versão, mas com uma ressalva importante: rodar `php -m` puro consulta o PHP de linha de comando, que quase nunca é o mesmo que atende o site. Chame o binário da versão explicitamente:

```bash
/opt/cpanel/ea-php82/root/usr/bin/php -m | grep -i -E 'imap|intl|soap|zip'
```

Ainda assim, o `phpinfo.php` pela web é a validação que mais vale, porque é a única que percorre o mesmo caminho que a requisição do cliente.

### Esperar o PHP-FPM reciclar quando a extensão não aparece

Quando o domínio roda com PHP-FPM, os processos já em memória continuam com a configuração antiga até reciclarem. O sintoma é característico: você salvou tudo certo, o `phpinfo.php` ainda mostra a lista antiga, e alguns minutos depois passa a mostrar a nova sem que ninguém faça nada.

O que fazer, em ordem de menor impacto:

- Esperar e recarregar o `phpinfo.php` com cache desligado (Ctrl+F5).
- No MultiPHP Manager, desligar e religar o PHP-FPM do domínio. Isso reescreve o pool e reinicia os processos daquele vhost.
- Se nada mudar, pedir ao suporte do provedor que reinicie o serviço PHP-FPM da versão em questão. Em revenda você não tem WHM com esse nível de acesso.

## O que imap, intl, soap e zip quebram quando faltam

| Extensão | Serve para | Sintoma típico quando falta |
|---|---|---||
| `imap` | Ler caixas de e-mail por IMAP ou POP3 dentro do PHP | Helpdesk que importa e-mail em ticket, formulário que valida caixa, sistema que lê pedido por e-mail |
| `intl` | Formatação e comparação de texto, data e número por localidade | Instalador de framework recusa continuar, erro `Class "NumberFormatter" not found`, plugin de tradução ou de marketplace falha |
| `soap` | Consumir e expor web services SOAP | Integração com prefeitura, correios, transportadora e ERP legado, erro `Class "SoapClient" not found` |
| `zip` | Ler e gravar arquivos .zip | Atualização e instalação de plugin e tema no WordPress, backup, importação de planilha .xlsx |

O `zip` e o `intl` são os que mais aparecem em checagem de instalador. O `soap` é quase sempre integração fiscal. O `imap` é o caso à parte: ele deixou de ser distribuído junto com o núcleo do PHP a partir da versão 8.4 e passou a viver no PECL, conforme a [lista de extensões removidas no PHP 8.4](https://www.php.net/manual/en/migration84.removed-exts.php). Nas versões anteriores ele continua existindo, mas sempre dependendo de o provedor ter instalado o pacote daquela versão específica. Se o cliente depende de `imap`, confirme a disponibilidade na versão de destino antes de subir o PHP, não depois.

## Quando a extensão nem aparece na lista do Select PHP Version

Acontece. Você abre o Select PHP Version na versão certa e a caixa não existe. Isso significa que o pacote daquele módulo não está instalado no servidor para aquela versão de PHP. Nenhuma configuração dentro do cPanel resolve, porque a instalação acontece no WHM, pelo EasyApache 4, que é onde os módulos são adicionados por versão, conforme a [documentação do cPanel](https://docs.cpanel.net/ea4/php/php-module-imap/).

Duas saídas, nessa ordem:

- **Pedir ao provedor.** Abra chamado dizendo exatamente: domínio, versão de PHP usada por ele, nome do módulo. Uma linha resolve: "o domínio exemplo.com.br roda ea-php82 e preciso do módulo `soap` habilitado nessa versão". Quanto mais específico o pedido, menos ida e volta.
- **Subir a versão do domínio.** Às vezes a extensão existe na 8.2 e não na 7.4 que o site ainda usa. Subir versão é bom por vários motivos, mas não é troca de caixinha: teste em cópia antes, porque plugin antigo quebra com aviso de depreciação e função removida.

O que não fazer: tentar carregar a extensão por `php.ini` ou por diretiva `extension=` sem que o arquivo `.so` exista no servidor. O PHP vai registrar erro de carregamento a cada requisição e você troca um problema visível por um problema silencioso no log.

## Checklist de padronização para quem cuida de várias contas

Quem administra dez ou cem sites não quer repetir esse diagnóstico por site. O jeito de não repetir é decidir uma vez e registrar.

### Defina a versão e as extensões padrão da carteira

- Uma versão de PHP padrão para sites novos, e uma versão mínima tolerada para sites legados.
- Um conjunto fixo de extensões que todo site novo recebe. `zip` e `intl` costumam entrar por padrão porque quase toda stack moderna pede. `soap` e `imap` entram por demanda, para não carregar módulo à toa.
- Uma regra escrita para `.htaccess`: nenhum handler de PHP fixo no arquivo. A versão se define no MultiPHP Manager. Isso evita que uma mudança de painel deixe de ter efeito meses depois, quando ninguém lembra do arquivo.

### Mantenha um registro de versão e extensões por cliente

Uma planilha simples já resolve, e vale mais que memória:

| Domínio | Versão de PHP | Extensões extras | Handler no .htaccess | Última conferência |
|---|---|---|---|---||
| exemplo1.com.br | 8.2 | zip, intl, soap | não | 12/03 |
| exemplo2.com.br | 8.1 | zip, intl, imap | não | 12/03 |
| loja.exemplo3.com.br | 8.2 | zip, intl | sim, removido | 14/03 |

Os domínios acima são exemplos fictícios. O que importa é a estrutura: ao receber o próximo chamado de "falta extensão", você consulta a linha antes de abrir o painel e já sabe onde marcar.

### Quando reconferir: migração, upgrade e instalação nova

- Ao migrar um site, conferir a versão no MultiPHP Manager e o `.htaccess` no mesmo dia, antes do DNS apontar.
- Ao subir a versão de PHP de um domínio, reconferir as extensões: a versão nova não herda a seleção da antiga.
- Antes de instalar qualquer sistema novo do cliente, ler o requisito de extensões na documentação dele e marcar tudo de uma vez, em vez de descobrir na tela de erro do instalador.

## Como explicar isso ao cliente sem parecer desculpa

O cliente final não precisa entender pacote de módulo nem PHP-FPM. Ele precisa saber que o problema foi resolvido e que não era falta de recurso no servidor. Uma frase pronta que funciona:

> **** O servidor tem o recurso, mas ele estava ligado em outra versão do PHP. O seu site roda na 8.2 e a ativação foi feita lá. Já está valendo.

Se o cliente perguntar por que existe mais de uma versão, a resposta curta é que o servidor mantém várias versões ao mesmo tempo para que sites antigos continuem funcionando enquanto os novos usam a versão atual, e que cada versão tem a sua própria lista de recursos ligados.

Se a extensão não existia e você precisou abrir chamado no provedor, avise antes que vai haver espera, e diga o que está esperando. "Pedi ao datacenter a instalação do módulo de integração fiscal na versão de PHP do seu site" é uma frase que o cliente entende e aceita melhor do que silêncio seguido de "resolvido".

## A pergunta que resolve antes de marcar qualquer caixa

Antes de marcar qualquer caixa, responda a uma pergunta: **qual versão de PHP este domínio executa agora**. O MultiPHP Manager diz, o `.htaccess` pode contradizer, e o `Loaded Configuration File` do `phpinfo()` é o desempate. Depois disso, marcar a extensão é trivial.

E quando o aviso sumir, apague o `phpinfo.php`. É a parte do procedimento que mais se esquece e a única que tem custo de segurança.

