blog
Painéis

Como resolver failed to open stream em Mail.php no cPanel

Como ler o include_path do log, instalar o pacote certo pelo cPanel na versão de PHP correta e saber quando o problema é Composer, não PEAR.

JR · · 7 min de leitura · 2 tabelas · 5 blocos de código

Resposta curta: O erro `failed to open stream` em `Mail.php` significa que o pacote PEAR Mail não está instalado na sua conta ou não está no `include_path`. Instale pelo PHP PEAR Packages do cPanel, na mesma versão de PHP do domínio, junto com Net_SMTP e Net_Socket, e confirme com `stream_resolve_include_path('Mail.php')`.

Neste artigo
  1. A linha do log que importa
  2. Do nome do arquivo ao nome do pacote
  3. Instalar pelo PHP PEAR Packages do cPanel
  4. Fazer o PHP enxergar a pasta
  5. Confirmar que funcionou
  6. Quando PEAR é a resposta errada
  7. Checklist de diagnóstico

A linha do log que importa

O erro chega quase sempre assim, dentro de error_log na pasta do site ou no Log de Erros do cPanel:

PHP Warning:  require_once(Mail.php): failed to open stream:
No such file or directory in /home/usuario/public_html/envio.php on line 3
PHP Fatal error:  Uncaught Error: Failed opening required 'Mail.php'
(include_path='.:/usr/share/pear')

Três informações estão ali, e elas resolvem o caso:

Mail.php é o ponto de entrada do pacote Mail do PEAR, o repositório antigo de bibliotecas PHP. Código que usa require_once 'Mail.php'; e depois Mail::factory('smtp', ...) espera esse pacote instalado na conta. Se o site veio de um servidor onde alguém instalou PEAR e migrou para outro onde ninguém instalou, o arquivo simplesmente não existe ali.

O mesmo raciocínio vale para os parentes: Mail/mime.php é o pacote Mail_Mime, Net/SMTP.php é o Net_SMTP, HTTP/Request2.php é o HTTP_Request2.

Do nome do arquivo ao nome do pacote

A tradução é quase mecânica: o caminho que aparece no erro, sem o .php e com as barras viradas em sublinhado, costuma ser o nome do pacote PEAR.

Linha no erro Pacote PEAR a instalar
require_once 'Mail.php' Mail
require_once 'Mail/mime.php' Mail_Mime
require_once 'Net/SMTP.php' Net_SMTP
require_once 'Net/Socket.php' Net_Socket
require_once 'HTTP/Request2.php' HTTP_Request2
require_once 'DB.php' DB

Um detalhe que economiza uma segunda rodada de erro: o pacote Mail sozinho raramente basta. Quando você usa Mail::factory('smtp', ...), ele chama o Net_SMTP, que chama o Net_Socket. Se instalar só o Mail, o próximo log vai dizer Net/SMTP.php: failed to open stream. Já conte com os três.

Instalar pelo PHP PEAR Packages do cPanel

O cPanel tem uma interface própria para isso, descrita na documentação oficial do PHP PEAR Packages. Ela instala o pacote na sua conta, não no servidor inteiro, então você não depende de ninguém para liberar.

1. Descobrir qual versão de PHP o site usa

Faça isto antes, porque instalar o pacote na versão errada é o jeito mais comum de "instalei e continua dando erro". No cPanel, seção Software, abra MultiPHP Manager: é lá que cada domínio aparece com a versão de PHP que usa. Anote a versão ativa do domínio: 8.1, 8.2, 8.3, o que for. Guarde essa informação, porque a edição de diretivas acontece em outra tela, Select PHP Version (em contas sem ela, MultiPHP INI Editor), que é onde fica a aba de opções com o include_path.

2. Abrir o PHP PEAR Packages

No cPanel, seção Software, clique em PHP PEAR Packages. A tela tem uma caixa de busca de módulos e uma lista dos pacotes já instalados.

3. Procurar e instalar

Digite Mail na caixa Search e clique em Go. A busca devolve os pacotes com nome parecido. Clique em Install na linha do pacote exato que você quer. Repita para Net_SMTP e Net_Socket.

A saída da instalação aparece na própria tela. Leia até o fim: ela mostra as pastas onde os arquivos foram gravados. Guarde esse caminho, você vai precisar dele no passo seguinte.

4. Anotar o caminho da sua pasta PEAR

A interface mostra o caminho da instalação local da conta, normalmente algo como /home/usuario/php. O valor exato aparece na própria tela do PHP PEAR Packages e na saída da instalação. Copie exatamente o que estiver ali em vez de supor.

Se o cPanel instalou mas o PHP continua não achando, é porque esse caminho não está no include_path. É o que o próximo passo resolve.

Fazer o PHP enxergar a pasta

Há duas formas. Comece pela primeira. A busca e a instalação de pacotes da seção anterior estão descritas na documentação do cPanel; a edição de include_path a seguir não está nela, é o procedimento comum da interface e pode variar conforme a configuração do servidor.

Pelo painel, sem tocar em arquivo

Abra Select PHP Version, aba Options. Procure a diretiva include_path. O valor atual costuma ser .:/usr/share/pear. Acrescente, separado por dois-pontos, o caminho que você anotou. Exemplo (é um exemplo, use o caminho da sua tela):

.:/usr/share/pear:/home/usuario/php

Salve. A mudança vale para todos os sites naquela versão de PHP, o que normalmente é o que você quer.

Pelo próprio código, quando o painel não deixa

Se a diretiva estiver travada, dá para resolver no topo do script que falha, antes do require_once:

<?php
set_include_path(get_include_path() . PATH_SEPARATOR . '/home/usuario/php');
require_once 'Mail.php';

Linha a linha: get_include_path() lê a lista atual, PATH_SEPARATOR é o separador correto do sistema, e set_include_path() grava a lista com a sua pasta no fim. Só então o require_once é executado. Funciona, mas precisa ser repetido em cada ponto de entrada da aplicação, por isso é o plano B.

Caminho da instalação até o testeVer versão do PHPMultiPHP Manager, anote a versãoInstalar pacotesMail, Net_SMTP e Net_SocketAnotar caminho PEARCopie o caminho da telaSomar ao include_pathSelect PHP Version, aba OptionsTestarstream_resolve_include_path no navegador
Ordem que evita instalar o pacote na versão errada de PHP.

Confirmar que funcionou

Não confie na mensagem de sucesso da instalação. Teste do jeito que o PHP vai testar.

Crie um arquivo teste-pear.php em public_html com este conteúdo:

<?php
echo 'include_path: ' . get_include_path() . "\n";

$arquivo = stream_resolve_include_path('Mail.php');
echo $arquivo ? "Encontrado em: $arquivo\n" : "NAO encontrado\n";

Abra https://seudominio.com.br/teste-pear.php no navegador. O resultado esperado é a lista de pastas, já com a sua, e uma linha Encontrado em: seguida do caminho completo do Mail.php. Se vier NAO encontrado, o caminho que você acrescentou está errado ou o pacote foi instalado em outra versão de PHP.

Um aviso que vale o parágrafo: apague esse arquivo depois do teste. Vale ainda mais se você usar phpinfo(), que expõe caminhos e configurações do servidor para qualquer visitante.

Se o site roda por CLI ou cron, teste também pelo terminal. O PHP de linha de comando pode usar outro php.ini e, em servidores cPanel, o php do shell costuma ser até uma versão diferente da que o site usa:

php -r "echo stream_resolve_include_path('Mail.php') ?: 'nao achou';"

A saída esperada é o caminho completo do arquivo, algo como /home/usuario/php/Mail.php. Se aparecer nao achou, ou o pacote não está no include_path do CLI, ou você testou com outra versão de PHP. Para chamar a mesma versão do site, troque php pelo binário correspondente, por exemplo ea-php82 -r "..." para PHP 8.2. Confirme a versão em uso com php -v antes de concluir qualquer coisa.

Quando PEAR é a resposta errada

Antes de instalar qualquer coisa, abra o arquivo que gerou o erro e olhe o que ele pede.

O pacote Mail do PEAR é código antigo e com manutenção mínima. Ele continua funcionando para scripts legados, e instalar é legítimo quando você precisa que o site volte hoje. Mas se o script é seu e você tem como mexer, migrar o envio para PHPMailer via Composer é o caminho que não vai te trazer de volta a esta página em dois anos.

Como voltar atrás

Tudo aqui é reversível, desde que você faça o básico:

  1. Antes de editar o arquivo PHP, faça uma cópia de verdade: no Gerenciador de Arquivos do cPanel, selecione o arquivo e use Download para baixar uma cópia, ou use Copy e salve como envio.php.bak na mesma pasta. O editor do painel não guarda versão anterior: depois que você salva, o conteúdo antigo se perde.
  2. Antes de mudar include_path, copie o valor atual para um bloco de notas. Se algo quebrar, cole de volta e salve.
  3. Para remover um pacote, volte em PHP PEAR Packages e use Uninstall na linha dele, conforme a interface descrita na documentação do cPanel.
PEAR ou Composer: como decidirOlhe o arquivo que falhouLeia a linha do requireExiste pasta vendor?Ou require do autoload.phpSim: é ComposerReenvie vendor, não instale PEARNão: chama Mail::factoryÉ PEAR, instale pelo cPanelScript é seu e editávelPlaneje migrar para PHPMailer
Decisão antes de instalar qualquer pacote na conta.

Checklist de diagnóstico

Quando o erro insiste, percorra nesta ordem.

Sintoma Causa provável O que fazer
Mail.php: failed to open stream Pacote Mail não instalado Instalar Mail no PHP PEAR Packages
Instalou, mas o erro continua igual Pacote em outra versão de PHP Conferir a versão do domínio no MultiPHP Manager e reinstalar
Net/SMTP.php: failed to open stream Dependência faltando Instalar Net_SMTP e Net_Socket
Funciona no navegador, falha no cron PHP CLI com php.ini diferente Testar com php -r e ajustar o include no script
Erro cita vendor/autoload.php Projeto é Composer, não PEAR Reenviar a pasta vendor ou rodar a instalação de dependências
Nada aparece no log Log do PHP em outro lugar Abrir Errors/Log de Erros no cPanel e checar a pasta do domínio

A regra geral vale para qualquer failed to open stream, não só para o Mail.php: o PHP está dizendo exatamente qual arquivo procurou e em quais pastas. Resolver é colocar o arquivo em uma dessas pastas, ou colocar a pasta na lista. Não há terceiro caminho.

Referências

  1. Documentação oficial (cpanel) — PHP PEAR Packages. Consultado em 2026-10-08.
Leia também