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

> 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')`.

João Rizzon · 2026-10-14 · Painéis

---

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

- **O arquivo procurado**: `Mail.php`. Não é o seu arquivo, é uma biblioteca.
- **Quem procurou**: `/home/usuario/public_html/envio.php`, linha 3.
- **Onde procurou**: o `include_path`. Tudo que aparece entre as aspas é a lista de pastas que o PHP varreu. Se o arquivo não está em nenhuma delas, o PHP para.

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

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

- Se a linha é `require_once 'Mail.php';` e o código chama `Mail::factory(...)`, é PEAR. Siga os passos acima.
- Se existe uma pasta `vendor/` no projeto, ou o código tem `require __DIR__ . '/vendor/autoload.php';`, **não é PEAR**. É Composer, e o erro quase sempre significa que a pasta `vendor` não foi enviada no deploy ou foi excluída. Instalar PEAR não resolve e ainda deixa biblioteca duplicada na conta.
- Se o projeto usa PHPMailer, Symfony Mailer ou Laravel, é Composer. PHPMailer moderno não se carrega com `require_once 'Mail.php'`.

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:

- 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.
- Antes de mudar `include_path`, copie o valor atual para um bloco de notas. Se algo quebrar, cole de volta e salve.
- Para remover um pacote, volte em **PHP PEAR Packages** e use **Uninstall** na linha dele, conforme a interface descrita na [documentação do cPanel](https://docs.cpanel.net/cpanel/software/php-pear-packages/).

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

