blog
Painéis

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.

JR · · 9 min de leitura · 2 tabelas · 3 blocos de código

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

Neste artigo
  1. Por que o aviso continua depois de você marcar a caixa
  2. Roteiro para acertar a versão antes de marcar qualquer coisa
  3. O que imap, intl, soap e zip quebram quando faltam
  4. Quando a extensão nem aparece na lista do Select PHP Version
  5. Checklist de padronização para quem cuida de várias contas
  6. Como explicar isso ao cliente sem parecer desculpa
  7. A pergunta que resolve antes de marcar qualquer caixa

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

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:

# 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
// apagar depois de conferir
phpinfo();

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

  1. O número da versão no topo. Tem que bater com o que você configurou.
  2. 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.
  3. 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:

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

Roteiro de diagnóstico da extensão ausenteMultiPHP ManagerAnote a versão do domínioChecar .htaccessProcure AddHandler na raiz e pastaSelect PHP VersionMarque a extensão na mesma versãophpinfo temporárioConfira Loaded Configuration FilePHP-FPM reciclarReligue o FPM do domínioApagar o arquivoRemova o phpinfo ao terminar
Ordem que evita ativar a extensão na versão errada.

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

Duas saídas, nessa ordem:

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

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

Padronização de PHP em carteira de sitesDefinir padrãoVersão e extensões fixas da carteiraRegistrarPlanilha por domínio e handlerReconferirMigração, upgrade e instalação nova
Decidir uma vez e registrar evita repetir o diagnóstico por site.

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:

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.

Referências

  1. Documentação oficial (cpanel) — PHP Module: imap (cPanel EasyApache 4). Consultado em 2026-09-18.
Leia também