16. Funções de rede
Discutiremos agora as funções de rede do PHP, que permitem programar usando TCP / IP (Transmission Control Protocol / Internet Protocol). Os scripts deste capítulo estão na pasta [scripts-console/inet] do código do curso:
| php8-oct-2026
└── scripts-console
└── inet
├── http
├── imap
├── ip
├── mailpit
├── smtp
└── utilities
|
16.1. Princípios básicos da programação web
Considere a comunicação entre duas máquinas remotas, A e B:

Quando uma aplicação AppA na máquina A quer se comunicar com uma aplicação AppB na máquina B na Internet, ela precisa saber várias coisas:
- o endereço IP (Internet Protocol) ou o nome da máquina B;
- o número da porta usada pela aplicação AppB. Isso porque a máquina B pode hospedar muitas aplicações que operam na Internet. Quando recebe informações da rede, ela precisa saber a qual aplicação as informações se destinam. As aplicações da máquina B acessam a rede por meio de interfaces também conhecidas como portas de comunicação. Essa informação está contida no pacote recebido pela máquina B para que ele possa ser entregue à aplicação correta;
- os protocolos de comunicação compreendidos pela máquina B. Em nosso estudo, usaremos apenas os protocolos TCP / IP;
- o protocolo de comunicação aceito pela aplicação AppB. De fato, as máquinas A e B "conversarão" entre si. O que elas disserem será encapsulado nos protocolos TCP e IP. No entanto, quando, na outra ponta da cadeia, a aplicação AppB receber as informações enviadas pela aplicação AppA, ela precisará ser capaz de interpretá-las. Isso é análogo a uma situação em que duas pessoas, A e B, se comunicam por telefone: a conversa é transportada pelo telefone. A fala é codificada em sinais pelo telefone A, transmitida pelas linhas telefônicas e chega ao telefone B para ser decodificada. A pessoa B então ouve a fala. É aqui que entra o conceito de protocolo de comunicação: se A fala francês e B não entende esse idioma, A e B não conseguirão se comunicar de forma eficaz.
Portanto, as duas aplicações que se comunicam devem concordar quanto ao tipo de diálogo que usarão. Por exemplo, o diálogo com um serviço chamado FTP não é o mesmo que com um serviço chamado POP: esses dois serviços não aceitam os mesmos comandos. Eles têm protocolos de diálogo diferentes.
16.1.2. Características do protocolo TCP
Aqui, nos concentraremos apenas nas comunicações de rede que usam o protocolo de transporte TCP, cujas principais características são as seguintes:
- O processo que deseja transmitir dados primeiro estabelece uma conexão com o processo que receberá as informações que ele está prestes a transmitir. Essa conexão é estabelecida entre uma porta da máquina emissora e uma porta da máquina receptora. Cria-se assim um caminho virtual entre as duas portas, que será reservado exclusivamente para os dois processos que estabeleceram a conexão;
- Todos os pacotes enviados pelo processo de origem seguem esse caminho virtual e chegam na ordem em que foram enviados;
- Os dados transmitidos aparecem como contínuos. O processo emissor envia os dados em seu próprio ritmo. Esses dados não são necessariamente enviados imediatamente: o protocolo TCP espera até ter dados suficientes para enviar. Eles são armazenados em uma estrutura chamada segmento TCP. Quando esse segmento está preenchido, ele é transmitido à camada IP, onde será encapsulado em um pacote IP;
- Cada segmento enviado pelo protocolo TCP é numerado. O protocolo TCP receptor verifica se está recebendo os segmentos em sequência. Para cada segmento recebido corretamente, ele envia uma confirmação (acknowledgment) ao emissor;
- quando o emissor recebe essa confirmação, ele notifica o processo emissor. O processo emissor pode, assim, confirmar que um segmento foi entregue com sucesso;
- se, após certo tempo, o protocolo TCP que enviou um segmento não receber uma confirmação, ele retransmite o segmento em questão, garantindo assim a qualidade do serviço de entrega das informações;
- O circuito virtual estabelecido entre os dois processos que se comunicam é full-duplex: isso significa que as informações podem fluir nos dois sentidos. Assim, o processo de destino pode enviar confirmações mesmo enquanto o processo de origem continua a enviar informações. Isso permite, por exemplo, que o protocolo TCP de origem envie vários segmentos sem esperar por uma confirmação. Se, após certo tempo, ele perceber que não recebeu a confirmação de um segmento específico nº n, retomará o envio dos segmentos a partir desse ponto.
16.1.3. A relação cliente-servidor
A comunicação pela Internet costuma ser assimétrica: a máquina A inicia uma conexão para solicitar um serviço à máquina B. Ela especifica que deseja estabelecer uma conexão com o serviço SB1 da máquina B. A máquina B aceita ou rejeita a solicitação. Se aceitar, a máquina A pode enviar suas requisições ao serviço SB1. Essas requisições devem obedecer ao protocolo de comunicação compreendido pelo serviço SB1. Estabelece-se assim um diálogo de requisição-resposta entre a máquina A, chamada de máquina cliente, e a máquina B, chamada de máquina servidor. Um dos dois parceiros encerrará a conexão.
16.1.4. Arquitetura do cliente
A arquitetura de um programa de rede que solicita serviços a uma aplicação servidora será a seguinte:
| open the connection with the SB1 service of machine B
if successful then
while not finished
prepare a request
send it to machine B
wait for and retrieve the response
process it
end while
end if
close the connection
|
16.1.5. Arquitetura do servidor
A arquitetura de um programa que oferece serviços será a seguinte:
| open the service on the local machine
while the service is open
listen for connection requests on a port called the listening port
when there is a request, have it handled by another task on another port called the service port
end while
|
O programa servidor trata a solicitação inicial de conexão de um cliente de maneira diferente de suas solicitações posteriores de serviço. O programa não presta o serviço por conta própria. Se o fizesse, deixaria de escutar as solicitações de conexão enquanto o serviço estivesse em andamento, e os clientes não seriam atendidos. Por isso, ele procede de outra forma: assim que uma solicitação de conexão é recebida na porta de escuta e depois aceita, o servidor cria uma tarefa responsável por prestar o serviço solicitado pelo cliente. Esse serviço é prestado em outra porta da máquina servidora, chamada de porta de serviço. Isso permite que vários clientes sejam atendidos ao mesmo tempo.
Uma tarefa de serviço terá a seguinte estrutura:
| while the service has not been fully provided
wait for a request on the service port
when there is one, build the response
send the response through the service port
end while
release the service port
|
Outra maneira de atender vários clientes ao mesmo tempo, sem criar tarefas, é monitorar simultaneamente a porta de escuta e as portas de serviço por meio de uma função que espera até que uma delas tenha algo a informar. É isso que o servidor TCP que vamos escrever fará, usando a função [stream_select] do PHP.
16.2. Explorando os protocolos de comunicação da Internet
16.2.1. Introdução
Quando um cliente se conecta a um servidor, estabelece-se um diálogo entre eles. A natureza desse diálogo constitui o que se chama de protocolo de comunicação do servidor. Entre os protocolos mais comuns da Internet estão os seguintes:
- HTTP: HyperText Transfer Protocol, o protocolo de comunicação com um servidor web (servidor HTTP);
- SMTP: Simple Mail Transfer Protocol, o protocolo de comunicação com um servidor de envio de e-mails (servidor SMTP);
- POP: Post Office Protocol, o protocolo de comunicação com um servidor de armazenamento de e-mails (servidor POP). Ele serve para recuperar os e-mails recebidos, não para enviá-los;
- IMAP: Internet Message Access Protocol, o protocolo de comunicação com um servidor de armazenamento de e-mails (servidor IMAP). Esse protocolo substituiu gradualmente o mais antigo protocolo POP;
- FTP: File Transfer Protocol, o protocolo de comunicação com um servidor de armazenamento de arquivos (servidor FTP).
Todos esses protocolos são baseados em texto: o cliente e o servidor trocam linhas de texto. Se você tiver um cliente capaz de:
- estabelecer uma conexão com um servidor TCP;
- exibir no console as linhas de texto enviadas pelo servidor;
- enviar ao servidor as linhas de texto que um usuário digitaria no teclado;
então podemos nos comunicar com um servidor TCP que use um protocolo baseado em texto, desde que conheçamos as regras desse protocolo.
16.2.2. Utilitários TCP
O curso de PHP 7 fornecia dois utilitários para Windows, [RawTcpClient] e [RawTcpServer], escritos em C#. Aqui, vamos substituí-los por dois scripts PHP, que examinaremos a seguir: essa é uma oportunidade de explorar as funções de rede do PHP. Eles estão na pasta [inet/utilities]:
| utilities
├── keyboard.php
├── tcp-client.php
└── tcp-server.php
|
- [tcp-client.php] permite conectar-se à porta P do servidor S;
- [tcp-server.php] cria um servidor que escuta clientes na porta P;
- [keyboard.php] contém duas funções usadas pelos dois scripts anteriores.
Observe que também existem ferramentas prontas para esse tipo de teste. No Windows, o comando PowerShell [Test-NetConnection localhost -Port 80] simplesmente verifica se um serviço está respondendo em uma porta. A ferramenta [curl], que encontraremos com o protocolo HTTP, pode se comunicar com muitos servidores, e sua opção [-v] (verbose) exibe as trocas entre cliente e servidor. Nossos dois scripts, por outro lado, nos permitem digitar nós mesmos os comandos do protocolo.
16.2.2.1. O servidor [tcp-server.php]
O servidor TCP [tcp-server.php] é invocado com a sintaxe [php tcp-server.php port] para criar um serviço TCP na porta [port] da máquina local (o computador em que você está trabalhando):
- O servidor pode atender vários clientes simultaneamente;
- o servidor executa os comandos digitados pelo usuário no teclado. Esses comandos são os seguintes:
- list: lista os clientes atualmente conectados ao servidor. Eles são exibidos no formato [id=x - name=y]. O campo [id] serve para identificar os clientes;
- send x [text]: envia text ao cliente nº x (id=x). Os colchetes [] não são enviados. Eles são obrigatórios no comando. Servem para delimitar visualmente o texto enviado ao cliente;
- close x: encerra a conexão com o cliente nº x;
- quit: encerra todas as conexões e interrompe o serviço;
- As linhas enviadas por um cliente ao servidor são exibidas no console;
- Toda a comunicação com um cliente é registrada em um arquivo de texto chamado [logs/machine-port.txt], em que [machine-port] identifica o cliente (seu endereço IP e a porta que ele usa).
O código do servidor é o seguinte:
| <?php
declare(strict_types=1);
// servidor TCP genérico
// sintaxe: php tcp-server.php port
// - espera clientes na porta [port] da máquina local e pode atender vários ao mesmo tempo;
// - exibe as linhas de texto enviadas pelos clientes;
// - executa os comandos digitados no teclado:
// list: lista os clientes conectados;
// send id [text]: envia [text] (sem os colchetes) ao cliente nº id;
// close id: fecha a conexão com o cliente nº id;
// quit: fecha todas as conexões e para o servidor;
// - registra as trocas com cada cliente no arquivo [logs/machine-port.txt]
// em que [machine-port] identifica o cliente
require_once __DIR__ . "/keyboard.php";
// análise dos argumentos da linha de comando
if (count($argv) !== 2 || !ctype_digit($argv[1])) {
print "Syntax: php tcp-server.php port\n";
exit(1);
}
$port = $argv[1];
// abertura do serviço em todas as interfaces de rede da máquina local
$server = @stream_socket_server("tcp://0.0.0.0:$port", $errorNumber, $error);
if ($server === false) {
print "Unable to open the service on the port [$port]: $error\n";
exit(2);
}
print "Server listening on the port [$port]\n";
print "Commands: list, send id [text], close id, quit\n";
if (!is_dir(__DIR__ . "/logs")) {
mkdir(__DIR__ . "/logs");
}
// os clientes conectados: id => [socket, nome, arquivo de log, buffer]
$clients = [];
$nextId = 1;
// o teclado é lido por um processo filho
[$reader, $keyboard] = startKeyboardReader();
$echo = !stream_isatty(STDIN);
$keyboardBuffer = "";
// laço de serviço
$done = false;
while (!$done) {
// monitoramos: a porta de escuta, os clientes e o teclado
$reads = [$server, $keyboard, ...array_column($clients, "socket")];
$writes = $exceptions = null;
stream_select($reads, $writes, $exceptions, null);
foreach ($reads as $stream) {
if ($stream === $server) {
// um novo cliente se conecta
$socket = stream_socket_accept($server, 0, $name);
if ($socket !== false) {
$id = $nextId++;
$log = fopen(__DIR__ . "/logs/" . str_replace(":", "-", $name) . ".txt", "w");
$clients[$id] = ["socket" => $socket, "name" => $name, "log" => $log, "buffer" => ""];
print "Client no. $id [$name] connected\n";
}
} elseif ($stream === $keyboard) {
// um comando foi digitado no teclado
$data = fread($keyboard, 8192);
if ($data === false || $data === "") {
// fim da entrada padrão: paramos o servidor
$done = true;
break;
}
foreach (extractLines($keyboardBuffer, $data) as $command) {
if ($echo) {
print "$command\n";
}
if (execute($command, $clients)) {
$done = true;
break;
}
}
} else {
// um cliente falou
$id = array_find_key($clients, fn(array $client): bool => $client["socket"] === $stream);
if ($id === null) {
// cliente fechado entretanto pelo comando [close]
continue;
}
$data = fread($stream, 8192);
if ($data === false || $data === "") {
print "The client no. $id has closed the connection\n";
close($clients, $id);
continue;
}
foreach (extractLines($clients[$id]["buffer"], $data) as $line) {
print "<-- client no. $id [$line]\n";
fwrite($clients[$id]["log"], "<-- [$line]\n");
}
}
}
}
// parada do serviço
foreach (array_keys($clients) as $id) {
close($clients, $id);
}
fclose($server);
proc_terminate($reader);
print "Server stopped\n";
// --------------------------------------------------------------------------
// executa um comando digitado no teclado - retorna true se for o comando [quit]
function execute(string $command, array &$clients): bool
{
// send id [text]
if (preg_match('/^send\s+(\d+)\s+\[(.*)\]$/', $command, $fields)) {
$id = (int) $fields[1];
if (!isset($clients[$id])) {
print "Unknown client no. $id\n";
} else {
fwrite($clients[$id]["socket"], "$fields[2]\r\n");
fwrite($clients[$id]["log"], "--> [$fields[2]]\n");
}
return false;
}
// os outros comandos
$words = preg_split('/\s+/', trim($command));
switch ($words[0]) {
case "list":
foreach ($clients as $id => $client) {
print "id=$id - name={$client["name"]}\n";
}
return false;
case "close":
$id = (int) ($words[1] ?? 0);
if (!isset($clients[$id])) {
print "Unknown client no. $id\n";
} else {
close($clients, $id);
print "Connection with the client no. $id closed\n";
}
return false;
case "quit":
return true;
default:
print "Unknown command [$command]. Commands: list, send id [text], close id, quit\n";
return false;
}
}
// --------------------------------------------------------------------------
// fecha a conexão com o cliente nº [$id]
function close(array &$clients, int $id): void
{
fclose($clients[$id]["socket"]);
fclose($clients[$id]["log"]);
unset($clients[$id]);
}
|
Comentários:
- linha 17: o arquivo [keyboard.php] é carregado; falaremos dele mais adiante;
- linha 20: o array [$argv] contém os argumentos da linha de comando. [$argv[0]] é o nome do script, [$argv[1]] é o primeiro argumento, neste caso o número da porta. A função [ctype_digit] verifica se o número da porta é composto apenas de dígitos;
- Linha 27: a função [stream_socket_server] inicia um serviço TCP. Seu primeiro parâmetro é um endereço no formato [tcp://interface:port]. A interface [0.0.0.0] refere-se a todas as interfaces de rede da máquina: o servidor pode ser acessado tanto por [localhost] quanto pelo endereço IP da máquina na rede local. Em caso de falha (por exemplo, se a porta já estiver em uso), a função retorna [false] e armazena um número de erro e uma mensagem de erro nas duas variáveis passadas como segundo e terceiro parâmetros. O operador [@] impede que o PHP exiba seu próprio aviso: exibimos a nossa mensagem;
- linha 39: o dicionário de clientes conectados. Cada cliente é descrito por seu socket (a conexão que o liga ao servidor), seu nome [address:port], seu arquivo de log e um buffer cuja finalidade discutiremos adiante;
- linha 42: o teclado é lido por um processo filho. Veremos por quê com o arquivo [keyboard.php]. [$keyboard] é um stream no qual as linhas digitadas no teclado são colocadas;
- Linha 43: a função [stream_isatty] determina se a entrada padrão é o teclado (um terminal) ou não. Se a entrada padrão tiver sido redirecionada para um arquivo ([php tcp-server.php 100 < commands.txt]), os comandos lidos não são exibidos na tela. O servidor então os exibirá por conta própria;
- linhas 48–52: o laço de serviço. A cada iteração, o servidor espera que um dos streams que monitora tenha algo a lhe dizer: a porta de escuta (um novo cliente se conecta), o teclado (um comando foi digitado) ou um dos clientes (ele enviou texto). O operador [...] decompõe o array de sockets dos clientes (obtido com [array_column]) no array [$reads];
- Linha 52: a função [stream_select] espera que um dos streams do array [$reads] esteja legível. O último parâmetro, [null], significa: esperar indefinidamente. Ao retornar, a função removeu do array [$reads] os streams sem nada para ler. O segundo e o terceiro parâmetros dizem respeito aos streams nos quais queremos escrever e aos eventos excepcionais: não temos interesse neles. Como são passados por referência, precisamos passar variáveis, neste caso [$writes] e [$exceptions], que são iguais a [null];
- Linhas 54–60: um novo cliente se conecta. A função [stream_socket_accept] aceita a conexão. Ela retorna o socket de serviço que liga o servidor a esse cliente e armazena a identidade do cliente em [$name] na forma [address:port]. Um timeout igual a 0 significa que não há espera: [stream_select] nos informou que um cliente estava aguardando;
- linhas 63–75: um comando foi digitado no teclado. A função [fread] lê tudo o que estiver disponível (até 8.192 bytes). Uma string vazia significa que o stream foi fechado. A função [extractLines] divide o que foi lido em linhas completas;
- linhas 81–95: um cliente enviou texto. A função [array_find_key] (PHP 8.4) retorna a chave do primeiro elemento do array que satisfaz a condição expressa pela função de seta [fn] passada como segundo parâmetro: isso recupera o ID do cliente a partir de seu socket. Se [fread] retornar uma string vazia, o cliente fechou a conexão. Caso contrário, cada linha recebida é exibida e registrada no arquivo de log do cliente;
- Linhas 110–141: a função [execute] executa um comando digitado no teclado. O comando [send id [text]] é reconhecido por uma expressão regular. O texto é enviado ao cliente seguido da sequência \r\n: os protocolos da Internet terminam as linhas de texto com os dois caracteres CR (\r) e LF (\n);
- linha 150: a função [close] fecha a conexão com um cliente e o remove do dicionário [$clients], passado por referência ([&]).
16.2.2.2. O arquivo [keyboard.php]
O arquivo [keyboard.php] é o seguinte:
| <?php
declare(strict_types=1);
// ferramentas compartilhadas por [tcp-client.php] e [tcp-server.php]
// --------------------------------------------------------------------------
// inicia um processo filho que lê o teclado e nos devolve cada linha digitada
// por meio de um socket. Por quê? Nossos programas precisam monitorar ao mesmo tempo a rede e o
// teclado com a função [stream_select]. Mas no Windows, [stream_select]
// só consegue monitorar sockets, não o teclado (STDIN).
// O descritor ['socket'] de [proc_open] (PHP 8.0) conecta o processo filho ao
// processo pai por meio de um socket, que [stream_select] pode monitorar em qualquer sistema operacional.
// retorna o processo filho e o socket que entrega as linhas digitadas no teclado
function startKeyboardReader(): array
{
$process = proc_open(
// o processo filho: um script PHP de uma linha que copia sua entrada para sua saída
[PHP_BINARY, "-r", 'while (($line = fgets(STDIN)) !== false) { echo $line; }'],
// sua entrada é o nosso teclado, sua saída é um socket
[0 => STDIN, 1 => ["socket"], 2 => STDERR],
$pipes
);
if ($process === false) {
throw new RuntimeException("Unable to start the keyboard reader");
}
return [$process, $pipes[1]];
}
// --------------------------------------------------------------------------
// adiciona os bytes [$data] ao buffer [$buffer] e extrai dele as linhas completas,
// retornadas sem a marca de fim de linha (\n ou \r\n);
// o fim do buffer (uma linha incompleta) permanece no buffer
function extractLines(string &$buffer, string $data): array
{
$buffer .= $data;
$lines = explode("\n", $buffer);
// o último elemento é a linha atual, ainda não terminada
$buffer = array_pop($lines);
return array_map(fn(string $line): string => rtrim($line, "\r"), $lines);
}
|
Comentários:
- Linha 15: nossos dois scripts precisam monitorar a rede e o teclado ao mesmo tempo. No Linux ou no macOS, poderíamos passar o stream [STDIN] (o teclado) para [stream_select]. No Windows, isso não é possível: [stream_select] só pode monitorar sockets nesse sistema. A solução alternativa é ter um segundo processo que leia o teclado e nos envie as linhas digitadas por meio de um socket;
- Linhas 17–22: a função [proc_open] inicia um processo filho. Seu primeiro parâmetro é o comando a ser executado, na forma de um array: o interpretador PHP em execução ([PHP_BINARY]) com a opção [-r], que executa o código PHP passado como argumento. Esse código copia cada linha lida de sua entrada para sua saída. O segundo parâmetro descreve os streams do processo filho: sua entrada (0) é a nossa entrada padrão (o teclado), sua saída (1) é um socket criado pelo PHP (descritor [['socket']], disponível desde o PHP 8.0) e seus erros (2) são enviados à nossa saída de erro. O terceiro parâmetro recebe os streams criados: [$pipes[1]] é a nossa extremidade do socket;
- linha 34: quando [stream_select] sinaliza que um stream está pronto para leitura, [fread] retorna o que foi recebido: pode ser uma linha, várias linhas ou parte de uma linha. A função [extractLines] adiciona esses bytes ao buffer [$buffer] (passado por referência), extrai dele as linhas completas e mantém a linha inacabada no buffer. Observe a função de seta [fn(string $line): string => rtrim($line, "\r")], que remove o \r final das linhas terminadas em \r\n.
Poderíamos ter lido as linhas com a função [fgets]. No entanto, [fgets] lê os dados em blocos e guarda as linhas que ainda não entregou em um buffer interno do PHP. O [stream_select], que monitora apenas a rede, não as veria. Ler com [fread] e dividir as linhas nós mesmos evita essa armadilha.
16.2.2.3. O cliente [tcp-client.php]
O cliente TCP [tcp-client.php] é chamado com a sintaxe [php tcp-client.php [--quit command] [--tls] server port] para se conectar à porta [port] do servidor [server]:
- As linhas digitadas pelo usuário no teclado são enviadas ao servidor;
- as linhas enviadas pelo servidor são exibidas no console assim que chegam;
- toda a comunicação é registrada em um arquivo de texto chamado [logs/server-port.txt];
- o comando [quit] interrompe o cliente. A opção [--quit] permite escolher outro comando;
- A opção [--tls] criptografa a conexão. Precisaremos dela para nos comunicar com servidores seguros.
Seu código é o seguinte:
| <?php
declare(strict_types=1);
// cliente TCP genérico
// sintaxe: php tcp-client.php [--quit command] [--tls] server port
// - conecta-se à porta [port] da máquina [server];
// - exibe as linhas de texto enviadas pelo servidor assim que chegam;
// - envia ao servidor as linhas de texto digitadas no teclado;
// - registra todas as trocas no arquivo [logs/server-port.txt]
// opções:
// --quit command: o comando que encerra o cliente ([quit] por padrão)
// --tls: a conexão é criptografada (TLS) assim que é aberta
require_once __DIR__ . "/keyboard.php";
// análise dos argumentos da linha de comando
$quit = "quit";
$tls = false;
$arguments = [];
for ($i = 1; $i < count($argv); $i++) {
match ($argv[$i]) {
"--quit" => $quit = $argv[++$i] ?? $quit,
"--tls" => $tls = true,
default => $arguments[] = $argv[$i],
};
}
if (count($arguments) !== 2 || !ctype_digit($arguments[1])) {
print "Syntax: php tcp-client.php [--quit command] [--tls] server port\n";
exit(1);
}
[$server, $port] = $arguments;
// abertura da conexão com o servidor
// com --tls, o certificado do servidor não é verificado: esta é uma ferramenta de descoberta
$context = stream_context_create(["ssl" => ["verify_peer" => false, "verify_peer_name" => false]]);
$transport = $tls ? "tls" : "tcp";
$connection = @stream_socket_client("$transport://$server:$port", $errorNumber, $error, 10,
STREAM_CLIENT_CONNECT, $context);
if ($connection === false) {
print "Failed to connect to the server [$server:$port]: $error\n";
exit(2);
}
$client = stream_socket_get_name($connection, false);
print "Client [$client] connected to the server [$server:$port]\n";
print "Type your commands ($quit to stop):\n";
// arquivo de log
if (!is_dir(__DIR__ . "/logs")) {
mkdir(__DIR__ . "/logs");
}
$log = fopen(__DIR__ . "/logs/$server-$port.txt", "w");
// o teclado é lido por um processo filho
[$reader, $keyboard] = startKeyboardReader();
// se a entrada padrão for um arquivo (php tcp-client.php ... < commands.txt),
// os comandos lidos não são exibidos na tela: nós mesmos os exibiremos
$echo = !stream_isatty(STDIN);
// buffers das linhas incompletas recebidas do servidor e do teclado
$serverBuffer = "";
$keyboardBuffer = "";
// laço de diálogo com o servidor
$done = false;
while (!$done) {
// esperamos até que o servidor ou o teclado tenha algo a nos dizer
$reads = $keyboard !== null ? [$connection, $keyboard] : [$connection];
$writes = $exceptions = null;
// sem teclado (fim da entrada padrão), não esperamos o servidor por mais de 2 segundos
if (stream_select($reads, $writes, $exceptions, $keyboard !== null ? null : 2) === 0) {
break;
}
// o servidor falou?
if (in_array($connection, $reads, true)) {
$data = fread($connection, 8192);
if ($data === false || $data === "") {
// o servidor fechou a conexão
if ($serverBuffer !== "") {
display("<-- [$serverBuffer]", $log);
}
print "Connection with the server lost...\n";
break;
}
foreach (extractLines($serverBuffer, $data) as $line) {
display("<-- [$line]", $log);
}
}
// uma linha foi digitada no teclado?
if ($keyboard !== null && in_array($keyboard, $reads, true)) {
$data = fread($keyboard, 8192);
if ($data === false || $data === "") {
// fim da entrada padrão
$keyboard = null;
continue;
}
foreach (extractLines($keyboardBuffer, $data) as $command) {
if ($echo) {
print "$command\n";
}
// fim do cliente?
if ($command === $quit) {
$done = true;
break;
}
// enviamos o comando ao servidor: os protocolos da internet
// terminam as linhas com a sequência \r\n
fwrite($connection, "$command\r\n");
fwrite($log, "--> [$command]\n");
}
}
}
// fechamento da conexão, do arquivo de log e do leitor de teclado
fclose($connection);
fclose($log);
proc_terminate($reader);
print "End of the client\n";
// --------------------------------------------------------------------------
// exibe uma linha recebida e a registra no arquivo de log
function display(string $line, $log): void
{
print "$line\n";
fwrite($log, "$line\n");
}
|
Comentários:
- Linhas 21–26: análise dos argumentos. A expressão [match] (PHP 8.0) compara seu argumento com os valores de seus ramos usando o operador [===] e avalia o ramo correspondente. Aqui, cada ramo é uma atribuição. [$argv[++$i] ?? $quit] retorna o argumento que segue [--quit] se ele existir, e [$quit] caso contrário;
- linha 32: desempacotamento de array: [$server] recebe [$arguments[0]], e [$port] recebe [$arguments[1]];
- Linhas 36–39: a função [stream_socket_client] estabelece uma conexão com o serviço [tcp://server:port]. Com a opção [--tls], o endereço passa a ser [tls://server:port]: o PHP então criptografa a conexão usando o protocolo TLS (Transport Layer Security). O contexto criado por [stream_context_create] especifica aqui que o certificado do servidor não deve ser verificado: para uma ferramenta de exploração, isso evita problemas com servidores de teste que têm certificados autoassinados. O quarto parâmetro é o tempo máximo (em segundos) permitido para estabelecer a conexão;
- linha 44: a função [stream_socket_get_name] retorna se uma conexão é local (false) ou remota (true), na forma [address:port];
- Linhas 65–70: o laço de diálogo. Ele tem a mesma estrutura do laço do servidor: [stream_select] espera que o servidor ou o teclado enviem algo. Quando a entrada padrão termina (como no caso de uma entrada redirecionada de um arquivo), o cliente continua a exibir o que o servidor envia, mas não espera por isso por mais de 2 segundos;
- linhas 73–85: as linhas enviadas pelo servidor são exibidas, entre colchetes, e gravadas no arquivo de log. Se o servidor fechar a conexão, o laço é interrompido;
- linhas 88–108: cada linha digitada no teclado é enviada ao servidor, seguida da sequência \r\n, exceto o comando de parada do cliente;
- linha 115: por fim, o processo filho que lê o teclado é encerrado.
16.2.2.4. Um exemplo
Vejamos um exemplo. Abra dois terminais (no VS Code, o botão [+] da visão [Terminal] abre um novo) e navegue até a pasta [inet/utilities] em cada um deles. No primeiro terminal, inicie o servidor na porta 100. No segundo, inicie o cliente e instrua-o a se conectar à porta 100 da máquina local [localhost], e depois digite uma linha de texto. Volte ao servidor, responda ao cliente nº 1, peça a lista de clientes, feche a conexão com o cliente nº 1 e interrompa o servidor.
Veja o que o servidor exibe (os comandos digitados no teclado são as linhas [send 1 ...], [list], [close 1], e [quit]):
| > php tcp-server.php 100
Server listening on the port [100]
Commands: list, send id [text], close id, quit
Client no. 1 [127.0.0.1:47966] connected
<-- client no. 1 [hello from client]
send 1 [hello from server]
list
id=1 - name=127.0.0.1:47966
close 1
Connection with the client no. 1 closed
quit
Server stopped
|
- [Client no. 1 [127.0.0.1:47966] connected]: um cliente foi detectado. O servidor lhe atribuiu o número 1. O cliente está usando a porta 47966 da máquina com endereço IP 127.0.0.1. Esse endereço pertence a [localhost], a máquina local;
- [<-- client no. 1 [hello from client]]: a linha recebida do cliente é colocada entre colchetes;
- [send 1 [hello from server]]: a resposta enviada ao cliente nº 1. Apenas o texto dentro dos colchetes é enviado, não os colchetes em si;
- [list]: a lista de clientes e sua resposta;
- [close 1] seguido de [quit]: a conexão com o cliente nº 1 é fechada e, em seguida, o servidor é encerrado.
E aqui está o que o cliente exibe:
| > php tcp-client.php localhost 100
Client [127.0.0.1:47966] connected to the server [localhost:100]
Type your commands (quit to stop):
hello from client
<-- [hello from server]
Connection with the server lost...
End of the client
|
- [hello from client]: a linha digitada no teclado;
- [<-- [hello from server]]: a resposta recebida do servidor. O texto recebido é o que está entre colchetes;
- [Connection with the server lost...]: o cliente detectou que o servidor fechou a conexão.
Dois arquivos de log foram criados na pasta [utilities/logs], um pelo servidor e outro pelo cliente. O arquivo do servidor tem o nome do cliente, [127.0.0.1-47966.txt]:
| <-- [hello from client]
--> [hello from server]
|
O arquivo do cliente tem o nome do servidor, [localhost-100.txt]:
| --> [hello from client]
<-- [hello from server]
|
16.3. Obter o nome ou o endereço IP de uma máquina na Internet
Os computadores na Internet são identificados por um endereço (IP, IPv4 ou IPv6) e, na maioria das vezes, por um nome. No entanto, em última análise, apenas o endereço é usado. Por isso, às vezes é necessário saber o endereço IP de uma máquina identificada por seu nome. Esse é o papel do serviço DNS (Domain Name System).
O script [inet/ip/ip-01.php] é o seguinte:
| <?php
declare(strict_types=1);
// endereços IP e nomes de máquinas da internet
// as máquinas cujo endereço IP e nome queremos obter
const HOSTS = ["istia.univ-angers.fr", "www.univ-angers.fr", "www.ibm.com", "www.php.net", "yahoo.com", "localhost", "xx"];
// adicionamos a máquina local, cujo nome é dado por [gethostname]
foreach ([...HOSTS, gethostname()] as $host) {
getIPandName($host);
}
// fim
print "Done\n";
// --------------------------------------------------------------------------
function getIPandName(string $machineName): void
{
// $machineName: nome da máquina cujo endereço IP queremos
print "---------------\n";
// machineName --> endereço IP
$ip = gethostbyname($machineName);
if ($ip === $machineName) {
print "Error, machine [$machineName] not found\n";
return;
}
print "ip[$machineName]=$ip\n";
// todos os endereços IPv4 da máquina
$ips = gethostbynamel($machineName);
if ($ips !== false && count($ips) > 1) {
print "all the IPv4 addresses of [$machineName]: " . implode(", ", $ips) . "\n";
}
// endereço IP --> machineName
$name = gethostbyaddr($ip);
if ($name === false || $name === $ip) {
print "Error, no name for the address [$ip]\n";
} else {
print "name[$ip]=$name\n";
}
}
|
Comentários:
- linha 8: a lista de máquinas para as quais queremos o nome e o endereço IP;
- linha 11: o nome da máquina local, retornado pela função [gethostname], é adicionado a essa lista. O operador [...] copia os elementos do array [HOSTS] para o novo array;
- linha 18: as funções de rede do PHP são usadas na função [getIPandName];
- Linha 23: a função [gethostbyname($machineName)] retorna o endereço IPv4 "ip3.ip2.ip1.ip0" da máquina chamada $machineName. Se a máquina $machineName não existir, a função retorna $machineName como resultado;
- linha 30: uma máquina pode ter vários endereços, como IPv4. A função [gethostbynamel] retorna todos eles em um array (ou [false] se a operação falhar);
- linha 35: a função [gethostbyaddr($ip)] recupera o nome da máquina com o endereço $ip. Se o endereço $ip não tiver nome, a função retorna $ip como resultado, e [false] se o endereço estiver malformado.
As funções [gethostbyname] e [gethostbynamel] só reconhecem endereços na forma IPv4. Para obter os endereços IPv6 de uma máquina, você usaria a função [dns_get_record] com o tipo [DNS_AAAA].
Resultados:
| > php ip-01.php
---------------
ip[istia.univ-angers.fr]=193.49.144.41
name[193.49.144.41]=ametys-fo-2.univ-angers.fr
---------------
ip[www.univ-angers.fr]=193.49.144.41
name[193.49.144.41]=ametys-fo-2.univ-angers.fr
---------------
ip[www.ibm.com]=23.217.77.36
name[23.217.77.36]=a23-217-77-36.deploy.static.akamaitechnologies.com
---------------
ip[www.php.net]=107.150.176.1
name[107.150.176.1]=107-150-176-1.bunnyinfra.net
---------------
ip[yahoo.com]=98.137.11.163
all the IPv4 addresses of [yahoo.com]: 98.137.11.164, 98.137.11.163, 74.6.231.21, 74.6.143.25, 74.6.231.20, 74.6.143.26
name[98.137.11.163]=media-router-fp74.prod.media.vip.gq1.yahoo.com
---------------
ip[localhost]=127.0.0.1
name[127.0.0.1]=localhost
---------------
Error, machine [xx] not found
---------------
ip[vm]=127.0.0.1
name[127.0.0.1]=localhost
Done
|
- As máquinas [istia.univ-angers.fr] e [www.univ-angers.fr] têm o mesmo endereço IP. O nome obtido a partir do endereço IP, conhecido como nome canônico, é ainda outro nome;
- o nome [www.ibm.com] está associado a um servidor pertencente à Akamai, uma empresa que hospeda sites de muitas empresas;
- A máquina [yahoo.com] tem seis endereços IPv4: as requisições são distribuídas entre vários servidores;
- [localhost] tem o endereço 127.0.0.1, conhecido como endereço de loopback: ele sempre se refere à máquina local;
- A máquina [xx] não existe;
- a última máquina é a máquina local, chamada aqui de [vm]. Os resultados dependem da configuração da máquina: em um computador Windows, você obterá o nome do seu computador e, dependendo da configuração, seu endereço na rede local (192.168.x.y, por exemplo).
Os resultados obtidos para máquinas na Internet mudam ao longo do tempo: provavelmente você não obterá os mesmos resultados.
16.4. O protocolo HTTP (HyperText Transfer Protocol)
16.4.1. Exemplo 1

Quando um navegador exibe uma URL, ele atua como cliente de um servidor web — ou, em outras palavras, de um servidor HTTP. O navegador toma a iniciativa e começa enviando uma série de comandos ao servidor. Para este primeiro exemplo:
- o servidor será o utilitário [tcp-server.php];
- o cliente será um navegador web.
Primeiro, iniciamos o servidor na porta 100 e, em seguida, usando um navegador, solicitamos a URL [http://localhost:100], ou seja, estamos dizendo que o servidor HTTP que consultamos está em execução na porta 100 da máquina local. O navegador aguarda a resposta. Voltemos à janela do servidor. Ali vemos as linhas enviadas pelo navegador. Em seguida, digitamos uma resposta no formato HTTP, linha por linha, depois fechamos a conexão e paramos o servidor:
| > php tcp-server.php 100
Server listening on the port [100]
Commands: list, send id [text], close id, quit
Client no. 1 [127.0.0.1:45752] connected
<-- client no. 1 [GET / HTTP/1.1]
<-- client no. 1 [Host: localhost:100]
<-- client no. 1 [Connection: keep-alive]
<-- client no. 1 [sec-ch-ua: "HeadlessChrome";v="141", "Not?A_Brand";v="8", "Chromium";v="141"]
<-- client no. 1 [sec-ch-ua-mobile: ?0]
<-- client no. 1 [sec-ch-ua-platform: "Linux"]
<-- client no. 1 [Upgrade-Insecure-Requests: 1]
<-- client no. 1 [User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/141.0.7390.37 Safari/537.36]
<-- client no. 1 [Accept-Language: en-US]
<-- client no. 1 [Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7]
<-- client no. 1 [Sec-Fetch-Site: none]
<-- client no. 1 [Sec-Fetch-Mode: navigate]
<-- client no. 1 [Sec-Fetch-User: ?1]
<-- client no. 1 [Sec-Fetch-Dest: document]
<-- client no. 1 [Accept-Encoding: gzip, deflate, br, zstd]
<-- client no. 1 []
send 1 [HTTP/1.1 200 OK]
send 1 [Content-Type: text/html; charset=utf-8]
send 1 [Connection: close]
send 1 []
send 1 [<h1>Hello from the TCP server!</h1>]
close 1
Connection with the client no. 1 closed
list
quit
Server stopped
|
- [Client no. 1]: o navegador que se conectou;
- seguido das linhas de texto que ele enviou:
- [GET / HTTP/1.1]: esta linha tem o formato [GET URL HTTP/1.1]. Ela solicita a URL / e instrui o servidor a usar o protocolo HTTP 1.1;
- [Host: localhost:100]: esta linha tem o formato [Host: server:port]. A diferença entre maiúsculas e minúsculas no cabeçalho [Host] não importa. Observe que o cliente está consultando um servidor local que opera na porta 100;
- o cabeçalho [Connection] especifica o modo de conexão desejado: [keep-alive] indica que a conexão deve ser mantida após a resposta, para eventuais requisições seguintes;
- o cabeçalho [User-Agent] fornece a identidade do cliente. Neste caso, trata-se de um navegador Chromium. Os cabeçalhos [sec-ch-ua...] e [Sec-Fetch...] são específicos de navegadores recentes. Os valores exatos dependem do navegador e do sistema operacional utilizados;
- o cabeçalho [Accept] especifica quais tipos de documento são aceitos pelo cliente;
- o cabeçalho [Accept-Language] especifica o idioma preferido para os documentos solicitados, caso estejam disponíveis em vários idiomas;
- o cabeçalho [Accept-Encoding] indica que o cliente aceita documentos compactados;
- o cliente encerra seus comandos com uma linha em branco;
- Os comandos [send 1 [...]] enviam a resposta ao navegador: uma primeira linha, [HTTP/1.1 200 OK], indicando que o documento solicitado foi encontrado; cabeçalhos; uma linha em branco; e, em seguida, o documento. O cabeçalho [Content-Type] especifica o tipo do documento — neste caso, HTML codificado em UTF-8 — e o cabeçalho [Connection: close] indica que o servidor fechará a conexão ao final do documento;
- [close 1]: o fechamento da conexão sinaliza ao navegador que o documento está completo.
O navegador então exibe o documento recebido:

Acabamos de escrever um servidor web "do zero"!
16.4.2. Exemplo 2
Agora que conhecemos os comandos enviados por um navegador para solicitar uma URL, vamos solicitar uma URL usando nosso cliente TCP [tcp-client.php]. O servidor Apache do [Laragon] será nosso servidor web: inicie-o (o botão [Start All] no [Laragon]). A pasta [inet/http/pages] contém uma página HTML estática:
| <!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Hello</title>
</head>
<body>
<h1>Hello!</h1>
<p>A static page served by the web server.</p>
</body>
</html>
|
Como o diretório [php8-oct-2026] está localizado dentro do diretório [<laragon>/www], esta página é acessível pela URL [http://localhost/php8-oct-2026/scripts-console/inet/http/pages/hello.html]. Vamos solicitá-la usando nosso cliente TCP, conectado à porta 80 do servidor [localhost], onde o servidor web está em execução. Digitamos os comandos que descobrimos no parágrafo anterior:
| > php tcp-client.php localhost 80
Client [127.0.0.1:59734] connected to the server [localhost:80]
Type your commands (quit to stop):
GET /php8-oct-2026/scripts-console/inet/http/pages/hello.html HTTP/1.1
Host: localhost:80
<-- [HTTP/1.1 200 OK]
<-- [Date: Thu, 01 Oct 2026 15:32:51 GMT]
<-- [Server: Apache/2.4.58 (Ubuntu)]
<-- [Last-Modified: Thu, 01 Oct 2026 15:02:24 GMT]
<-- [ETag: "e2-65cc8b40e550d"]
<-- [Accept-Ranges: bytes]
<-- [Content-Length: 226]
<-- [Vary: Accept-Encoding]
<-- [Content-Type: text/html]
<-- []
<-- [<!DOCTYPE html>]
<-- [<html lang="en">]
<-- [ <head>]
<-- [ <meta charset="utf-8">]
<-- [ <title>Hello</title>]
<-- [ </head>]
<-- [ <body>]
<-- [ <h1>Hello!</h1>]
<-- [ <p>A static page served by the web server.</p>]
<-- [ </body>]
<-- [</html>]
quit
End of the client
|
- [GET ... HTTP/1.1]: o comando [GET] com o caminho do documento solicitado;
- [Host: localhost:80]: o cabeçalho [Host];
- estes são os únicos dois comandos essenciais. Para os demais cabeçalhos, o servidor web usará valores padrão;
- a linha vazia que deve encerrar os comandos do cliente;
- Abaixo da linha em branco vem a resposta do servidor web Apache:
- [HTTP/1.1 200 OK]: a linha de status. O código 200 significa que o documento foi encontrado;
- em seguida vêm os cabeçalhos HTTP da resposta, seguidos de uma linha em branco. O cabeçalho [Content-Length] especifica o tamanho do documento em bytes;
- depois da linha em branco vem o documento HTML solicitado;
- o cabeçalho [Server] identifica o servidor web: neste caso, um servidor Apache 2.4. Com o [Laragon], você verá a entrada [(Win64)] e as versões do OpenSSL e do PHP;
- [quit]: digitamos [quit] para encerrar a conexão do cliente. O servidor, por sua vez, mantém a conexão aberta por alguns segundos (modo keep-alive do HTTP/1.1) enquanto aguarda outra requisição e depois a fecha.
O arquivo de log [utilities/logs/localhost-80.txt] contém as trocas:
| --> [GET /php8-oct-2026/scripts-console/inet/http/pages/hello.html HTTP/1.1]
--> [Host: localhost:80]
--> []
<-- [HTTP/1.1 200 OK]
<-- [Date: Thu, 01 Oct 2026 15:32:51 GMT]
<-- [Server: Apache/2.4.58 (Ubuntu)]
<-- [Last-Modified: Thu, 01 Oct 2026 15:02:24 GMT]
<-- [ETag: "e2-65cc8b40e550d"]
<-- [Accept-Ranges: bytes]
<-- [Content-Length: 226]
<-- [Vary: Accept-Encoding]
<-- [Content-Type: text/html]
<-- []
<-- [<!DOCTYPE html>]
<-- [<html lang="en">]
<-- [ <head>]
<-- [ <meta charset="utf-8">]
<-- [ <title>Hello</title>]
<-- [ </head>]
<-- [ <body>]
<-- [ <h1>Hello!</h1>]
<-- [ <p>A static page served by the web server.</p>]
<-- [ </body>]
<-- [</html>]
|
Agora temos o essencial para programar um cliente TCP que solicite uma URL.
16.4.3. Exemplo 3

O script [inet/http/http-01.php] é um cliente HTTP configurado pelo arquivo JSON [config-http-01.json]. O conteúdo deste último é o seguinte:
| {
"localhost": {
"port": 80,
"GET": "/php8-oct-2026/scripts-console/inet/http/pages/hello.html",
"Host": "localhost:80",
"User-Agent": "client PHP",
"Accept": "text/html",
"Accept-Language": "en",
"Connection": "close",
"endOfLine": "\r\n"
}
}
|
- linha 2: o nome da máquina que hospeda o servidor web a ser acessado;
- linha 3: a porta em que esse servidor web opera;
- linha 4: a URL do documento desejado;
- linha 5: a máquina de destino no formato máquina:porta;
- linha 6: o identificador do cliente HTTP: você pode informar o que quiser;
- linha 7: o tipo de documento aceito pelo cliente, neste caso HTML em texto;
- linha 8: o idioma desejado para o documento solicitado;
- linha 9: instrui-se o servidor a fechar a conexão depois que o documento for enviado. Sem esse cabeçalho, um servidor HTTP/1.1 mantém a conexão aberta por alguns segundos aguardando outra requisição, e nosso cliente — que lê até que a conexão seja fechada — esperaria desnecessariamente;
- linha 10: o caractere de fim de linha dos comandos enviados pelo cliente. O protocolo HTTP exige a sequência \r\n.
O script [http-01.php] é o seguinte:
| <?php
declare(strict_types=1);
// cliente HTTP básico: solicita um documento a um servidor web e o salva em um arquivo
// o arquivo de configuração pode ser passado como argumento (php http-01.php config.json)
$configFileName = $argv[1] ?? "config-http-01.json";
// recuperamos a configuração
$config = json_decode(file_get_contents($configFileName), true);
// obtém o texto HTML das URLs do arquivo de configuração
foreach ($config as $site => $protocol) {
// leitura da URL do site $site
$result = getURL($site, $protocol);
// exibição do resultado
print "$result\n";
}
// --------------------------------------------------------------------------
function getURL(string $site, array $protocol, bool $tracking = true): string
{
// lê a URL $protocol["GET"] do site $site e a armazena no arquivo output/$site.html
// o diálogo cliente / servidor segue o protocolo $protocol
//
// abertura de uma conexão na porta $protocol["port"] de $site
$connection = @stream_socket_client("tcp://$site:{$protocol["port"]}", $errorNumber, $error, 10);
// retorna se houver erro
if ($connection === false) {
return "Failed to connect to the site [$site:{$protocol["port"]}]: $error";
}
// $connection representa um fluxo de comunicação bidirecional
// entre o cliente (este programa) e o servidor web contatado
// este canal é usado para a troca de comandos e informações
// o protocolo de diálogo é o HTTP
//
// criação do arquivo output/$site.html
if (!is_dir("output")) {
mkdir("output");
}
$html = fopen("output/$site.html", "w");
if ($html === false) {
fclose($connection);
return "Error while creating the file [output/$site.html]";
}
// o cliente vai iniciar o diálogo HTTP com o servidor
if ($tracking) {
print "Client: start of the communication with the server [$site] ----------------------------\n";
}
// as linhas enviadas pelo cliente devem terminar com \r\n
$endOfLine = $protocol["endOfLine"];
// por simplicidade, os casos de erro na comunicação cliente / servidor não são testados
// o cliente envia o comando GET para solicitar a URL $protocol["GET"]
// sintaxe GET URL HTTP/1.1
$command = "GET {$protocol["GET"]} HTTP/1.1$endOfLine";
if ($tracking) {
print "--> $command";
}
fwrite($connection, $command);
// envio dos outros cabeçalhos HTTP
foreach ($protocol as $verb => $value) {
if (!in_array($verb, ["GET", "port", "endOfLine"], true)) {
// construímos o comando
$command = "$verb: $value$endOfLine";
if ($tracking) {
print "--> $command";
}
// enviamos o comando ao servidor
fwrite($connection, $command);
}
}
// os cabeçalhos do protocolo HTTP devem terminar com uma linha vazia
fwrite($connection, $endOfLine);
//
// o servidor vai agora responder no canal $connection. Ele enviará todos
// os seus dados e depois fechará o canal (Connection: close). O cliente lê portanto tudo
// o que vier de $connection até que o canal seja fechado
//
// lemos primeiro os cabeçalhos HTTP enviados pelo servidor
// eles também terminam com uma linha vazia
if ($tracking) {
print "Response of the server [$site] ----------------------------\n";
}
while (($line = fgets($connection)) !== false) {
// removemos os espaços de fim de linha (incluindo \r\n)
$line = rtrim($line);
// temos a linha vazia que encerra os cabeçalhos?
if ($line === "") {
break;
}
// exibimos o cabeçalho HTTP
if ($tracking) {
print "<-- $line\n";
}
}
// lemos o documento HTML que segue a linha vazia e o armazenamos no arquivo
while (($line = fgets($connection)) !== false) {
fwrite($html, $line);
}
// o servidor fechou a conexão - o cliente a fecha por sua vez
fclose($connection);
fclose($html);
// retorno
return "End of the communication with the site [$site]. Check the file [output/$site.html]";
}
|
Comentários sobre o código:
- linha 7: o arquivo de configuração pode ser passado como argumento. Usaremos vários arquivos de configuração;
- linha 10: o arquivo de configuração é usado para criar um dicionário:
- as chaves do dicionário são os servidores web a serem consultados;
- os valores especificam o protocolo HTTP a ser usado;
- linha 12: o programa percorre a lista de servidores web da configuração;
- linha 20: a função [getURL($site, $protocol, $tracking)] solicita um documento do site $site e o armazena no arquivo de texto [output/$site.html]. Por padrão, as trocas cliente/servidor são exibidas no console ($tracking=true);
- linha 26: a função [stream_socket_client] estabelece uma conexão com um serviço TCP / IP em execução na porta [port] da máquina $site. Uma vez aberta a conexão cliente/servidor, muitos serviços TCP / IP trocam linhas de texto. É o caso aqui com o protocolo HTTP. O fluxo de dados do servidor para o cliente pode então ser tratado como um arquivo de texto lido com [fgets]. O mesmo vale para o fluxo de dados do cliente para o servidor, que pode ser escrito com [fwrite];
- linha 40: criação do arquivo [output/$site.html], no qual será armazenado o documento HTML recebido;
- linha 54: o primeiro comando do cliente deve ser [GET URL HTTP/1.1]. Significa: "quero obter (GET) a página [URL] do site ao qual estou conectado. Estou usando o protocolo HTTP, versão 1.1";
- linhas 60–70: as demais linhas do protocolo HTTP [Host, User-Agent, Accept, Accept-Language, Connection] são enviadas. A ordem delas não importa. O curso de PHP 7 testava as chaves a excluir uma a uma; a função [in_array] com o terceiro parâmetro [true] (comparação estrita) é mais legível;
- linha 72: uma linha vazia é enviada ao servidor para indicar que o cliente terminou de enviar seus cabeçalhos HTTP e agora aguarda o documento solicitado;
- linhas 83–94: o servidor enviará primeiro uma série de cabeçalhos HTTP que fornecem diversos detalhes sobre o documento solicitado. Esses cabeçalhos terminam com uma linha em branco. Lemos uma linha com [fgets], removemos os espaços em branco finais (inclusive \r\n) com [rtrim] e verificamos se é a linha em branco que marca o fim dos cabeçalhos. Se não for, o cabeçalho é exibido;
- linhas 95–97: as linhas de texto do documento podem ser lidas uma a uma com um laço while e salvas no arquivo de texto [output/$site.html]. Depois que o servidor web envia o documento inteiro, ele fecha a conexão com o cliente. No lado do cliente, isso será detectado como o fim do arquivo: [fgets] passa a retornar [false].
Vamos executar o script em um terminal aberto na pasta [inet/http]. O console exibe os seguintes logs:
| > php http-01.php
Client: start of the communication with the server [localhost] ----------------------------
--> GET /php8-oct-2026/scripts-console/inet/http/pages/hello.html HTTP/1.1
--> Host: localhost:80
--> User-Agent: client PHP
--> Accept: text/html
--> Accept-Language: en
--> Connection: close
Response of the server [localhost] ----------------------------
<-- HTTP/1.1 200 OK
<-- Date: Thu, 01 Oct 2026 16:47:43 GMT
<-- Server: Apache/2.4.58 (Ubuntu)
<-- Last-Modified: Thu, 01 Oct 2026 15:02:24 GMT
<-- ETag: "e2-65cc8b40e550d"
<-- Accept-Ranges: bytes
<-- Content-Length: 226
<-- Vary: Accept-Encoding
<-- Connection: close
<-- Content-Type: text/html
End of the communication with the site [localhost]. Check the file [output/localhost.html]
|
Em nosso exemplo, o arquivo recebido [output/localhost.html] é o seguinte:
| <!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Hello</title>
</head>
<body>
<h1>Hello!</h1>
<p>A static page served by the web server.</p>
</body>
</html>
|
Este é de fato o documento [hello.html]: é também o que um navegador exibe.
16.4.4. Exemplo 4
Neste exemplo, mostraremos que o cliente HTTP que escrevemos é insuficiente.
16.4.4.1. O protocolo HTTPS
Vamos atualizar o arquivo de configuração. O arquivo [config-http-01-https.json] é o seguinte:
| {
"localhost": {
"port": 443,
"GET": "/php8-oct-2026/scripts-console/inet/http/pages/hello.html",
"Host": "localhost:443",
"User-Agent": "client PHP",
"Accept": "text/html",
"Accept-Language": "en",
"Connection": "close",
"endOfLine": "\r\n"
}
}
|
Aqui, solicitaremos o documento [hello.html] na porta 443 do servidor [localhost]. A porta 443 é a porta usada pelo protocolo HTTP seguro, conhecido como HTTPS. Nesse protocolo, o diálogo cliente-servidor começa com uma troca de informações que protege a conexão: ela será criptografada pelo protocolo TLS. O cliente deve, portanto, usar o protocolo HTTPS em vez do protocolo HTTP, o que nosso cliente não faz.
O servidor Apache do [Laragon] suporta o protocolo HTTPS, mas ele não está ativado por padrão. A ativação é feita pelo menu do [Laragon]: clique com o botão direito na janela do [Laragon] e depois selecione [Apache / SSL / Enabled]. O servidor Apache é então reiniciado e passa a escutar em duas portas: a porta 80 (HTTP) e a porta 443 (HTTPS). O [Laragon] gerou para ele um certificado chamado autoassinado. Voltaremos a esse ponto no próximo capítulo.
Com este arquivo de configuração ([php http-01.php config-http-01-https.json]), a saída do console é a seguinte:
| > php http-01.php config-http-01-https.json
Client: start of the communication with the server [localhost] ----------------------------
--> GET /php8-oct-2026/scripts-console/inet/http/pages/hello.html HTTP/1.1
--> Host: localhost:443
--> User-Agent: client PHP
--> Accept: text/html
--> Accept-Language: en
--> Connection: close
Response of the server [localhost] ----------------------------
<-- HTTP/1.1 400 Bad Request
<-- Date: Thu, 01 Oct 2026 16:47:43 GMT
<-- Server: Apache/2.4.58 (Ubuntu)
<-- Content-Length: 438
<-- Connection: close
<-- Content-Type: text/html; charset=iso-8859-1
End of the communication with the site [localhost]. Check the file [output/localhost.html]
|
- [HTTP/1.1 400 Bad Request]: o servidor respondeu que a requisição do cliente era inválida.
O conteúdo do arquivo [output/localhost.html] é o seguinte:
| <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>400 Bad Request</title>
</head><body>
<h1>Bad Request</h1>
<p>Your browser sent a request that this server could not understand.<br />
Reason: You're speaking plain HTTP to an SSL-enabled server port.<br />
Instead use the HTTPS scheme to access this URL, please.<br />
</p>
<hr>
<address>Apache/2.4.58 (Ubuntu) Server at 127.0.0.1 Port 443</address>
</body></html>
|
O servidor diz claramente que não usamos o protocolo correto: "You’re speaking plain HTTP to an SSL-enabled server port" (você está falando HTTP puro com uma porta reservada ao SSL, o antigo nome do TLS).
16.4.4.2. Documento enviado em chunks
A pasta [inet/http/pages] contém um segundo documento, o script PHP [index.php]:
| <?php
declare(strict_types=1);
// uma página enviada em várias partes: [flush] força o envio imediato do que já foi escrito
// o servidor, portanto, não conhece o tamanho total do documento ao enviar os cabeçalhos
print "<!DOCTYPE html>\n<html lang=\"en\">\n<head><meta charset=\"utf-8\"><title>Chunks</title></head>\n<body>\n";
flush();
for ($i = 1; $i <= 3; $i++) {
print "<p>chunk no. $i</p>\n";
flush();
}
print "</body>\n</html>\n";
|
- Linha 8: a função [flush] instrui o servidor a enviar imediatamente ao cliente tudo o que o script já escreveu. Como resultado, o script envia seu documento em cinco partes separadas. Ao enviar os cabeçalhos HTTP da resposta, o servidor, portanto, não conhece o tamanho total do documento.
Agora vamos usar o seguinte arquivo de configuração [config-http-01-chunks.json]:
| {
"localhost": {
"port": 80,
"GET": "/php8-oct-2026/scripts-console/inet/http/pages/",
"Host": "localhost:80",
"User-Agent": "client PHP",
"Accept": "text/html",
"Accept-Language": "en",
"Connection": "close",
"endOfLine": "\r\n"
}
}
|
- Linha 4: solicitamos o arquivo [pages/]. O servidor Apache então envia seu documento padrão, neste caso [index.php].
A saída do console é a seguinte:
| > php http-01.php config-http-01-chunks.json
Client: start of the communication with the server [localhost] ----------------------------
--> GET /php8-oct-2026/scripts-console/inet/http/pages/ HTTP/1.1
--> Host: localhost:80
--> User-Agent: client PHP
--> Accept: text/html
--> Accept-Language: en
--> Connection: close
Response of the server [localhost] ----------------------------
<-- HTTP/1.1 200 OK
<-- Date: Thu, 01 Oct 2026 16:47:43 GMT
<-- Server: Apache/2.4.58 (Ubuntu)
<-- X-Powered-By: PHP/8.5.11
<-- Vary: Accept-Encoding
<-- Connection: close
<-- Transfer-Encoding: chunked
<-- Content-Type: text/html; charset=UTF-8
End of the communication with the site [localhost]. Check the file [output/localhost.html]
|
- O cabeçalho [X-Powered-By] indica que o documento foi gerado pelo PHP 8.5;
- o cabeçalho [Transfer-Encoding: chunked] indica que o servidor está enviando o documento em chunks. Não há cabeçalho [Content-Length]: o servidor não anuncia o tamanho do documento.
Isso resulta na presença de números no fluxo enviado ao cliente: cada chunk é precedido por uma linha que indica seu tamanho em hexadecimal, e o documento termina com um chunk de tamanho 0. Eis o arquivo [output/localhost.html]:
| 61
<!DOCTYPE html>
<html lang="en">
<head><meta charset="utf-8"><title>Chunks</title></head>
<body>
13
<p>chunk no. 1</p>
13
<p>chunk no. 2</p>
13
<p>chunk no. 3</p>
10
</body>
</html>
0
|
- [61]: o tamanho hexadecimal do primeiro chunk, que é de 97 bytes: as quatro primeiras linhas do documento;
- [13]: o tamanho dos três chunks seguintes, que é de 19 bytes;
- [10]: o tamanho do último chunk, 16 bytes;
- [0]: o chunk de 0 byte que encerra o documento.
Um cliente HTTP adequado não deveria deixar esses números no documento final.
16.4.4.3. Redirecionamento
Eis um último arquivo de configuração, [config-http-01-redirect.json]:
| {
"localhost": {
"port": 80,
"GET": "/php8-oct-2026/scripts-console/inet/http/pages",
"Host": "localhost:80",
"User-Agent": "client PHP",
"Accept": "text/html",
"Accept-Language": "en",
"Connection": "close",
"endOfLine": "\r\n"
}
}
|
Ele se parece com o exemplo anterior, mas a URL solicitada não termina com o caractere /. Não são a mesma URL. A execução do cliente HTTP produz então a seguinte saída no console:
| > php http-01.php config-http-01-redirect.json
Client: start of the communication with the server [localhost] ----------------------------
--> GET /php8-oct-2026/scripts-console/inet/http/pages HTTP/1.1
--> Host: localhost:80
--> User-Agent: client PHP
--> Accept: text/html
--> Accept-Language: en
--> Connection: close
Response of the server [localhost] ----------------------------
<-- HTTP/1.1 301 Moved Permanently
<-- Date: Thu, 01 Oct 2026 16:47:43 GMT
<-- Server: Apache/2.4.58 (Ubuntu)
<-- Location: http://localhost/php8-oct-2026/scripts-console/inet/http/pages/
<-- Content-Length: 346
<-- Connection: close
<-- Content-Type: text/html; charset=iso-8859-1
End of the communication with the site [localhost]. Check the file [output/localhost.html]
|
- [HTTP/1.1 301 Moved Permanently]: o código 301 indica que o documento solicitado foi movido permanentemente para a URL;
- [Location: ...]: a nova URL. Observe o caractere / no final desta vez: [pages] é um diretório, e o servidor Apache instrui o cliente a referenciá-lo como uma URL terminada em /.
O arquivo [output/localhost.html] fica então assim:
| <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>301 Moved Permanently</title>
</head><body>
<h1>Moved Permanently</h1>
<p>The document has moved <a href="http://localhost/php8-oct-2026/scripts-console/inet/http/pages/">here</a>.</p>
<hr>
<address>Apache/2.4.58 (Ubuntu) Server at localhost Port 80</address>
</body></html>
|
Um cliente HTTP deveria ser capaz de seguir os redirecionamentos. Neste caso, ele deveria solicitar automaticamente a nova URL [http://localhost/php8-oct-2026/scripts-console/inet/http/pages/].
16.4.5. Exemplo 5
Os exemplos anteriores mostraram que nosso cliente HTTP era insuficiente. Vamos agora apresentar uma ferramenta chamada [curl] que permite obter documentos web tratando os problemas mencionados: o protocolo HTTPS, documentos enviados em chunks, redirecionamentos… A ferramenta [curl] está incluída no Windows (a partir do Windows 10) e no [Laragon]. Em um terminal PowerShell, é preciso digitar [curl.exe], e não [curl]: no PowerShell 5, [curl] é um alias de outro comando, [Invoke-WebRequest].
O comando [curl --help] exibe as principais opções de configuração do [curl]. Há várias dezenas delas. Usaremos pouquíssimas. Para solicitar uma URL, basta digitar o comando [curl URL]. Esse comando exibirá o documento solicitado no console. Se você também quiser ver as trocas HTTP entre o cliente e o servidor, digite [curl --verbose URL]. Por fim, para salvar o documento HTML solicitado em um arquivo, digite [curl --verbose --output file URL].
Para não poluir as pastas do curso, vamos entrar em uma pasta de trabalho — por exemplo, [c:\temp\curl] (crie-a se não existir) — e solicitar a página [hello.html]:
| > curl --verbose --output localhost.html http://localhost/php8-oct-2026/scripts-console/inet/http/pages/hello.html
* Host localhost:80 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0* Trying 127.0.0.1:80...
* Connected to localhost (127.0.0.1) port 80
> GET /php8-oct-2026/scripts-console/inet/http/pages/hello.html HTTP/1.1
> Host: localhost
> User-Agent: curl/8.5.0
> Accept: */*
>
< HTTP/1.1 200 OK
< Date: Thu, 01 Oct 2026 15:32:56 GMT
< Server: Apache/2.4.58 (Ubuntu)
< Last-Modified: Thu, 01 Oct 2026 15:02:24 GMT
< ETag: "e2-65cc8b40e550d"
< Accept-Ranges: bytes
< Content-Length: 226
< Vary: Accept-Encoding
< Content-Type: text/html
<
{ [226 bytes data]
100 226 100 226 0 0 306k 0 --:--:-- --:--:-- --:--:-- 230k
* Connection #0 to host localhost left intact
|
- as linhas que começam com [*] contêm informações do [curl]: ele encontrou dois endereços para [localhost], o endereço IPv6 [::1] e o endereço IPv4 [127.0.0.1], e se conectou ao segundo;
- as linhas que começam com [>] são as linhas enviadas pelo [curl] ao servidor [localhost]. O protocolo HTTP é reconhecido;
- as linhas que começam com [<] são as linhas enviadas em resposta pelo servidor;
- as demais linhas mostram a barra de progresso do download.
O arquivo [localhost.html] contém o documento solicitado. Você pode verificar isso abrindo o arquivo em um editor de texto.
Agora vamos solicitar a URL [https://localhost/php8-oct-2026/scripts-console/inet/http/pages/hello.html]. Para obter essa URL, o cliente HTTP precisa ser capaz de se comunicar em HTTPS. É o caso do cliente [curl]. Como o certificado do servidor é autoassinado, [curl] se recusaria a prosseguir. A opção [--insecure] o instrui a não verificar o certificado. A saída do console é a seguinte:
| > curl --verbose --insecure --output localhost-https.html https://localhost/php8-oct-2026/scripts-console/inet/http/pages/hello.html
* Host localhost:443 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0* Trying 127.0.0.1:443...
* Connected to localhost (127.0.0.1) port 443
* ALPN: curl offers h2,http/1.1
} [5 bytes data]
* TLSv1.3 (OUT), TLS handshake, Client hello (1):
} [512 bytes data]
* TLSv1.3 (IN), TLS handshake, Server hello (2):
{ [122 bytes data]
* TLSv1.3 (IN), TLS handshake, Encrypted Extensions (8):
{ [21 bytes data]
* TLSv1.3 (IN), TLS handshake, Certificate (11):
{ [822 bytes data]
* TLSv1.3 (IN), TLS handshake, CERT verify (15):
{ [264 bytes data]
* TLSv1.3 (IN), TLS handshake, Finished (20):
{ [52 bytes data]
* TLSv1.3 (OUT), TLS change cipher, Change cipher spec (1):
} [1 bytes data]
* TLSv1.3 (OUT), TLS handshake, Finished (20):
} [52 bytes data]
* SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384 / X25519 / RSASSA-PSS
* ALPN: server accepted http/1.1
* Server certificate:
* subject: CN=localhost
* start date: Oct 1 14:55:35 2026 GMT
* expire date: Sep 28 14:55:35 2036 GMT
* issuer: CN=localhost
* SSL certificate verify result: self-signed certificate (18), continuing anyway.
* Certificate level 0: Public key type RSA (2048/112 Bits/secBits), signed using sha256WithRSAEncryption
* using HTTP/1.x
} [5 bytes data]
> GET /php8-oct-2026/scripts-console/inet/http/pages/hello.html HTTP/1.1
> Host: localhost
> User-Agent: curl/8.5.0
> Accept: */*
>
{ [5 bytes data]
* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
{ [57 bytes data]
* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
{ [57 bytes data]
* old SSL session ID is stale, removing
{ [5 bytes data]
< HTTP/1.1 200 OK
< Date: Thu, 01 Oct 2026 15:32:56 GMT
< Server: Apache/2.4.58 (Ubuntu)
< Last-Modified: Thu, 01 Oct 2026 15:02:24 GMT
< ETag: "e2-65cc8b40e550d"
< Accept-Ranges: bytes
< Content-Length: 226
< Vary: Accept-Encoding
< Content-Type: text/html
<
{ [226 bytes data]
100 226 100 226 0 0 45798 0 --:--:-- --:--:-- --:--:-- 47200
* Connection #0 to host localhost left intact
|
- as linhas [TLSv1.3 ...] mostram as trocas cliente/servidor para proteger a conexão: a conexão será criptografada;
- as linhas [Server certificate] descrevem o certificado enviado pelo servidor. Ele foi emitido para a máquina [localhost] (CN=localhost) por essa mesma máquina (issuer: CN=localhost): trata-se de um certificado autoassinado. [curl] informa que não conseguiu verificar o certificado, mas continua mesmo assim;
- Em seguida vêm as trocas criptografadas habituais, HTTP. [HTTP/1.1 200 OK]: o documento solicitado foi encontrado.
Agora vamos solicitar a URL [http://localhost/php8-oct-2026/scripts-console/inet/http/pages]. Havíamos visto que, para essa URL, havia um redirecionamento para a mesma URL terminada com o caractere /. A saída do console é então a seguinte:
| > curl --verbose --location --output pages.html http://localhost/php8-oct-2026/scripts-console/inet/http/pages
* Host localhost:80 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0* Trying 127.0.0.1:80...
* Connected to localhost (127.0.0.1) port 80
> GET /php8-oct-2026/scripts-console/inet/http/pages HTTP/1.1
> Host: localhost
> User-Agent: curl/8.5.0
> Accept: */*
>
< HTTP/1.1 301 Moved Permanently
< Date: Thu, 01 Oct 2026 15:32:56 GMT
< Server: Apache/2.4.58 (Ubuntu)
< Location: http://localhost/php8-oct-2026/scripts-console/inet/http/pages/
< Content-Length: 346
< Content-Type: text/html; charset=iso-8859-1
<
* Ignoring the response-body
100 346 100 346 0 0 637k 0 --:--:-- --:--:-- --:--:-- 337k
* Connection #0 to host localhost left intact
* Issue another request to this URL: 'http://localhost/php8-oct-2026/scripts-console/inet/http/pages/'
* Found bundle for host: 0x562ea38dc400 [serially]
* Can not multiplex, even if we wanted to
* Re-using existing connection with host localhost
> GET /php8-oct-2026/scripts-console/inet/http/pages/ HTTP/1.1
> Host: localhost
> User-Agent: curl/8.5.0
> Accept: */*
>
< HTTP/1.1 200 OK
< Date: Thu, 01 Oct 2026 15:32:56 GMT
< Server: Apache/2.4.58 (Ubuntu)
< X-Powered-By: PHP/8.5.11
< Vary: Accept-Encoding
< Transfer-Encoding: chunked
< Content-Type: text/html; charset=UTF-8
<
{ [97 bytes data]
100 170 0 170 0 0 147k 0 --:--:-- --:--:-- --:--:-- 147k
* Connection #0 to host localhost left intact
|
- Usamos a opção [--location] para indicar que queremos seguir os redirecionamentos enviados pelo servidor;
- [HTTP/1.1 301 Moved Permanently] e [Location]: o servidor indica que o documento solicitado está em outra URL;
- [Issue another request to this URL]: [curl] envia uma nova requisição, desta vez para a nova URL, reutilizando a mesma conexão;
- [HTTP/1.1 200 OK]: o servidor responde que encontrou o documento solicitado;
- [Transfer-Encoding: chunked]: ele o envia em chunks. [curl] remove os tamanhos dos chunks.
O documento solicitado será encontrado no arquivo [pages.html].
16.4.6. Exemplo 6
O PHP tem uma extensão chamada [curl] que permite usar as capacidades da ferramenta [curl] dentro de um programa PHP. Ela está ativada no PHP do [Laragon]: isso pode ser verificado com o comando [php -m], que lista as extensões carregadas. Se ela não estivesse ativada, seria preciso descomentar a linha [extension=curl] no arquivo [php.ini].
Escreveremos um script chamado [http-02.php] que usará o seguinte arquivo de configuração JSON [config-http-02.json]:
| {
"localhost": {
"timeout": 5,
"url": "http://localhost/php8-oct-2026/scripts-console/inet/http/pages"
},
"localhost-https": {
"timeout": 5,
"url": "https://localhost/php8-oct-2026/scripts-console/inet/http/pages/hello.html",
"verify-peer": false
}
}
|
Cada entrada do dicionário [key => value] tem a seguinte estrutura:
- key: um nome que será usado para nomear o arquivo onde o documento será salvo;
- value: um dicionário com as seguintes chaves:
- timeout: tempo máximo de espera por uma resposta do servidor. Passado esse tempo, o cliente se desconecta;
- url: URL do documento solicitado;
- verify-peer: o certificado do servidor (HTTPS) deve ser verificado? True por padrão.
O código do script [http-02.php] é o seguinte:
| <?php
declare(strict_types=1);
// cliente HTTP escrito com a extensão [curl] do PHP
// pode falar HTTPS, seguir redirecionamentos e receber um documento enviado em chunks
// constantes
const CONFIG_FILE_NAME = "config-http-02.json";
// recuperamos a configuração
$config = json_decode(file_get_contents(CONFIG_FILE_NAME), true);
// obtém o texto HTML das URLs do arquivo de configuração
foreach ($config as $site => $info) {
// leitura da URL do site $site
$result = getUrl($site, $info["url"], $info["timeout"], $info["verify-peer"] ?? true);
// exibição do resultado
print "$result\n";
}
// --------------------------------------------------------------------------
function getUrl(string $site, string $url, int $timeout, bool $verifyPeer = true): string
{
// lê a URL $url e a armazena no arquivo output/$site.html
//
// acompanhamento
print "Client: start of the communication with the server [$site] ----------------------------\n";
// inicialização de uma sessão cURL: desde o PHP 8.0, [curl_init] retorna um objeto [CurlHandle]
$curl = curl_init($url);
if ($curl === false) {
return "Error while initializing the cURL session for the site [$site]";
}
// opções do curl
$options = [
// modo verboso: as trocas cliente / servidor são exibidas...
CURLOPT_VERBOSE => true,
// ... na saída padrão (por padrão, é a saída de erro)
CURLOPT_STDERR => STDOUT,
// nova conexão - sem cache
CURLOPT_FRESH_CONNECT => true,
// timeout da requisição (em segundos)
CURLOPT_TIMEOUT => $timeout,
CURLOPT_CONNECTTIMEOUT => $timeout,
// verificar ou não a validade do certificado do servidor (HTTPS)
CURLOPT_SSL_VERIFYPEER => $verifyPeer,
CURLOPT_SSL_VERIFYHOST => $verifyPeer ? 2 : 0,
// seguir os redirecionamentos
CURLOPT_FOLLOWLOCATION => true,
// recuperação do documento solicitado como string
CURLOPT_RETURNTRANSFER => true,
];
// configuração do curl
curl_setopt_array($curl, $options);
// execução da requisição
$pageContent = curl_exec($curl);
// a sessão cURL é fechada automaticamente quando o objeto $curl desaparece
// ([curl_close] é inútil desde o PHP 8.0 e obsoleta desde o PHP 8.5)
//
// uso do resultado
if ($pageContent === false) {
// houve um erro de comunicação
return "Error communicating with the server [$site]: " . curl_error($curl);
}
// salvamento do resultado em output/$site.html
if (!is_dir("output")) {
mkdir("output");
}
if (file_put_contents("output/$site.html", $pageContent) === false) {
return "Error while creating the file [output/$site.html]";
}
// retorno bem-sucedido
return "End of the communication with the server [$site]. Check the file [output/$site.html]";
}
|
Comentários:
- linha 12: o arquivo de configuração é usado para criar o dicionário [$config];
- linha 15: percorremos a lista de sites encontrada na configuração;
- linha 17: para cada site, a função [getUrl] é chamada para baixar a URL [$info["url"]] com um timeout de [$info["timeout"]];
- linha 30: uma sessão [curl] é iniciada. [curl_init] ainda não se conecta ao servidor web. A partir do PHP 8.0, ela retorna um objeto da classe [CurlHandle] (em vez de um resource), que servirá de parâmetro para todas as funções [curl] seguintes. Se a inicialização da sessão falhar, a função retorna o booleano [false];
- linhas 35–52: o dicionário [$options] configura a conexão [curl] com o servidor:
- [CURLOPT_VERBOSE]: exibe as trocas cliente/servidor, de forma semelhante à opção [--verbose] da ferramenta [curl]. [CURLOPT_STDERR] as envia para a saída padrão ([STDOUT]) em vez da saída de erro, o que preserva a ordem das exibições;
- [CURLOPT_SSL_VERIFYPEER] e [CURLOPT_SSL_VERIFYHOST]: verificam o certificado do servidor e o nome nele contido;
- [CURLOPT_FOLLOWLOCATION]: segue os redirecionamentos, de forma semelhante à opção [--location];
- [CURLOPT_RETURNTRANSFER]: retorna o documento recebido como uma string;
- linha 54: as opções de conexão são passadas ao objeto [$curl];
- linha 56: conexão à URL solicitada com as opções definidas. Por causa da opção [CURLOPT_RETURNTRANSFER => true], a função [curl_exec] retorna o documento enviado pelo servidor como uma string, sem os tamanhos dos chunks caso tenha sido enviado em chunks. A função [curl_exec] retorna o valor booleano [false] se a conexão falhar. A função [curl_error] retorna então a causa do erro;
- linha 57: o curso de PHP 7 fechava a sessão com a função [curl_close]. Desde o PHP 8.0, essa função não faz mais nada: a sessão é fechada quando o objeto [CurlHandle] deixa de ser usado. Ela está obsoleta (deprecated) desde o PHP 8.5;
- Linha 69: a página recebida é salva em um arquivo local.
Quando o script [http-02.php] é executado, a seguinte saída é exibida no console:
| > php http-02.php
Client: start of the communication with the server [localhost] ----------------------------
* Host localhost:80 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
* Trying 127.0.0.1:80...
* Connected to localhost (127.0.0.1) port 80
> GET /php8-oct-2026/scripts-console/inet/http/pages HTTP/1.1
Host: localhost
Accept: */*
< HTTP/1.1 301 Moved Permanently
< Date: Thu, 01 Oct 2026 16:47:51 GMT
< Server: Apache/2.4.58 (Ubuntu)
< Location: http://localhost/php8-oct-2026/scripts-console/inet/http/pages/
< Content-Length: 346
< Content-Type: text/html; charset=iso-8859-1
<
* Ignoring the response-body
* Connection #0 to host localhost left intact
* Issue another request to this URL: 'http://localhost/php8-oct-2026/scripts-console/inet/http/pages/'
* Found bundle for host: 0x557b108f4920 [serially]
* Can not multiplex, even if we wanted to
* Re-using existing connection with host localhost
> GET /php8-oct-2026/scripts-console/inet/http/pages/ HTTP/1.1
Host: localhost
Accept: */*
< HTTP/1.1 200 OK
< Date: Thu, 01 Oct 2026 16:47:51 GMT
< Server: Apache/2.4.58 (Ubuntu)
< X-Powered-By: PHP/8.5.11
< Vary: Accept-Encoding
< Transfer-Encoding: chunked
< Content-Type: text/html; charset=UTF-8
<
* Connection #0 to host localhost left intact
End of the communication with the server [localhost]. Check the file [output/localhost.html]
Client: start of the communication with the server [localhost-https] ----------------------------
* Host localhost:443 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
* Trying 127.0.0.1:443...
* Connected to localhost (127.0.0.1) port 443
* ALPN: curl offers h2,http/1.1
* SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384 / X25519 / RSASSA-PSS
* ALPN: server accepted http/1.1
* Server certificate:
* subject: CN=localhost
* start date: Oct 1 14:55:35 2026 GMT
* expire date: Sep 28 14:55:35 2036 GMT
* issuer: CN=localhost
* SSL certificate verify result: self-signed certificate (18), continuing anyway.
* Certificate level 0: Public key type RSA (2048/112 Bits/secBits), signed using sha256WithRSAEncryption
* using HTTP/1.x
> GET /php8-oct-2026/scripts-console/inet/http/pages/hello.html HTTP/1.1
Host: localhost
Accept: */*
* old SSL session ID is stale, removing
< HTTP/1.1 200 OK
< Date: Thu, 01 Oct 2026 16:47:51 GMT
< Server: Apache/2.4.58 (Ubuntu)
< Last-Modified: Thu, 01 Oct 2026 15:02:24 GMT
< ETag: "e2-65cc8b40e550d"
< Accept-Ranges: bytes
< Content-Length: 226
< Vary: Accept-Encoding
< Content-Type: text/html
<
* Connection #0 to host localhost left intact
End of the communication with the server [localhost-https]. Check the file [output/localhost-https.html]
|
Ocorrem as mesmas trocas de dados que com a ferramenta [curl]: as linhas que começam com [>] são enviadas ao servidor; as que começam com [<] são recebidas do servidor; e as que começam com [*] contêm informações do [curl]. O redirecionamento foi seguido e a conexão HTTPS foi estabelecida.
16.4.7. Conclusão
Nesta seção, exploramos o protocolo HTTP e escrevemos um script [http-02.php] capaz de baixar uma URL da web. No próximo capítulo, usaremos para isso o componente [HttpClient] do framework Symfony.
16.5. O protocolo SMTP (Simple Mail Transfer Protocol)
16.5.1. Introdução

Neste capítulo:
- [Server B] será um servidor SMTP local que instalaremos;
- [Client A] será um cliente SMTP em diversas formas:
- o cliente [tcp-client.php] para descobrir o protocolo SMTP;
- um script PHP que reproduz o protocolo SMTP descoberto com [tcp-client.php];
- um script PHP que usa a biblioteca [Symfony Mailer] para enviar todo tipo de e-mail.
16.5.2. Instalação de um servidor SMTP de teste: [Mailpit]
O curso de PHP 7 instalava o servidor de e-mail [hMailServer] — que não é mais mantido — e o configurava para retransmitir e-mails pelo servidor SMTP do Gmail. Em vez disso, usaremos o [Mailpit] (https://mailpit.axllent.org), uma ferramenta gratuita projetada para desenvolvedores:
- ele é um servidor SMTP que aceita todos os e-mails enviados a ele, independentemente do remetente ou do destinatário, mas não os encaminha — ele os armazena. Isso significa que você pode enviar e-mails para qualquer endereço sem o risco de incomodar ninguém;
- ele oferece uma interface web que permite ler os e-mails recebidos;
- ele também fornece um servidor POP3, que usaremos para ler e-mails programaticamente;
- é um único arquivo executável que não requer instalação.
O [Mailpit] pode ser baixado em https://github.com/axllent/mailpit/releases. No Windows, baixe o arquivo [mailpit-windows-amd64.zip] da versão mais recente e copie o arquivo [mailpit.exe] que ele contém para a pasta [inet/mailpit] do código do curso. Essa pasta já contém os seguintes arquivos:
| mailpit
├── mailpit.bat
├── mailpit-secure.bat
├── pop3-users.txt
├── relay.yml
└── smtp-users.txt
|
O arquivo [pop3-users.txt] define os usuários do servidor POP3 do [Mailpit] na forma [user:password]. Há apenas um:
O arquivo [mailpit.bat] inicia o [Mailpit] com esse arquivo de usuários:
| @echo off
rem main instance of Mailpit: SMTP on port 1025, POP3 on port 1110, web interface on port 8025
"%~dp0mailpit.exe" --pop3-auth-file "%~dp0pop3-users.txt"
|
- [%~dp0] especifica a pasta do arquivo [.bat]: portanto, você pode iniciar [mailpit.bat] a partir de qualquer pasta, por exemplo, dando um clique duplo nele no Windows Explorer;
- a opção [--pop3-auth-file] inicia o servidor POP3 do [Mailpit].
Você também pode digitar o comando diretamente em um terminal aberto na pasta [inet/mailpit]: [.\mailpit.exe --pop3-auth-file pop3-users.txt]. O [Mailpit] exibirá então linhas de log indicando que oferece três serviços:
- um servidor SMTP na porta 1025 (a porta padrão do protocolo SMTP é a 25, mas as portas abaixo de 1024 costumam ser reservadas ou bloqueadas);
- um servidor POP3 na porta 1110 (a porta padrão é a 110);
- uma interface web para a URL [http://localhost:8025].
O terminal deve permanecer aberto enquanto você quiser usar o [Mailpit]: a combinação de teclas [Ctrl-C] o encerra. Os e-mails recebidos ficam armazenados na memória enquanto o [Mailpit] estiver em execução. Veremos o [Mailpit] novamente em versões futuras do servidor de cálculo de impostos, que enviarão e-mails ao seu administrador.
O segundo arquivo, [mailpit-secure.bat], inicia uma segunda instância do [Mailpit], que usaremos mais adiante para examinar conexões seguras:
| @echo off
rem secure instance of Mailpit: SMTP with mandatory STARTTLS and authentication on port 1587,
rem web interface over HTTPS on port 8026, relay of the messages to the main instance (port 1025)
"%~dp0mailpit.exe" --smtp 0.0.0.0:1587 --listen 0.0.0.0:8026 --ui-tls-cert sans:localhost --ui-tls-key sans:localhost --smtp-tls-cert sans:localhost --smtp-tls-key sans:localhost --smtp-require-starttls --smtp-auth-file "%~dp0smtp-users.txt" --smtp-relay-config "%~dp0relay.yml" --smtp-relay-all
|
- [--smtp 0.0.0.0:1587]: o servidor SMTP desta instância escuta na porta 1587;
- [--listen 0.0.0.0:8026 --ui-tls-cert sans:localhost --ui-tls-key sans:localhost]: sua interface web fica na porta 8026 (a porta 8025 está ocupada pela primeira instância), em HTTPS;
- [--smtp-tls-cert sans:localhost --smtp-tls-key sans:localhost]: o [Mailpit] gera seu próprio certificado autoassinado para a máquina [localhost]. Esse certificado permite criptografar as comunicações com seus clientes;
- [--smtp-require-starttls]: os clientes devem criptografar a conexão (com o comando STARTTLS, que veremos mais adiante) antes de enviar um e-mail;
- [--smtp-auth-file smtp-users.txt]: os clientes devem se autenticar usando uma das contas do arquivo [smtp-users.txt]. Há apenas uma: [guest@localhost] com a senha [guest];
- [--smtp-relay-config relay.yml --smtp-relay-all]: os e-mails recebidos são encaminhados ao servidor SMTP definido em [relay.yml], ou seja, à primeira instância do [Mailpit] (localhost, porta 1025):
| # relay SMTP da instância "secure" do Mailpit (porta 1587)
# para a instância principal (porta 1025)
host: localhost
port: 1025
|
Esta segunda instância se comporta como um servidor SMTP público, como o do Gmail ([smtp.gmail.com], porta 587), que também exige uma conexão criptografada e autenticação. Vamos usá-la com uma conta do Gmail no momento oportuno, para quem tiver uma.
Vamos iniciar a primeira instância do [Mailpit] e abrir sua interface web [http://localhost:8025] em um navegador:

Veremos esta página se encher à medida que percorrermos os exemplos.
16.5.3. O protocolo SMTP

Vamos explorar o protocolo SMTP usando o seguinte ambiente:
- o cliente A será o cliente TCP genérico ([tcp-client.php]);
- o servidor B será o servidor SMTP do [Mailpit];
- o cliente A pedirá ao servidor B que entregue um e-mail ao usuário [guest@localhost];
- verificaremos pela interface web do [Mailpit] que o e-mail foi recebido com sucesso.
Em uma janela de terminal aberta na pasta [inet/utilities], iniciamos o cliente e digitamos os comandos do protocolo SMTP:
| > php tcp-client.php --quit bye localhost 1025
Client [127.0.0.1:50072] connected to the server [localhost:1025]
Type your commands (bye to stop):
<-- [220 vm Mailpit ESMTP Service ready]
EHLO localhost
<-- [250-vm greets localhost]
<-- [250-SIZE 52428800]
<-- [250-ENHANCEDSTATUSCODES]
<-- [250-8BITMIME]
<-- [250 SMTPUTF8]
MAIL FROM: <guest@localhost>
<-- [250 2.1.0 Ok]
RCPT TO: <guest@localhost>
<-- [250 2.1.5 Ok]
DATA
<-- [354 Start mail input; end with <CR><LF>.<CR><LF>]
Subject: test
From: guest@localhost
To: guest@localhost
line 1
line 2
.
<-- [250 2.0.0 Ok: queued as 0d0daBzXhAGBiM8Aw3oxZ7]
QUIT
<-- [221 2.0.0 vm Mailpit ESMTP Service closing transmission channel]
Connection with the server lost...
End of the client
|
- [php tcp-client.php --quit bye localhost 1025]: conectamo-nos à porta 1025 da máquina local, onde o serviço SMTP do [Mailpit] está em execução. O argumento [--quit bye] indica que o usuário sairá do programa digitando o comando [bye]. Sem esse argumento, o comando para encerrar o programa é [quit]. No entanto, [QUIT] também é um comando do protocolo SMTP. Precisamos, portanto, evitar essa ambiguidade;
- [220 vm Mailpit ESMTP Service ready]: assim que a conexão é estabelecida, o servidor envia sua mensagem de boas-vindas. O código [220] indica que o servidor está pronto. [vm] é o nome da máquina que executa o [Mailpit]: você verá o nome do seu computador;
- [EHLO localhost]: o cliente envia o comando [EHLO client-machine-name]. O servidor responde com uma série de linhas na forma [250-xx], sendo que a última tem a forma [250 xx] (um espaço, e não um hífen, após o código). O código [250] indica que o comando enviado pelo cliente foi bem-sucedido. As linhas seguintes listam as extensões do protocolo SMTP que o servidor suporta, como o tamanho máximo da mensagem [SIZE];
- [MAIL FROM: <guest@localhost>]: o cliente especifica o remetente da mensagem, e o servidor o aceita (código 250);
- [RCPT TO: <guest@localhost>]: o cliente especifica o destinatário da mensagem. Pode haver vários comandos [RCPT TO] para vários destinatários;
- [DATA]: este comando informa ao servidor que o cliente está prestes a enviar o conteúdo da mensagem. O servidor responde com o código [354] e especifica como encerrar a mensagem;
- O cliente então envia uma lista de linhas de texto terminada por uma linha contendo apenas um ponto. A mensagem pode começar com linhas [Subject:, From:, To:] para definir, respectivamente, o assunto da mensagem, o remetente e o destinatário. Esses cabeçalhos devem ser seguidos por uma linha em branco e, depois, pelo texto da mensagem;
- [250 2.0.0 Ok: queued as ...]: assim que o servidor recebe a linha contendo apenas um ponto, ele coloca a mensagem na fila de entrega;
- [QUIT]: o cliente avisa ao servidor que terminou. O servidor responde com o código [221] e então fecha a conexão, o que o cliente detecta.
Vamos verificar na interface web do [Mailpit] para confirmar que o usuário [guest@localhost] realmente recebeu a mensagem:

O remetente é [From], o destinatário é [To], o assunto é [Subject] e o texto da mensagem é exibido. A aba [Headers] exibe todos os cabeçalhos da mensagem, e a aba [Raw] exibe o texto puro recebido pelo [Mailpit].
Nosso cliente [tcp-client.php] enviou a mensagem com sucesso. Agora temos a base para criar um cliente SMTP escrito em PHP.
16.5.4. Um cliente SMTP básico escrito em PHP
Vamos reproduzir em PHP o que aprendemos antes sobre o protocolo SMTP.

O script [inet/smtp/smtp-01.php] é configurado pelo seguinte arquivo JSON [config-smtp-01.json]:
| {
"mail to localhost via localhost": {
"smtp-server": "localhost",
"smtp-port": 1025,
"from": "guest@localhost",
"to": "guest@localhost",
"subject": "to localhost via localhost",
"message": "line 1\nline 2\nline 3"
},
"mail to gmail via localhost": {
"smtp-server": "localhost",
"smtp-port": 1025,
"from": "guest@localhost",
"to": "php8parlexemple@gmail.com",
"subject": "to gmail via localhost",
"message": "line 1\nline 2\nline 3"
},
"mail via a secure server": {
"smtp-server": "localhost",
"smtp-port": 1587,
"from": "guest@localhost",
"to": "guest@localhost",
"subject": "via a secure server",
"message": "line 1\nline 2\nline 3"
}
}
|
[config-smtp-01.json] é um dicionário em que cada elemento tem a forma [name => info]. O valor [info] é, por sua vez, um dicionário com as seguintes chaves e valores:
- [smtp-server]: o nome do servidor SMTP a ser usado;
- [smtp-port]: o número da porta do serviço SMTP;
- [from]: o remetente da mensagem;
- [to]: o destinatário da mensagem;
- [subject]: o assunto da mensagem;
- [message]: a mensagem a ser enviada.
São enviadas três mensagens:
- a primeira usa o servidor SMTP do [Mailpit] para enviar um e-mail ao usuário [guest@localhost];
- a segunda usa o mesmo servidor para enviar um e-mail a um endereço do Gmail. O [Mailpit] reterá esse e-mail sem entregá-lo;
- a terceira usa a segunda instância do [Mailpit], a da porta 1587, que exige uma conexão criptografada. Portanto, [mailpit-secure.bat] deve ter sido iniciado.
O código [smtp-01.php] do cliente SMTP é o seguinte:
| <?php
declare(strict_types=1);
// cliente SMTP (Simple Mail Transfer Protocol) usado para enviar uma mensagem
// protocolo de comunicação cliente-servidor SMTP
// -> o cliente se conecta à porta do servidor SMTP (25, 587, 1025...)
// <- o servidor lhe envia uma mensagem de boas-vindas
// -> o cliente envia o comando EHLO nome de sua máquina
// <- o servidor responde OK ou não
// -> o cliente envia o comando MAIL FROM: <sender>
// <- o servidor responde OK ou não
// -> o cliente envia o comando RCPT TO: <recipient>
// <- o servidor responde OK ou não
// -> o cliente envia o comando DATA
// <- o servidor responde OK ou não
// -> o cliente envia todas as linhas de sua mensagem e termina com uma linha contendo o
// único caractere .
// <- o servidor responde OK ou não
// -> o cliente envia o comando QUIT
// <- o servidor responde OK ou não
// as respostas do servidor têm a forma xxx texto, em que xxx é um número de 3 dígitos. Qualquer
// número xxx >= 400 sinaliza um erro.
// A resposta pode ter várias linhas da forma xxx-texto, exceto a última
// que tem a forma xxx texto (espaço após o código)
// as linhas de texto trocadas devem terminar com os caracteres CR (13) e LF (10)
// os parâmetros de envio dos e-mails
const CONFIG_FILE_NAME = "config-smtp-01.json";
// recuperamos a configuração
$mails = json_decode(file_get_contents(CONFIG_FILE_NAME), true);
// envio dos e-mails
foreach ($mails as $name => $info) {
// acompanhamento
print "Sending the mail [$name]\n";
// envio do e-mail
$result = sendmail($info, verbose: true);
// exibição do resultado
print "$result\n";
}
// fim
print "Done\n";
// --------------------------------------------------------------------------
function sendmail(array $info, bool $verbose = true): string
{
// envia a mensagem descrita por [$info]
// se $verbose=true, acompanha as trocas cliente-servidor
//
// o nome da máquina cliente
$client = gethostname();
// abertura de uma conexão com o servidor SMTP
$connection = @stream_socket_client("tcp://{$info["smtp-server"]}:{$info["smtp-port"]}", $errorNumber, $error);
if ($connection === false) {
return "Failed to connect to the server [{$info["smtp-server"]}:{$info["smtp-port"]}]: $error";
}
// $connection representa um fluxo de comunicação bidirecional
// entre o cliente (este programa) e o servidor SMTP contatado
try {
// após a conexão, o servidor envia uma mensagem de boas-vindas que lemos
sendCommand($connection, "", $verbose);
// comando EHLO
sendCommand($connection, "EHLO $client", $verbose);
// comando MAIL FROM:
sendCommand($connection, "MAIL FROM: <{$info["from"]}>", $verbose);
// comando RCPT TO:
sendCommand($connection, "RCPT TO: <{$info["to"]}>", $verbose);
// comando DATA
sendCommand($connection, "DATA", $verbose);
// a mensagem: cabeçalhos (From, To, Subject), uma linha vazia, o texto
// e uma linha reduzida a um ponto
// os fins de linha do texto devem ser \r\n
$text = str_replace("\n", "\r\n", $info["message"]);
// uma linha do texto que começa com um ponto deve começar com dois pontos
$text = preg_replace('/^\./m', '..', $text);
$data = "From: {$info["from"]}\r\nTo: {$info["to"]}\r\nSubject: {$info["subject"]}\r\n\r\n$text\r\n.";
sendCommand($connection, $data, $verbose);
// comando QUIT
sendCommand($connection, "QUIT", $verbose);
return "Message sent";
} catch (RuntimeException $ex) {
// o servidor sinalizou um erro
return "Error: " . $ex->getMessage();
} finally {
// em todos os casos, fechamos a conexão
fclose($connection);
}
}
// --------------------------------------------------------------------------
function sendCommand($connection, string $command, bool $verbose): void
{
// envia $command ao canal $connection e lê a resposta do servidor
// modo verboso se $verbose=true
// lança uma RuntimeException se o servidor sinalizar um erro
//
// envio do comando se não estiver vazio
if ($command !== "") {
fwrite($connection, "$command\r\n");
if ($verbose) {
display($command, 1);
}
}
// leitura da resposta: linhas [xxx-texto] terminadas por uma linha [xxx texto]
do {
$response = fgets($connection);
if ($response === false) {
throw new RuntimeException("the server has closed the connection");
}
if ($verbose) {
display($response, 2);
}
} while (substr($response, 3, 1) === "-");
// código da resposta
$code = (int) substr($response, 0, 3);
// erro retornado pelo servidor?
if ($code >= 400) {
throw new RuntimeException(rtrim(substr($response, 4)));
}
}
// --------------------------------------------------------------------------
function display(string $exchange, int $direction): void
{
// exibe $exchange na tela
// se $direction=1 exibe --> [$exchange] (com fins de linha \n em vez de \r\n)
// se $direction=2 exibe <-- [$exchange] sem os caracteres de fim de linha \r\n
print match ($direction) {
1 => "--> [" . str_replace("\r\n", "\n", $exchange) . "]\n",
2 => "<-- [" . rtrim($exchange, "\r\n") . "]\n",
};
}
|
Comentários:
- linha 32: o arquivo de configuração é processado. O segundo parâmetro, [true], de [json_decode] exige arrays associativos em vez de objetos;
- linha 35: percorremos os elementos do dicionário [$mails]. Cada elemento tem a forma [name => info], em que [name] é um nome qualquer e [info] é um dicionário contendo as informações necessárias para enviar um e-mail;
- linha 39: o e-mail é enviado pela função [sendmail], que recebe dois parâmetros:
- $info: o dicionário contendo as informações necessárias para enviar o e-mail;
- $verbose: um booleano que indica se as trocas cliente/servidor devem ou não ser exibidas no console. Observe o argumento nomeado [verbose: true] (PHP 8.0), que torna a chamada mais legível do que um simples [true];
- linha 53: o nome da máquina cliente, usado pelo comando EHLO;
- linha 55: abertura de uma conexão com o servidor SMTP. O curso de PHP 7 usava a função [fsockopen], que continua disponível. [stream_socket_client] é mais geral: foi a que usamos em [tcp-client.php];
- linhas 61–86: a função [sendmail] envia os diversos comandos que um cliente SMTP deve enviar: leitura da mensagem de boas-vindas, EHLO, MAIL FROM, RCPT TO, DATA, a mensagem, QUIT. Cada comando é enviado pela função [sendCommand], que lança uma exceção [RuntimeException] se o servidor responder com um código de erro. Todos os comandos ficam, portanto, dentro de um bloco [try]: o primeiro erro faz o programa entrar no bloco [catch], que retorna a mensagem de erro. O bloco [finally] é executado em todos os casos: é nele que a conexão é fechada. O código fica assim muito mais curto que o do curso de PHP 7, que verificava o resultado de cada comando;
- linhas 75–78: preparação da mensagem. As linhas da mensagem devem terminar com \r\n. Se uma linha de texto contiver apenas um ponto, o servidor considerará a mensagem concluída. Para evitar isso, o protocolo SMTP exige que o cliente dobre o ponto no início de uma linha: o servidor removerá esse ponto extra. A expressão regular [/^\./m] (opção m: multilinha) corresponde a um ponto no início de uma linha;
- linha 93: a função [sendCommand] é responsável por enviar os comandos do cliente ao servidor SMTP e ler a resposta. Ela aceita três parâmetros:
- [$connection]: a conexão que liga o cliente ao servidor;
- [$command]: o comando a enviar. Se estiver vazio, nada é enviado; a função apenas lê uma resposta (como no caso da mensagem de boas-vindas);
- [$verbose]: se for true, as trocas cliente/servidor são exibidas no console;
- linhas 107–115: lê todas as linhas da resposta. Cada linha tem a forma [XXX-YYY], em que XXX é um código numérico, exceto a última linha da resposta, que tem a forma [XXX YYY] (sem o hífen). O laço [do ... while] para, portanto, quando o quarto caractere da linha não é um hífen;
- linha 119: se o código numérico XXX for maior ou igual a 400, o servidor retornou um erro (os códigos 4xx indicam erros temporários, os códigos 5xx indicam erros permanentes);
- linha 125: a função [display] usa uma expressão [match] para selecionar o texto a exibir de acordo com o sentido da troca.
A execução do script produz a seguinte saída no console:
| > php smtp-01.php
Sending the mail [mail to localhost via localhost]
<-- [220 vm Mailpit ESMTP Service ready]
--> [EHLO vm]
<-- [250-vm greets vm]
<-- [250-SIZE 52428800]
<-- [250-ENHANCEDSTATUSCODES]
<-- [250-8BITMIME]
<-- [250 SMTPUTF8]
--> [MAIL FROM: <guest@localhost>]
<-- [250 2.1.0 Ok]
--> [RCPT TO: <guest@localhost>]
<-- [250 2.1.5 Ok]
--> [DATA]
<-- [354 Start mail input; end with <CR><LF>.<CR><LF>]
--> [From: guest@localhost
To: guest@localhost
Subject: to localhost via localhost
line 1
line 2
line 3
.]
<-- [250 2.0.0 Ok: queued as 5SoJJqMUYg3ZrkBqoVKLQo]
--> [QUIT]
<-- [221 2.0.0 vm Mailpit ESMTP Service closing transmission channel]
Message sent
Sending the mail [mail to gmail via localhost]
<-- [220 vm Mailpit ESMTP Service ready]
--> [EHLO vm]
<-- [250-vm greets vm]
<-- [250-SIZE 52428800]
<-- [250-ENHANCEDSTATUSCODES]
<-- [250-8BITMIME]
<-- [250 SMTPUTF8]
--> [MAIL FROM: <guest@localhost>]
<-- [250 2.1.0 Ok]
--> [RCPT TO: <php8parlexemple@gmail.com>]
<-- [250 2.1.5 Ok]
--> [DATA]
<-- [354 Start mail input; end with <CR><LF>.<CR><LF>]
--> [From: guest@localhost
To: php8parlexemple@gmail.com
Subject: to gmail via localhost
line 1
line 2
line 3
.]
<-- [250 2.0.0 Ok: queued as 78JcBpdQn6ACCrBcnniPz3]
--> [QUIT]
<-- [221 2.0.0 vm Mailpit ESMTP Service closing transmission channel]
Message sent
Sending the mail [mail via a secure server]
<-- [220 vm Mailpit ESMTP Service ready]
--> [EHLO vm]
<-- [250-vm greets vm]
<-- [250-SIZE 52428800]
<-- [250-STARTTLS]
<-- [250-AUTH LOGIN PLAIN]
<-- [250-ENHANCEDSTATUSCODES]
<-- [250-8BITMIME]
<-- [250 SMTPUTF8]
--> [MAIL FROM: <guest@localhost>]
<-- [530 5.7.0 Must issue a STARTTLS command first]
Error: 5.7.0 Must issue a STARTTLS command first
Done
|
- Os dois primeiros envios são bem-sucedidos;
- o terceiro falha: depois do comando [MAIL FROM], o servidor da porta 1587 retorna o código de erro 530 com a mensagem [Must issue a STARTTLS command first]. Observe que, em sua resposta ao comando EHLO, ele anunciou a extensão [STARTTLS] e a autenticação [AUTH LOGIN PLAIN]. O cliente SMTP deve primeiro criptografar a conexão (comando STARTTLS) e depois se autenticar (comando AUTH). Nosso cliente não fez isso e, por isso, é rejeitado. O servidor SMTP do Gmail ([smtp.gmail.com], porta 587) responde exatamente da mesma forma.
A interface web do [Mailpit] exibe os e-mails recebidos. Observe que o e-mail destinado a [php8parlexemple@gmail.com] está de fato ali: o [Mailpit] não o encaminhou ao Gmail.
16.5.5. Um segundo cliente SMTP, que usa a biblioteca [Symfony Mailer]
O cliente anterior tem pelo menos duas deficiências:
- ele não consegue usar uma conexão segura se o servidor exigir uma;
- ele não consegue anexar arquivos à mensagem.
Em nosso novo script, usaremos a biblioteca [Symfony Mailer] (https://symfony.com/doc/current/mailer.html). O curso de PHP 7 usava a biblioteca [SwiftMailer], que não é mantida desde 2021: [Symfony Mailer] é a sucessora dela, escrita pela mesma equipe. A biblioteca foi instalada junto com as demais dependências do curso por meio do comando [composer install] (veja o arquivo [composer.json] na raiz da pasta [php8-oct-2026]) e está localizada na pasta [vendor/symfony/mailer]. Ela usa o componente [symfony/mime], que pode gerar mensagens de qualquer formato.
O script [inet/smtp/smtp-02.php] usará o seguinte arquivo de configuração JSON [config-smtp-02.json]:
| {
"mail to localhost via localhost": {
"smtp-server": "localhost",
"smtp-port": 1025,
"from": "guest@localhost",
"to": "guest@localhost",
"subject": "test-localhost",
"message": "line 1\nline 2\nline 3",
"tls": false,
"attachments": [
"/attachments/Hello from Symfony Mailer.docx",
"/attachments/Hello from Symfony Mailer.pdf",
"/attachments/Hello from Symfony Mailer.odt",
"/attachments/Cours-Tutoriels-Serge-Tahé-1568x268.png",
"/attachments/test-localhost.eml"
]
},
"mail to localhost via a secure server": {
"smtp-server": "localhost",
"smtp-port": 1587,
"from": "guest@localhost",
"to": "guest@localhost",
"subject": "test-secure-server",
"message": "line 1\nline 2\nline 3",
"tls": true,
"user": "guest@localhost",
"password": "guest",
"verify-peer": false,
"attachments": [
"/attachments/Hello from Symfony Mailer.pdf"
]
},
"mail to gmail via gmail": {
"enabled": false,
"smtp-server": "smtp.gmail.com",
"smtp-port": 587,
"from": "php8parlexemple@gmail.com",
"to": "php8parlexemple@gmail.com",
"subject": "test-gmail-via-gmail",
"message": "line 1\nline 2\nline 3",
"tls": true,
"user": "php8parlexemple@gmail.com",
"password": "application password",
"verify-peer": true,
"attachments": [
"/attachments/Hello from Symfony Mailer.docx",
"/attachments/Hello from Symfony Mailer.pdf",
"/attachments/Hello from Symfony Mailer.odt",
"/attachments/Cours-Tutoriels-Serge-Tahé-1568x268.png",
"/attachments/test-localhost.eml"
]
}
}
|
Ele contém os mesmos campos do arquivo [config-smtp-01.json], além de campos adicionais:
- [tls]: definido como [true], especifica que uma conexão segura e autenticada deve ser usada com o servidor SMTP. Nesse caso, os seguintes campos devem ser adicionados:
- [user]: o nome de usuário usado para autenticar a conexão;
- [password]: a senha dele;
- [verify-peer]: o certificado enviado pelo servidor deve ser verificado? Isso deve ser feito com um servidor público. Com nosso servidor de teste, que tem um certificado autoassinado, é preciso definir como [false];
- [attachments]: especifica os nomes dos arquivos a anexar ao e-mail. Eles ficam na pasta [smtp/attachments];
- [enabled]: quando definido como [false], desativa o envio. É o caso do terceiro envio, que usa o servidor SMTP do Gmail.
Para usar o servidor SMTP do Gmail, você precisa de uma conta do Gmail (substitua [php8parlexemple@gmail.com] pelo seu endereço) com a verificação em duas etapas ativada, e deve criar para ela uma "senha de app" na seção [Security] das configurações da sua Conta do Google. Essa senha de 16 caracteres substitui a senha da conta em aplicativos como o nosso. Digite-a no campo [password] e altere o valor de [enabled] para [true].
O código do script [smtp-02.php] é o seguinte:
| <?php
declare(strict_types=1);
// cliente SMTP (Simple Mail Transfer Protocol) escrito com a biblioteca [Symfony Mailer]
// pode usar uma conexão segura e anexar arquivos à mensagem
// dependências
require_once __DIR__ . "/../../../vendor/autoload.php";
use Symfony\Component\Mailer\Mailer;
use Symfony\Component\Mailer\Transport;
use Symfony\Component\Mime\Email;
// os parâmetros de envio dos e-mails: o arquivo de configuração
// pode ser passado como argumento (php smtp-02.php config.json)
$configFileName = $argv[1] ?? "config-smtp-02.json";
// recuperamos a configuração
$mails = json_decode(file_get_contents($configFileName), true);
// envio dos e-mails
foreach ($mails as $name => $info) {
// envio desativado na configuração?
if (($info["enabled"] ?? true) === false) {
print "Sending of the mail [$name] disabled\n";
continue;
}
// acompanhamento
print "Sending the mail [$name]\n";
// envio do e-mail
$result = sendmail($name, $info);
// exibição do resultado
print "$result\n";
}
// fim
print "Done\n";
// --------------------------------------------------------------------------
function sendmail(string $name, array $info): string
{
// envia $info["message"] ao servidor SMTP $info["smtp-server"] na porta $info["smtp-port"]
// se $info["tls"] for true, a conexão é segura e autenticada
// o e-mail é enviado em nome de $info["from"]
// para o destinatário $info["to"]
// os documentos $info["attachments"] são anexados à mensagem
// a mensagem tem o assunto $info["subject"]
//
try {
// criação da mensagem
$email = (new Email())
// remetente
->from($info["from"])
// destinatário (pode haver vários: to(a, b, c), cc(...), bcc(...))
->to($info["to"])
// assunto da mensagem
->subject($info["subject"])
// texto da mensagem
->text($info["message"])
// variante HTML do texto
->html("<b>" . str_replace("\n", "<br/>", $info["message"]) . "</b>");
// anexos
foreach ($info["attachments"] as $attachment) {
// caminho do anexo
$fileName = __DIR__ . $attachment;
// verificamos se o arquivo existe
if (file_exists($fileName)) {
// anexamos o documento à mensagem
$email->attachFromPath($fileName);
} else {
print "The attachment [$fileName] does not exist\n";
}
}
// o transporte da mensagem: um DSN (Data Source Name) da forma
// smtp://user:password@server:port?options
$dsn = "smtp://{$info["smtp-server"]}:{$info["smtp-port"]}";
if ($info["tls"]) {
// conexão segura (STARTTLS) e autenticada
$verifyPeer = ($info["verify-peer"] ?? true) ? 1 : 0;
$dsn = sprintf("smtp://%s:%s@%s:%d?require_tls=1&verify_peer=%d",
rawurlencode($info["user"]), rawurlencode($info["password"]),
$info["smtp-server"], $info["smtp-port"], $verifyPeer);
}
// o gerenciador de envio
$mailer = new Mailer(Transport::fromDsn($dsn));
// envio da mensagem
$mailer->send($email);
// fim
return "Message [$name] sent";
} catch (Throwable $ex) {
// erro
return "Error while sending the message [$name]: " . $ex->getMessage();
}
}
|
Comentários:
- linha 9: carregamos o arquivo [vendor/autoload.php] criado pelo Composer. Esse arquivo nos permite carregar os arquivos de definição de classes das bibliotecas assim que essas classes são usadas pela primeira vez. Isso nos poupa de criar tantos arquivos [require] quantas forem as classes e interfaces do [Symfony Mailer] que usaremos. O caminho é relativo à pasta do script ([__DIR__]): o script funciona independentemente da localização da pasta [php8-oct-2026];
- linhas 11–13: as classes do [Symfony Mailer] estão em namespaces. As instruções [use] nos permitem referenciá-las por seus nomes curtos;
- linha 17: o arquivo de configuração pode ser passado como argumento ao script; caso contrário, o padrão é [config-smtp-02.json];
- linha 25: um envio é desativado se o seu campo [enabled] estiver definido como [false]. O operador [??] retorna [true] se o campo estiver ausente;
- linha 40: a nova função [sendmail], que tem dois parâmetros:
- [$name], que serve para distinguir as mensagens;
- [$info]: as informações necessárias para enviar a mensagem ao destinatário;
- linhas 51–61: definimos a mensagem usando a classe [Email]. Seus métodos retornam o próprio objeto, o que permite encadeá-los:
- [from] define o remetente da mensagem;
- [to] define o destinatário da mensagem;
- [subject] define o assunto da mensagem;
- [text] define o corpo da mensagem;
- [html] define uma variante (HTML) da mensagem. Aqui, trocamos os caracteres de fim de linha pela tag HTML [<br/>] e formatamos todo o texto em negrito. Quando a mensagem tem variantes, os clientes de e-mail exibem a variante preferida do usuário;
- linhas 63–72: o método [attachFromPath] anexa um arquivo à mensagem. O tipo do arquivo (application/pdf...) é inferido a partir de sua extensão;
- linhas 76–82: depois de definida a mensagem a enviar, é preciso especificar como enviá-la. O [Symfony Mailer] descreve o transporte da mensagem por meio de uma string chamada DSN (Data Source Name), na forma [smtp://user:password@server:port?options]. Para uma conexão segura, o usuário e a senha são adicionados, codificados com [rawurlencode] (o caractere @ em [guest@localhost] torna-se %40), junto com duas opções: [require_tls=1] exige a criptografia da conexão, e [verify_peer=0] desativa a verificação do certificado do servidor. Observe que o [Symfony Mailer] usa automaticamente o comando STARTTLS quando o servidor o anuncia;
- linha 85: a classe [Mailer] envia as mensagens. É preciso passar a ela o transporte selecionado, que foi criado a partir do DSN pelo método estático [Transport::fromDsn];
- linha 87: a mensagem é enviada;
- linha 90: a biblioteca lança uma exceção assim que algo dá errado.
Quando o script [smtp-02.php] é executado (com as duas instâncias do [Mailpit] já em execução), a seguinte saída é exibida no console:
| > php smtp-02.php
Sending the mail [mail to localhost via localhost]
Message [mail to localhost via localhost] sent
Sending the mail [mail to localhost via a secure server]
Message [mail to localhost via a secure server] sent
Sending of the mail [mail to gmail via gmail] disabled
Done
|
A interface web do [Mailpit] exibe as duas mensagens. A mensagem [test-secure-server] passou pela instância segura, que a retransmitiu à instância principal. Eis a mensagem [test-localhost]:

- no canto superior direito, o selo [Attachments (5)] indica os cinco anexos, cujas miniaturas são visíveis na parte inferior da página;
- a aba [HTML] exibe a variante HTML da mensagem (em negrito), enquanto a aba [Text] exibe sua variante em texto.
A aba [Raw] mostra o texto puro da mensagem recebida. Aqui está ele, com as linhas que codificam o conteúdo dos anexos removidas:
| Return-Path: <guest@localhost>
Received: from [127.0.0.1] (localhost [127.0.0.1])
by vm (Mailpit) with SMTP
for <guest@localhost>; Thu, 1 Oct 2026 17:14:24 +0200 (CEST)
From: guest@localhost
To: guest@localhost
Subject: test-localhost
Message-ID: <d17f753f0db420a353457b730f2cfdec@localhost>
MIME-Version: 1.0
Date: Thu, 01 Oct 2026 17:14:24 +0200
Content-Type: multipart/mixed; boundary=jM982j4q
--jM982j4q
Content-Type: multipart/alternative; boundary=LUEVyqZR
--LUEVyqZR
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
line 1
line 2
line 3
--LUEVyqZR
Content-Type: text/html; charset=utf-8
Content-Transfer-Encoding: quoted-printable
<b>line 1<br/>line 2<br/>line 3</b>
--LUEVyqZR--
--jM982j4q
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document;
name="Hello from Symfony Mailer.docx"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; name="Hello from Symfony Mailer.docx";
filename="Hello from Symfony Mailer.docx"
--jM982j4q
Content-Type: application/pdf; name="Hello from Symfony Mailer.pdf"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; name="Hello from Symfony Mailer.pdf";
filename="Hello from Symfony Mailer.pdf"
--jM982j4q
Content-Type: application/vnd.oasis.opendocument.text;
name="Hello from Symfony Mailer.odt"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; name="Hello from Symfony Mailer.odt";
filename="Hello from Symfony Mailer.odt"
--jM982j4q
Content-Type: image/png;
name="=?utf-8?Q?Cours-Tutoriels-Serge-Tah=C3=A9-1568x268=2Epng?="
Content-Transfer-Encoding: base64
Content-Disposition: attachment;
name*=utf-8''Cours-Tutoriels-Serge-Tah%C3%A9-1568x268.png;
filename*=utf-8''Cours-Tutoriels-Serge-Tah%C3%A9-1568x268.png
--jM982j4q
Content-Type: message/rfc822; name=test-localhost.eml
Content-Transfer-Encoding: base64
Content-Disposition: attachment; name=test-localhost.eml;
filename=test-localhost.eml
--jM982j4q--
|
- [Return-Path] e [Received]: esses cabeçalhos foram adicionados pelo [Mailpit] ao receber a mensagem. Cada servidor pelo qual uma mensagem passa adiciona um cabeçalho [Received];
- [From], [To], [Subject]: o remetente, o destinatário e o assunto;
- [Content-Type: multipart/mixed; boundary=...]: a mensagem é composta de várias partes, separadas por linhas rotuladas com [--boundary]. A última é seguida pela linha [--boundary--]. Este é o formato MIME (Multipurpose Internet Mail Extensions);
- a primeira parte é, ela mesma, do tipo [multipart/alternative]: contém duas variantes da mensagem, em [text/plain] e em [text/html]. Elas são codificadas em [quoted-printable], uma codificação que deixa os caracteres ASCII sem codificar e codifica os demais (é torna-se =C3=A9);
- Em seguida vêm os cinco anexos ([Content-Disposition: attachment]), codificados em [base64], uma codificação que transforma qualquer conteúdo binário em linhas de caracteres ASCII;
- o nome de arquivo [Cours-Tutoriels-Serge-Tahé-1568x268.png] contém o caractere [é]. Ele é codificado de duas maneiras: [name="=?utf-8?Q?...?="] (conhecida como codificação RFC 2047) e [filename*=utf-8''...%C3%A9...] (conhecida como codificação RFC 2231). Voltaremos a encontrá-las ao ler os e-mails;
- o último anexo, do tipo [message/rfc822], é ele mesmo um e-mail: o arquivo [test-localhost.eml], que também tem anexos.
Por fim, vejamos dois erros comuns. O arquivo [config-smtp-02-errors.json] descreve dois envios à instância segura: o primeiro verifica o certificado do servidor ([verify-peer] como [true]), e o segundo usa uma senha incorreta:
| {
"server certificate verified": {
"smtp-server": "localhost",
"smtp-port": 1587,
"from": "guest@localhost",
"to": "guest@localhost",
"subject": "test-errors",
"message": "line 1\nline 2\nline 3",
"tls": true,
"user": "guest@localhost",
"password": "guest",
"verify-peer": true,
"attachments": []
},
"wrong password": {
"smtp-server": "localhost",
"smtp-port": 1587,
"from": "guest@localhost",
"to": "guest@localhost",
"subject": "test-errors",
"message": "line 1\nline 2\nline 3",
"tls": true,
"user": "guest@localhost",
"password": "xx",
"verify-peer": false,
"attachments": []
}
}
|
Vamos executar o script com esse arquivo de configuração usando o comando [php smtp-02.php config-smtp-02-errors.json]:
| > php smtp-02.php config-smtp-02-errors.json
Sending the mail [server certificate verified]
Error while sending the message [server certificate verified]: Unable to connect with STARTTLS: stream_socket_enable_crypto(): SSL operation failed with code 1. OpenSSL Error messages:
error:0A000086:SSL routines::certificate verify failed
Sending the mail [wrong password]
Error while sending the message [wrong password]: Failed to authenticate on SMTP server with username "guest@localhost" using the following authenticators: "LOGIN", "PLAIN". Authenticator "LOGIN" returned "Expected response code "235" but got code "535", with message "535 5.7.8 Authentication credentials invalid".". Authenticator "PLAIN" returned "Expected response code "235" but got code "535", with message "535 5.7.8 Authentication credentials invalid".".
Done
|
- Primeira tentativa: o certificado autoassinado do [Mailpit] não foi emitido por uma autoridade certificadora conhecida. A verificação falha, e o cliente se recusa a prosseguir — é isso que protege um cliente contra a personificação de um servidor. Com o [smtp.gmail.com], cujo certificado é válido, a verificação é bem-sucedida;
- segunda tentativa: o servidor rejeita a autenticação com o código de erro 535.
16.6. Os protocolos POP3 (Post Office Protocol) e IMAP (Internet Message Access Protocol)
16.6.1. Introdução
Existem dois protocolos para ler e-mails armazenados em um servidor de e-mail:
- o protocolo POP3 (Post Office Protocol), historicamente o primeiro, mas raramente usado hoje;
- o protocolo IMAP (Internet Message Access Protocol), que é mais recente que o POP3 e atualmente o mais utilizado.
Para explorar esses protocolos, usaremos a seguinte arquitetura:

- [Server B] será:
- para o POP3, o servidor POP3 do [Mailpit] (porta 1110);
- para o IMAP, um servidor IMAP. Pode ser o servidor do Gmail ([imap.gmail.com], porta 993), usando a conta do Gmail e a senha de app mencionadas para o protocolo SMTP. Os resultados apresentados aqui foram obtidos com um servidor IMAP local, o servidor de código aberto [Dovecot] (https://www.dovecot.org), que tem um usuário chamado [guest@localhost] com a senha [guest]. Colocamos os e-mails enviados por nossos scripts SMTP na caixa de entrada INBOX desse usuário. Com o Gmail, você obterá resultados no mesmo formato;
- [Client A] será um cliente POP3 / IMAP em diversas formas:
- o cliente [tcp-client.php] para descobrir os protocolos POP3 e IMAP;
- um script PHP que reproduz o protocolo POP3 descoberto com [tcp-client.php];
- scripts PHP que usam as classes POP3 e IMAP, que escreveremos, seguidas da biblioteca [zbateson/mail-mime-parser] para analisar as mensagens.
O curso de PHP 7 usava as funções [imap_*] da extensão [imap] do PHP, que suportava tanto IMAP quanto POP3. Essa extensão, baseada em uma biblioteca C abandonada havia anos, foi removida do PHP 8.4. Portanto, vamos escrever nós mesmos os clientes POP3 e IMAP de que precisamos, usando as funções de socket do PHP. É uma oportunidade de entender a fundo esses dois protocolos.
16.6.2. Explorando o protocolo POP3
Primeiro, usamos o script [smtp-01.php] para enviar dois e-mails: um para [guest@localhost] e o outro para [php8parlexemple@gmail.com] (a terceira tentativa falha, como vimos). O servidor POP3 do [Mailpit] apresenta todos os e-mails recebidos pelo [Mailpit] em uma única caixa de correio, independentemente de seus destinatários. Para lê-la, é preciso fazer login com um usuário do arquivo [pop3-users.txt] — neste caso, [guest] — com a senha [guest].
Vamos ver como acessar essa caixa de correio usando o cliente [tcp-client.php]:
| > php tcp-client.php --quit bye localhost 1110
Client [127.0.0.1:47492] connected to the server [localhost:1110]
Type your commands (bye to stop):
<-- [+OK Mailpit POP3 server]
USER guest
<-- [+OK]
PASS guest
<-- [+OK signed in]
LIST
<-- [+OK 2 messages (682 octets)]
<-- [1 349]
<-- [2 333]
<-- [.]
RETR 1
<-- [+OK 349 octets]
<-- [Message-ID: <73n0AqT1QxqOYmrcWH5gK7@mailpit>]
<-- [Return-Path: <guest@localhost>]
<-- [Received: from vm (localhost [127.0.0.1])]
<-- [ by vm (Mailpit) with SMTP]
<-- [ for <php8parlexemple@gmail.com>; Thu, 1 Oct 2026 17:14:31 +0200 (CEST)]
<-- [From: guest@localhost]
<-- [To: php8parlexemple@gmail.com]
<-- [Subject: to gmail via localhost]
<-- []
<-- [line 1]
<-- [line 2]
<-- [line 3]
<-- []
<-- [.]
DELE 1
<-- [+OK message marked for deletion]
LIST
<-- [+OK 1 messages (333 octets)]
<-- [2 333]
<-- [.]
DELE 2
<-- [+OK message marked for deletion]
LIST
<-- [+OK 0 messages (0 octets)]
<-- [.]
QUIT
<-- [+OK goodbye]
Connection with the server lost...
End of the client
|
- [php tcp-client.php --quit bye localhost 1110]: o servidor POP3 normalmente usa a porta 110. Aqui, é a porta 1110 do [Mailpit];
- [USER guest]: o comando [USER] serve para especificar o usuário cuja caixa de correio se deseja ler;
- [PASS guest]: o comando [PASS] serve para informar a senha do usuário;
- [LIST]: o comando [LIST] solicita a lista de mensagens da caixa de correio do usuário. O servidor responde com o número de mensagens e seu tamanho total, seguido de uma linha [number size] por mensagem;
- [RETR 1]: o comando [RETR] solicita a mensagem especificada pelo número informado. Os cabeçalhos [From], [To] e [Subject] — enviados pelo [smtp-01.php] — estão incluídos, junto com os cabeçalhos adicionados pelo [Mailpit]. [Mailpit] exibe as mensagens da mais nova para a mais antiga: a mensagem nº 1 é a recebida mais recentemente;
- [DELE 1]: o comando [DELE] marca a mensagem de número especificado como "a ser excluída". A mensagem deixa de aparecer na lista;
- [QUIT]: o comando [QUIT] informa ao servidor que você terminou. Nesse momento, o servidor exclui as mensagens marcadas. As duas mensagens desapareceram da interface web do [Mailpit].
A resposta do servidor pode assumir várias formas:
- uma única linha começando com [+OK] para indicar que o comando anterior do cliente foi bem-sucedido;
- uma única linha começando com [-ERR] para indicar que o comando anterior do cliente falhou;
- várias linhas em que:
- a primeira linha começa com [+OK];
- a última linha consiste em um único ponto.
16.6.3. Um script básico que implementa o protocolo POP3

Como o protocolo POP3 tem a mesma estrutura que o protocolo SMTP, o script [inet/imap/pop3-01.php] é uma adaptação do script [smtp-01.php]. Ele tem o seguinte arquivo de configuração, [config-pop3-01.json]:
| {
"localhost:1110": {
"server": "localhost",
"port": 1110,
"user": "guest",
"password": "guest",
"maxmails": 5
}
}
|
- linhas 3–4: o servidor POP3 consultado é o servidor do [Mailpit];
- linhas 5–6: o usuário e sua senha;
- linha 7: no máximo 5 e-mails serão recuperados.
O script [pop3-01.php] é o seguinte:
| <?php
declare(strict_types=1);
// cliente POP3 (Post Office Protocol) usado para ler as mensagens de uma caixa de correio
// protocolo de comunicação cliente-servidor POP3
// -> o cliente se conecta à porta do servidor POP3 (110, 1110...)
// <- o servidor lhe envia uma mensagem de boas-vindas
// -> o cliente envia o comando USER user
// <- o servidor responde OK ou não
// -> o cliente envia o comando PASS password
// <- o servidor responde OK ou não
// -> o cliente envia o comando LIST
// <- o servidor responde OK ou não. Se OK, envia a lista [nº tamanho] das mensagens
// -> o cliente envia o comando RETR nº para cada uma das mensagens
// <- o servidor responde OK ou não. Se OK, envia o conteúdo da mensagem solicitada
// -> o cliente envia o comando DELE nº para excluir uma mensagem
// <- o servidor responde OK ou não
// -> o cliente envia o comando QUIT para encerrar o diálogo com o servidor
// <- o servidor responde OK ou não
// as respostas do servidor têm a forma +OK texto ou -ERR texto
// A resposta pode ter várias linhas. Nesse caso, a última é composta por um único ponto
// as linhas de texto trocadas devem terminar com os caracteres CR (13) e LF (10)
// os parâmetros de leitura das caixas de correio
const CONFIG_FILE_NAME = "config-pop3-01.json";
// recuperamos a configuração
$mailboxes = json_decode(file_get_contents(CONFIG_FILE_NAME), true);
// leitura das caixas de correio
foreach ($mailboxes as $name => $info) {
// acompanhamento
print "Reading the mailbox [$name]\n";
// leitura da caixa de correio
$result = readmail($info, verbose: true);
// exibição do resultado
print "$result\n";
}
// fim
print "Done\n";
// --------------------------------------------------------------------------
function readmail(array $info, bool $verbose = true): string
{
// lê no máximo $info["maxmails"] mensagens da caixa de correio descrita por [$info]
// cada mensagem é excluída depois de lida
// se $verbose=true, acompanha as trocas cliente-servidor
//
// abertura de uma conexão com o servidor POP3
$connection = @stream_socket_client("tcp://{$info["server"]}:{$info["port"]}", $errorNumber, $error);
if ($connection === false) {
return "Failed to connect to the server [{$info["server"]}:{$info["port"]}]: $error";
}
try {
// após a conexão, o servidor envia uma mensagem de boas-vindas que lemos
sendCommand($connection, "", $verbose);
// comando USER
sendCommand($connection, "USER {$info["user"]}", $verbose);
// comando PASS
sendCommand($connection, "PASS {$info["password"]}", $verbose);
// comando LIST: a 1ª linha da resposta tem a forma [+OK n messages...]
$response = sendCommand($connection, "LIST", $verbose, multiline: true);
preg_match('/^\+OK (\d+)/', $response[0], $fields);
$nbMessages = (int) ($fields[1] ?? 0);
// percorremos as mensagens
for ($i = 1; $i <= min($nbMessages, $info["maxmails"]); $i++) {
// comando RETR: a mensagem está nas linhas 1 a n-1 da resposta
sendCommand($connection, "RETR $i", $verbose, multiline: true);
// comando DELE
sendCommand($connection, "DELE $i", $verbose);
}
// comando QUIT: é ele que exclui as mensagens marcadas por DELE
sendCommand($connection, "QUIT", $verbose);
return "Reading done";
} catch (RuntimeException $ex) {
// o servidor sinalizou um erro
return "Error: " . $ex->getMessage();
} finally {
// em todos os casos, fechamos a conexão
fclose($connection);
}
}
// --------------------------------------------------------------------------
function sendCommand($connection, string $command, bool $verbose, bool $multiline = false): array
{
// envia $command ao canal $connection e retorna as linhas da resposta
// modo verboso se $verbose=true
// se $multiline=true, a resposta termina com uma linha reduzida a um ponto
// lança uma RuntimeException se o servidor sinalizar um erro
//
// envio do comando se não estiver vazio
if ($command !== "") {
fwrite($connection, "$command\r\n");
if ($verbose) {
display($command, 1);
}
}
// leitura da 1ª linha da resposta
$line = readServerLine($connection, $verbose);
// erro?
if (str_starts_with($line, "-ERR")) {
throw new RuntimeException(substr($line, 5));
}
$response = [$line];
// resposta de várias linhas?
if ($multiline) {
while (($line = readServerLine($connection, $verbose)) !== ".") {
// uma linha da mensagem que começa com um ponto foi enviada
// com um ponto extra: nós o removemos
$response[] = str_starts_with($line, "..") ? substr($line, 1) : $line;
}
}
return $response;
}
// --------------------------------------------------------------------------
function readServerLine($connection, bool $verbose): string
{
// lê uma linha enviada pelo servidor e a retorna sem os caracteres \r\n
$line = fgets($connection);
if ($line === false) {
throw new RuntimeException("the server has closed the connection");
}
$line = rtrim($line, "\r\n");
if ($verbose) {
display($line, 2);
}
return $line;
}
// --------------------------------------------------------------------------
function display(string $exchange, int $direction): void
{
// exibe $exchange na tela
// se $direction=1 exibe --> [$exchange]
// se $direction=2 exibe <-- [$exchange]
print match ($direction) {
1 => "--> [$exchange]\n",
2 => "<-- [$exchange]\n",
};
}
|
Comentários
Como mencionamos, [pop3-01.php] é uma adaptação do script [smtp-01.php] que já discutimos. Comentaremos apenas as principais diferenças:
- linha 44: a função [readmail] é responsável por ler os e-mails da caixa de correio. As informações de login dessa caixa estão no dicionário [$info];
- linha 51: estabelece uma conexão com o servidor POP3;
- linha 57: lê a mensagem de boas-vindas enviada pelo servidor;
- linhas 59–61: os comandos [USER] e [PASS] são enviados para identificar o usuário cujos e-mails se deseja obter;
- linhas 63–65: o comando [LIST] é enviado para determinar quantos e-mails há na caixa de correio. A função [sendCommand] agora retorna as linhas da resposta. Na primeira linha de sua resposta ao comando LIST, o servidor indica quantas mensagens existem. Isso é recuperado por meio de uma expressão regular. [$fields[1] ?? 0] retorna 0 se a expressão regular não encontrou nada;
- linhas 67–71: percorremos as mensagens. Para cada uma, enviamos dois comandos:
- RETR i: para recuperar a mensagem nº i;
- DELE i: para excluí-la depois de lida;
- linha 74: o comando [QUIT] é enviado para informar ao servidor que terminamos;
- linha 86: o parâmetro [$multiline] indica se a resposta esperada tem várias linhas, a última das quais consiste em um único ponto. É o caso dos comandos [LIST] e [RETR]. Um erro é indicado por uma primeira linha começando com [-ERR] (função [str_starts_with] do PHP 8.0);
- linhas 110–112: assim como no SMTP, o servidor duplica o ponto no início de uma linha da mensagem. O cliente deve remover esse ponto extra.
Enviamos mais dois e-mails usando [smtp-01.php] e depois executamos [pop3-01.php]:
| > php pop3-01.php
Reading the mailbox [localhost:1110]
<-- [+OK Mailpit POP3 server]
--> [USER guest]
<-- [+OK]
--> [PASS guest]
<-- [+OK signed in]
--> [LIST]
<-- [+OK 2 messages (682 octets)]
<-- [1 349]
<-- [2 333]
<-- [.]
--> [RETR 1]
<-- [+OK 349 octets]
<-- [Message-ID: <67n1volg9CfPFES6KhEOf7@mailpit>]
<-- [Return-Path: <guest@localhost>]
<-- [Received: from vm (localhost [127.0.0.1])]
<-- [ by vm (Mailpit) with SMTP]
<-- [ for <php8parlexemple@gmail.com>; Thu, 1 Oct 2026 17:14:39 +0200 (CEST)]
<-- [From: guest@localhost]
<-- [To: php8parlexemple@gmail.com]
<-- [Subject: to gmail via localhost]
<-- []
<-- [line 1]
<-- [line 2]
<-- [line 3]
<-- []
<-- [.]
--> [DELE 1]
<-- [+OK message marked for deletion]
--> [RETR 2]
<-- [+OK 333 octets]
<-- [Message-ID: <6ZFzliytBzUvTLo2fEhfiC@mailpit>]
<-- [Return-Path: <guest@localhost>]
<-- [Received: from vm (localhost [127.0.0.1])]
<-- [ by vm (Mailpit) with SMTP]
<-- [ for <guest@localhost>; Thu, 1 Oct 2026 17:14:39 +0200 (CEST)]
<-- [From: guest@localhost]
<-- [To: guest@localhost]
<-- [Subject: to localhost via localhost]
<-- []
<-- [line 1]
<-- [line 2]
<-- [line 3]
<-- []
<-- [.]
--> [DELE 2]
<-- [+OK message marked for deletion]
--> [QUIT]
<-- [+OK goodbye]
Reading done
Done
|
Aqui temos um cliente POP3 básico, que carece de certas capacidades:
- a capacidade de se comunicar com um servidor seguro;
- a capacidade de ler os anexos das mensagens.
Antes de adicionar esses recursos, vamos explorar o protocolo IMAP.
16.6.4. Explorando o protocolo IMAP
O protocolo IMAP é mais rico em recursos que o protocolo POP3. O servidor gerencia várias caixas de correio por usuário (INBOX, Sent, Trash etc.) e acompanha o estado das mensagens: lida, respondida, a ser excluída... Esses estados são chamados de flags. O mais importante é que o cliente pode solicitar ao servidor a estrutura de uma mensagem e baixar apenas uma parte dela.
Cada comando do cliente é precedido por uma tag escolhida pelo cliente, por exemplo, [A1]. O servidor responde com linhas começando com um asterisco [*], seguidas de uma linha começando com a tag do comando, seguida de [OK] (sucesso), [NO] (falha) ou [BAD] (comando inválido).
Os servidores IMAP públicos aceitam apenas conexões criptografadas na porta 993 desde o momento em que são iniciados. Com o Gmail, você iniciaria o cliente TCP com a opção [--tls]: [php tcp-client.php --tls --quit bye imap.gmail.com 993]. Nosso servidor local também aceita conexões não criptografadas na porta padrão 143, o que é útil para a descoberta. Enviamos dois e-mails usando o script [smtp-02.php] (configuração [config-smtp-02.json]), e eles foram entregues na caixa de entrada INBOX do usuário [guest@localhost]. Eis um diálogo com o servidor IMAP:
| > php tcp-client.php --quit bye localhost 143
Client [127.0.0.1:39098] connected to the server [localhost:143]
Type your commands (bye to stop):
<-- [* OK [CAPABILITY IMAP4rev1 SASL-IR LOGIN-REFERRALS ID ENABLE IDLE LITERAL+ STARTTLS AUTH=PLAIN AUTH=LOGIN] Dovecot ready.]
A1 LOGIN guest@localhost guest
<-- [A1 OK [CAPABILITY IMAP4rev1 SASL-IR LOGIN-REFERRALS ID ENABLE IDLE SORT SORT=DISPLAY THREAD=REFERENCES THREAD=REFS THREAD=ORDEREDSUBJECT MULTIAPPEND URL-PARTIAL CATENATE UNSELECT CHILDREN NAMESPACE UIDPLUS LIST-EXTENDED I18NLEVEL=1 CONDSTORE QRESYNC ESEARCH ESORT SEARCHRES WITHIN CONTEXT=SEARCH LIST-STATUS BINARY MOVE SNIPPET=FUZZY PREVIEW=FUZZY PREVIEW STATUS=SIZE SAVEDATE LITERAL+ NOTIFY SPECIAL-USE] Logged in]
A2 SELECT INBOX
<-- [* FLAGS (\Answered \Flagged \Deleted \Seen \Draft)]
<-- [* OK [PERMANENTFLAGS (\Answered \Flagged \Deleted \Seen \Draft \*)] Flags permitted.]
<-- [* 2 EXISTS]
<-- [* 2 RECENT]
<-- [* OK [UNSEEN 1] First unseen.]
<-- [* OK [UIDVALIDITY 1790865054] UIDs valid]
<-- [* OK [UIDNEXT 10] Predicted next UID]
<-- [A2 OK [READ-WRITE] Select completed (0.001 + 0.000 secs).]
A3 SEARCH UNSEEN
<-- [* SEARCH 1 2]
<-- [A3 OK Search completed (0.001 + 0.000 secs).]
A4 FETCH 2 (FLAGS RFC822.SIZE BODY.PEEK[HEADER.FIELDS (FROM TO SUBJECT DATE)])
<-- [* 2 FETCH (FLAGS (\Recent) RFC822.SIZE 28101 BODY[HEADER.FIELDS (FROM TO SUBJECT DATE)] {114}]
<-- [From: guest@localhost]
<-- [To: guest@localhost]
<-- [Subject: test-secure-server]
<-- [Date: Thu, 01 Oct 2026 17:14:39 +0200]
<-- []
<-- [)]
<-- [A4 OK Fetch completed (0.001 + 0.000 secs).]
A5 FETCH 2 BODY.PEEK[1.1]
<-- [* 2 FETCH (BODY[1.1] {22}]
<-- [line 1]
<-- [line 2]
<-- [line 3)]
<-- [A5 OK Fetch completed (0.002 + 0.000 + 0.001 secs).]
A6 FETCH 1 BODYSTRUCTURE
<-- [* 1 FETCH (BODYSTRUCTURE ((("text" "plain" ("charset" "utf-8") NIL NIL "quoted-printable" 22 2 NIL NIL NIL NIL)("text" "html" ("charset" "utf-8") NIL NIL "quoted-printable" 35 0 NIL NIL NIL NIL) "alternative" ("boundary" "7tEIKgyZ") NIL NIL NIL)("application" "vnd.openxmlformats-officedocument.wordprocessingml.document" ("name" "Hello from Symfony Mailer.docx") NIL NIL "base64" 13518 NIL ("attachment" ("name" "Hello from Symfony Mailer.docx" "filename" "Hello from Symfony Mailer.docx")) NIL NIL)("application" "pdf" ("name" "Hello from Symfony Mailer.pdf") NIL NIL "base64" 26926 NIL ("attachment" ("name" "Hello from Symfony Mailer.pdf" "filename" "Hello from Symfony Mailer.pdf")) NIL NIL)("application" "vnd.oasis.opendocument.text" ("name" "Hello from Symfony Mailer.odt") NIL NIL "base64" 9514 NIL ("attachment" ("name" "Hello from Symfony Mailer.odt" "filename" "Hello from Symfony Mailer.odt")) NIL NIL)("image" "png" ("name" "=?utf-8?Q?Cours-Tutoriels-Serge-Tah=C3=A9-1568x268=2Epng?=") NIL NIL "base64" 57834 NIL ("attachment" ("filename*" "utf-8''Cours-Tutoriels-Serge-Tah%C3%A9-1568x268.png" "name*" "utf-8''Cours-Tutoriels-Serge-Tah%C3%A9-1568x268.png")) NIL NIL)("message" "rfc822" ("name" "test-localhost.eml") NIL NIL "base64" 149814 (NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL) ("text" "plain" ("charset" "us-ascii") NIL NIL "7bit" 0 0 NIL NIL NIL NIL) 1921 NIL ("attachment" ("name" "test-localhost.eml" "filename" "test-localhost.eml")) NIL NIL) "mixed" ("boundary" "9UJIzQkk") NIL NIL NIL))]
<-- [A6 OK Fetch completed (0.001 + 0.000 secs).]
A7 LOGOUT
<-- [* BYE Logging out]
<-- [A7 OK Logout completed (0.001 + 0.000 secs).]
Connection with the server lost...
End of the client
|
- [A1 LOGIN guest@localhost guest]: o comando [LOGIN user password] autentica o usuário. O servidor responde com uma lista das capacidades do usuário (CAPABILITY);
- [A2 SELECT INBOX]: o comando [SELECT] seleciona a caixa de correio à qual os comandos seguintes se aplicarão. O servidor lista as flags disponíveis (FLAGS), o número de mensagens (2 EXISTS) e o número da primeira mensagem não lida (UNSEEN 1)...;
- [A3 SEARCH UNSEEN]: o comando [SEARCH] procura mensagens com base em um critério. Há cerca de vinte critérios desse tipo. Aqui, procuramos as mensagens ainda não lidas (UNSEEN). O servidor retorna seus números: 1 e 2;
- [A4 FETCH 2 (...)]: o comando [FETCH] solicita informações sobre uma mensagem. Aqui, ele recupera as flags da mensagem (FLAGS), seu tamanho (RFC822.SIZE) e quatro de seus cabeçalhos. O formato [BODY.PEEK[...]] solicita uma parte da mensagem sem marcá-la como lida. O texto dos cabeçalhos é enviado como um literal: [{114}] no fim da linha indica que os 114 bytes seguintes fazem parte da resposta, independentemente de seu conteúdo (inclusive quebras de linha). A resposta termina com um parêntese de fechamento após o literal;
- [A5 FETCH 2 BODY.PEEK[1.1]]: a parte 1.1 da mensagem nº 2 é solicitada; aqui, seu texto é [text/plain]. Veremos em breve como as partes de uma mensagem são numeradas;
- [A6 FETCH 1 BODYSTRUCTURE]: solicitamos a estrutura da mensagem nº 1, a que tem cinco anexos. A resposta é uma lista de listas entre parênteses. Podemos reconhecer as partes da mensagem que vimos no [Mailpit]: uma lista [(("text" "plain" ...)("text" "html" ...) "alternative" ...)] para a parte [multipart/alternative], seguida de uma lista para cada anexo, incluindo seu tipo, parâmetros (nome), codificação (base64), tamanho e disposição ("attachment" com o nome do arquivo). A estrutura termina com o subtipo [mixed] da mensagem inteira;
- [A7 LOGOUT]: o fim do diálogo.
16.6.5. Classes para os protocolos POP3 e IMAP
Nossos scripts de leitura de e-mail usarão indiferentemente um servidor POP3 ou um servidor IMAP. Portanto, escreveremos:
- uma interface [MailClient] que descreve o que um cliente de e-mail pode fazer;
- uma classe abstrata [TcpClient] que reúne o que é comum aos dois protocolos: uma conexão TCP — que pode ser criptografada — pela qual linhas de texto são trocadas;
- duas classes, [Pop3Client] e [ImapClient], que herdam de [TcpClient] e implementam a interface [MailClient];
- uma classe chamada [MimePart] que descreve a estrutura de uma mensagem, obtida pelo comando IMAP [BODYSTRUCTURE].
Elas estão localizadas na pasta [inet/imap]:
| imap
├── ImapClient.php
├── MailClient.php
├── MimePart.php
├── Pop3Client.php
├── TcpClient.php
├── config-imap-01.json
├── config-pop3-01.json
├── imap-01.php
├── imap-02.php
├── imap-03.php
└── pop3-01.php
|
16.6.5.1. A interface [MailClient]
| <?php
declare(strict_types=1);
// o que um cliente de leitura de e-mails pode fazer, fale ele POP3 ou IMAP
// as mensagens são designadas por seu número (1, 2...) na caixa de correio
interface MailClient
{
// conexão e autenticação - retorna o número de mensagens na caixa de correio
public function connect(): int;
// os números das mensagens não lidas
public function unread(): array;
// os principais cabeçalhos da mensagem nº $n (Date, From, To, Subject...)
public function headers(int $n): array;
// o texto completo da mensagem nº $n (cabeçalhos e corpo)
public function message(int $n): string;
// marca a mensagem nº $n como "to be deleted"
public function delete(int $n): void;
// exclui as mensagens marcadas e encerra a conexão
public function close(): void;
}
|
- linha 10: conexão ao servidor e autenticação do usuário. O método retorna o número de mensagens na caixa de correio;
- linha 13: os números das mensagens não lidas;
- linha 16: os principais cabeçalhos de uma mensagem, na forma de um dicionário;
- linha 19: o texto completo de uma mensagem, isto é, o que vimos na aba [Raw] do [Mailpit];
- linha 22: marca uma mensagem como "a ser excluída";
- linha 25: exclui as mensagens marcadas e fecha a conexão.
16.6.5.2. A classe [TcpClient]
| <?php
declare(strict_types=1);
// classe base dos clientes POP3 e IMAP: uma conexão TCP, eventualmente
// criptografada (TLS), na qual são trocadas linhas de texto terminadas por \r\n
abstract class TcpClient
{
// a conexão com o servidor (um resource do tipo stream)
protected mixed $connection = null;
// $info: a configuração do servidor (server, port, tls, verify-peer, user, password...)
// $tracking: se true, as trocas cliente / servidor são exibidas no console
public function __construct(protected readonly array $info, protected readonly bool $tracking = false)
{
}
// abertura da conexão com o servidor
protected function openConnection(): void
{
// conexão criptografada desde a abertura (tls://) ou não (tcp://)?
$transport = ($this->info["tls"] ?? false) ? "tls" : "tcp";
// o certificado do servidor deve ser verificado? (sim por padrão)
$verify = $this->info["verify-peer"] ?? true;
$context = stream_context_create(["ssl" => ["verify_peer" => $verify, "verify_peer_name" => $verify]]);
$connection = @stream_socket_client("$transport://{$this->info["server"]}:{$this->info["port"]}",
$errorNumber, $error, 10, STREAM_CLIENT_CONNECT, $context);
if ($connection === false) {
throw new RuntimeException("failed to connect to the server "
. "[{$this->info["server"]}:{$this->info["port"]}]: $error");
}
$this->connection = $connection;
}
// envio de uma linha ao servidor - $display: o que deve ser exibido no modo de rastreamento
protected function send(string $line, ?string $display = null): void
{
fwrite($this->connection, "$line\r\n");
$this->display("--> " . ($display ?? $line));
}
// leitura de uma linha enviada pelo servidor, retornada sem os caracteres \r\n
// $display: a linha deve ser exibida no modo de rastreamento?
protected function readLine(bool $display = true): string
{
$line = fgets($this->connection);
if ($line === false) {
throw new RuntimeException("the server has closed the connection");
}
$line = rtrim($line, "\r\n");
if ($display) {
$this->display("<-- $line");
}
return $line;
}
// leitura de $nbBytes bytes enviados pelo servidor
protected function readBytes(int $nbBytes): string
{
$bytes = "";
while (strlen($bytes) < $nbBytes) {
$chunk = fread($this->connection, $nbBytes - strlen($bytes));
if ($chunk === false || $chunk === "") {
throw new RuntimeException("the server has closed the connection");
}
$bytes .= $chunk;
}
$this->display("<-- ... $nbBytes bytes ...");
return $bytes;
}
// fechamento da conexão
protected function closeConnection(): void
{
if ($this->connection !== null) {
fclose($this->connection);
$this->connection = null;
}
}
// exibição no modo de rastreamento
protected function display(string $message): void
{
if ($this->tracking) {
print "$message\n";
}
}
// análise dos cabeçalhos de uma mensagem: retorna o dicionário [nome => valor] dos
// cabeçalhos decodificados (os cabeçalhos não ASCII são codificados, por exemplo =?utf-8?Q?...?=)
protected static function parseHeaders(string $headers): array
{
$dictionary = iconv_mime_decode_headers($headers, ICONV_MIME_DECODE_CONTINUE_ON_ERROR, "UTF-8");
return $dictionary === false ? [] : $dictionary;
}
}
|
- linha 7: a classe é abstrata; não pode ser instanciada. Ela serve de classe-mãe para as classes [Pop3Client] e [ImapClient];
- linha 10: a conexão com o servidor. As funções do PHP a representam como um resource, um tipo que não pode ser declarado em PHP: usa-se o tipo [mixed];
- linha 14: o construtor usa a promoção de parâmetros (PHP 8.0): os parâmetros [$info] e [$tracking] tornam-se propriedades da classe, neste caso somente leitura ([readonly], PHP 8.1). O corpo do construtor está vazio. [$info] é a configuração do servidor, lida de um arquivo JSON. [$tracking] solicita que as trocas cliente/servidor sejam exibidas;
- linhas 19–32: estabelecimento da conexão. Se a configuração contiver [tls: true], a conexão é criptografada assim que é estabelecida (transporte [tls://]). O contexto especifica se o certificado do servidor deve ser verificado (entrada [verify-peer], true por padrão);
- linha 36: envio de uma linha ao servidor. O parâmetro [$display] permite exibir algo diferente do que é enviado: vamos usá-lo para ocultar senhas;
- linha 44: leitura de uma linha. Se o servidor tiver fechado a conexão, uma exceção é lançada;
- linha 58: lê um número especificado de bytes. Usaremos isso para os literais do IMAP. A função [fread] pode retornar menos bytes do que o solicitado: fazemos um laço até receber tudo;
- linha 91: a função [iconv_mime_decode_headers] analisa um bloco de cabeçalhos de e-mail e retorna o dicionário [name => value]. Ela concatena cabeçalhos distribuídos em várias linhas e decodifica cabeçalhos codificados (=?utf-8?Q?...?=).
16.6.5.3. A classe [Pop3Client]
| <?php
declare(strict_types=1);
require_once __DIR__ . "/TcpClient.php";
require_once __DIR__ . "/MailClient.php";
// cliente POP3: os comandos USER, PASS, STAT, TOP, LIST, RETR, DELE, QUIT
final class Pop3Client extends TcpClient implements MailClient
{
// número de mensagens na caixa de correio
private int $nbMessages = 0;
#[\Override]
public function connect(): int
{
$this->openConnection();
// mensagem de boas-vindas do servidor
$this->command("");
// autenticação
$this->command("USER {$this->info["user"]}");
$this->command("PASS {$this->info["password"]}", "PASS *****");
// STAT: a resposta tem a forma [+OK nbMessages totalSize]
$response = $this->command("STAT");
$this->nbMessages = (int) explode(" ", $response[0])[1];
return $this->nbMessages;
}
#[\Override]
public function unread(): array
{
// o POP3 não memoriza as mensagens lidas: todas as mensagens presentes são novas
return $this->nbMessages === 0 ? [] : range(1, $this->nbMessages);
}
#[\Override]
public function headers(int $n): array
{
// TOP n 0: os cabeçalhos da mensagem nº n seguidos de 0 linhas do corpo
$lines = $this->command("TOP $n 0", multiline: true);
$headers = self::parseHeaders(implode("\r\n", array_slice($lines, 1)));
// LIST n: a resposta tem a forma [+OK n size]
$response = $this->command("LIST $n");
// mantemos apenas os principais cabeçalhos
$summary = array_intersect_key($headers, array_flip(["Date", "From", "To", "Subject", "Message-ID"]));
return [...$summary, "Size" => explode(" ", $response[0])[2]];
}
#[\Override]
public function message(int $n): string
{
// RETR n: a 1ª linha da resposta é [+OK...], as seguintes são a mensagem
$lines = $this->command("RETR $n", multiline: true);
return implode("\r\n", array_slice($lines, 1)) . "\r\n";
}
#[\Override]
public function delete(int $n): void
{
$this->command("DELE $n");
}
#[\Override]
public function close(): void
{
// nada a fazer se a conexão não pôde ser aberta
if ($this->connection === null) {
return;
}
try {
// é o comando QUIT que exclui as mensagens marcadas por DELE
$this->command("QUIT");
} finally {
$this->closeConnection();
}
}
// envia um comando ao servidor (se não estiver vazio) e retorna as linhas da resposta
// $multiline: a resposta termina com uma linha contendo apenas um ponto?
private function command(string $command, ?string $display = null, bool $multiline = false): array
{
if ($command !== "") {
$this->send($command, $display);
}
// 1ª linha: +OK ou -ERR
$line = $this->readLine();
if (str_starts_with($line, "-ERR")) {
throw new RuntimeException("[" . ($display ?? $command) . "]: $line");
}
$response = [$line];
if ($multiline) {
// as linhas seguintes, até a linha [.], não são exibidas no modo de rastreamento
while (($line = $this->readLine(false)) !== ".") {
// o servidor duplica o ponto que inicia uma linha: nós o removemos
$response[] = str_starts_with($line, "..") ? substr($line, 1) : $line;
}
$this->display("<-- ... " . (count($response) - 1) . " lines ...");
$this->display("<-- .");
}
return $response;
}
}
|
- linha 9: a classe herda de [TcpClient] e implementa [MailClient]. Ela é declarada como [final]: nenhuma classe pode ser derivada dela;
- linha 14: o atributo [#[\Override]] (PHP 8.3) indica que o método implementa um método de uma interface ou sobrescreve um método da classe-mãe. Se não for esse o caso (por exemplo, um erro de digitação no nome), o PHP reporta um erro;
- linhas 15–26: a conexão. Os comandos de [pop3-01.php] estão presentes aqui. O comando [STAT] retorna o número de mensagens e seu tamanho total em uma única linha. A senha é exibida na forma [*****];
- linhas 30–33: o protocolo POP3 não registra as mensagens lidas; todas as mensagens são tratadas como novas. A função [range(1, n)] retorna o array [1, 2, ..., n];
- linhas 37–46: o comando [TOP n 0] retorna os cabeçalhos da mensagem nº n seguidos de 0 linha de seu corpo. O comando [LIST n] retorna seu tamanho. A função [array_intersect_key] mantém apenas os cabeçalhos cujos nomes são chaves do array retornado por [array_flip]. O operador [...] copia esses cabeçalhos para o array retornado, ao qual o tamanho é adicionado;
- linhas 50–54: o comando [RETR n] retorna a mensagem nº n;
- linhas 64–74: o comando [QUIT] exclui as mensagens marcadas pelo comando [DELE]. A conexão é fechada em todos os casos (bloco [finally]);
- linha 80: o método [command] é a função [sendCommand] de [pop3-01.php]. No modo de rastreamento, as linhas de uma resposta de várias linhas não são exibidas; apenas seu número é mostrado.
16.6.5.4. A classe [ImapClient]
| <?php
declare(strict_types=1);
require_once __DIR__ . "/TcpClient.php";
require_once __DIR__ . "/MailClient.php";
require_once __DIR__ . "/MimePart.php";
// cliente IMAP: os comandos LOGIN, SELECT, SEARCH, FETCH, STORE, EXPUNGE, LOGOUT
// cada comando é precedido por uma tag (A0001, A0002...); o servidor envia
// respostas [* ...] e termina com uma resposta [tag OK|NO|BAD ...]
final class ImapClient extends TcpClient implements MailClient
{
// número do último comando enviado (usado para montar as tags)
private int $number = 0;
// há mensagens marcadas como "to be deleted"?
private bool $deletions = false;
#[\Override]
public function connect(): int
{
$this->openConnection();
// mensagem de boas-vindas do servidor: [* OK ...]
[$welcome] = $this->readResponse();
if (!str_starts_with($welcome, "* OK")) {
throw new RuntimeException("the server refuses the connection: $welcome");
}
// autenticação
$this->command("LOGIN " . self::quote($this->info["user"]) . " " . self::quote($this->info["password"]),
"LOGIN " . self::quote($this->info["user"]) . " *****");
// seleção da caixa de correio: uma das respostas tem a forma [* n EXISTS]
$responses = $this->command("SELECT " . self::quote($this->info["mailbox"] ?? "INBOX"));
$exists = array_find($responses, fn(array $response): bool => ($response[1] ?? "") === "EXISTS");
return (int) ($exists[0] ?? 0);
}
#[\Override]
public function unread(): array
{
// a resposta tem a forma [* SEARCH n1 n2 ...]
$responses = $this->command("SEARCH UNSEEN");
$search = array_find($responses, fn(array $response): bool => $response[0] === "SEARCH") ?? ["SEARCH"];
return array_map(intval(...), array_slice($search, 1));
}
#[\Override]
public function headers(int $n): array
{
// BODY.PEEK[HEADER]: os cabeçalhos da mensagem, sem marcá-la como lida
$data = $this->fetch($n, "(FLAGS RFC822.SIZE BODY.PEEK[HEADER])");
$headers = self::parseHeaders($data["BODY[HEADER]"]);
// mantemos apenas os principais cabeçalhos
$summary = array_intersect_key($headers, array_flip(["Date", "From", "To", "Subject", "Message-ID"]));
return [...$summary, "Flags" => implode(" ", $data["FLAGS"]), "Size" => $data["RFC822.SIZE"]];
}
#[\Override]
public function message(int $n): string
{
// BODY[]: a mensagem inteira; o servidor a marca como lida (flag \Seen)
return $this->fetch($n, "BODY[]")["BODY[]"];
}
// a estrutura MIME da mensagem nº $n
public function structure(int $n): MimePart
{
return MimePart::fromBodyStructure($this->fetch($n, "BODYSTRUCTURE")["BODYSTRUCTURE"]);
}
// o conteúdo (codificado) da parte nº $section (1, 1.2...) da mensagem nº $n
public function part(int $n, string $section): string
{
return $this->fetch($n, "BODY[$section]")["BODY[$section]"] ?? "";
}
#[\Override]
public function delete(int $n): void
{
// adicionamos o flag \Deleted à mensagem
$this->command("STORE $n +FLAGS (\\Deleted)");
$this->deletions = true;
}
#[\Override]
public function close(): void
{
// nada a fazer se a conexão não pôde ser aberta
if ($this->connection === null) {
return;
}
try {
// EXPUNGE exclui as mensagens que têm o flag \Deleted
if ($this->deletions) {
$this->command("EXPUNGE");
}
$this->command("LOGOUT");
} finally {
$this->closeConnection();
}
}
// comando FETCH n items: retorna o dicionário [item => valor] da resposta
// [* n FETCH (item1 value1 item2 value2 ...)]
private function fetch(int $n, string $items): array
{
$responses = $this->command("FETCH $n $items");
$fetch = array_find($responses, fn(array $response): bool => ($response[1] ?? "") === "FETCH");
if ($fetch === null) {
throw new RuntimeException("no message no. $n");
}
$dictionary = [];
foreach (array_chunk($fetch[2], 2) as [$key, $value]) {
$dictionary[strtoupper($key)] = $value;
}
return $dictionary;
}
// envia um comando com tag e retorna suas respostas [* ...], cada uma dividida em tokens
// $display: o que deve ser exibido no modo de rastreamento (para ocultar uma senha)
private function command(string $command, ?string $display = null): array
{
$tag = sprintf("A%04d", ++$this->number);
$this->send("$tag $command", $display === null ? null : "$tag $display");
$responses = [];
while (true) {
[$text, $literals] = $this->readResponse();
// resposta final [tag OK|NO|BAD text]?
if (str_starts_with($text, "$tag ")) {
$status = substr($text, strlen($tag) + 1);
if (!str_starts_with($status, "OK")) {
throw new RuntimeException("[" . ($display ?? $command) . "]: $status");
}
return $responses;
}
// resposta [* ...]
if (str_starts_with($text, "* ")) {
$position = 2;
$responses[] = self::tokens($text, $position, $literals);
}
}
}
// lê uma resposta do servidor: uma linha que pode conter literais. Um literal
// é anunciado por {n} no fim da linha: seguem-se n bytes, depois o resto da linha.
// retorna o texto da resposta, no qual o literal nº k é substituído por \0k\0, e os literais
private function readResponse(): array
{
$text = "";
$literals = [];
while (true) {
$line = $this->readLine();
if (preg_match('/\{(\d+)\}$/', $line, $fields) !== 1) {
return [$text . $line, $literals];
}
$text .= substr($line, 0, -strlen($fields[0])) . "\0" . count($literals) . "\0";
$literals[] = $this->readBytes((int) $fields[1]);
}
}
// divide $text em tokens a partir da posição $position, até o fim do texto ou
// até um parêntese de fechamento. Uma lista (...) torna-se um array, NIL torna-se null,
// uma string "..." ou um literal torna-se uma string, todo o resto (átomo) também
private static function tokens(string $text, int &$position, array $literals): array
{
$tokens = [];
$length = strlen($text);
while ($position < $length) {
$c = $text[$position];
if ($c === " ") {
$position++;
} elseif ($c === "(") {
// uma lista: chamada recursiva
$position++;
$tokens[] = self::tokens($text, $position, $literals);
} elseif ($c === ")") {
// fim da lista atual
$position++;
return $tokens;
} elseif ($c === '"') {
// uma string entre aspas em que \" e \\ representam " e \
$string = "";
for ($position++; $text[$position] !== '"'; $position++) {
if ($text[$position] === "\\") {
$position++;
}
$string .= $text[$position];
}
$position++;
$tokens[] = $string;
} elseif ($c === "\0") {
// um literal
$end = strpos($text, "\0", $position + 1);
$tokens[] = $literals[(int) substr($text, $position + 1, $end - $position - 1)];
$position = $end + 1;
} else {
// um átomo: até o próximo espaço ou parêntese, exceto dentro de colchetes
// (BODY[HEADER.FIELDS (FROM TO)] é um único átomo)
$start = $position;
$brackets = 0;
while ($position < $length
&& ($brackets > 0 || !in_array($text[$position], [" ", "(", ")"], true))) {
$brackets += match ($text[$position]) { "[" => 1, "]" => -1, default => 0 };
$position++;
}
$atom = substr($text, $start, $position - $start);
$tokens[] = $atom === "NIL" ? null : $atom;
}
}
return $tokens;
}
// uma string IMAP: entre aspas, com \ antes dos caracteres " e \
private static function quote(string $text): string
{
return '"' . addcslashes($text, '"\\') . '"';
}
}
|
- linha 15: o número do último comando. Ele é usado para gerar os rótulos [A0001], [A0002]...;
- linhas 20–34: a conexão. O servidor primeiro envia uma mensagem de boas-vindas: [* OK ...]. Os comandos [LOGIN] e [SELECT] são então enviados. O método [command] retorna as respostas do servidor [* ...], cada uma dividida em tokens: a resposta [* 2 EXISTS] torna-se o array [["2", "EXISTS"]]. A função [array_find] (PHP 8.4) retorna o primeiro elemento do array que satisfaz a condição, ou [null];
- linhas 38–43: o comando [SEARCH UNSEEN]. O resultado [* SEARCH 1 2] torna-se [["SEARCH", "1", "2"]]. Mantemos os elementos a partir do número 1 ([array_slice]), que são convertidos em inteiros pela função [intval]. A notação [intval(...)] (PHP 8.1) cria uma função a partir da função [intval]: é a sintaxe das first-class callables;
- linhas 47–54: o comando [FETCH n (FLAGS RFC822.SIZE BODY.PEEK[HEADER])] retorna as flags, o tamanho e os cabeçalhos da mensagem nº n;
- linhas 58–61: o comando [FETCH n BODY[]] retorna a mensagem nº n por inteiro. O servidor adiciona a ela a flag [\Seen]: a mensagem agora está marcada como lida;
- linhas 65–67: o comando [FETCH n BODYSTRUCTURE] retorna a estrutura da mensagem, que a classe [MimePart] transforma em uma árvore de objetos;
- linhas 71–73: o comando [FETCH n BODY[section]] retorna o conteúdo da parte nº [section] da mensagem, tal como codificado na mensagem (Base64, quoted-printable etc.);
- linhas 77–81: o comando [STORE n +FLAGS (\Deleted)] adiciona a flag [\Deleted] à mensagem. Ela ainda não foi removida;
- linhas 85–98: o comando [EXPUNGE] exclui as mensagens que têm a flag [\Deleted]. O comando [LOGOUT] encerra o diálogo;
- linhas 104–115: o método [fetch] envia um comando [FETCH] e converte a lista de resposta [[* n FETCH (item1 value1 item2 value2...)]] em um dicionário [[item1 => value1, item2 => value2...]]. A função [array_chunk] divide a lista em pares, que o laço [foreach] desempacota em [[$key, $value]];
- linhas 120–133: o método [command] envia um comando precedido de seu rótulo e depois lê as respostas do servidor até encontrar a que começa com o rótulo. Se essa resposta final não for [OK], uma exceção é lançada;
- linhas 146–153: leitura de uma resposta. Se uma linha terminar com [{n}], ela é seguida por n bytes (o literal) e depois pelo restante da resposta. No texto da resposta, cada literal é substituído por um marcador [\0k\0] (\0 é o caractere de código 0, que não pode aparecer em uma linha de texto IMAP) e seu conteúdo é armazenado no array [$literals];
- linhas 163–209: o método [tokens] divide o texto de uma resposta em tokens:
- uma lista entre parênteses se torna um array. O método chama a si mesmo (chamada recursiva) para analisar o conteúdo da lista e devolve o controle no parêntese de fechamento;
- uma string entre aspas ou um literal se torna uma string;
- [NIL] torna-se [null];
- todo o resto (um átomo) se torna uma string. Um átomo pode conter colchetes, que por sua vez podem conter espaços e parênteses: [BODY[HEADER.FIELDS (FROM TO)]] é um único átomo. A expressão [match] soma 1 ao contador de colchetes abertos para [[] e subtrai 1 dele para []];
- O parâmetro [$position], passado por referência, é a posição atual no texto: ela avança conforme a análise prossegue, inclusive nas chamadas recursivas;
- Linha 213: uma string IMAP é delimitada por aspas. A função [addcslashes] acrescenta um caractere [\] antes dos caracteres ["] e [\].
16.6.5.5. A classe [MimePart]
| <?php
declare(strict_types=1);
// uma parte de uma mensagem MIME, conforme descrita pela resposta BODYSTRUCTURE de um servidor IMAP
// uma mensagem é uma árvore de partes: uma parte [multipart/xxx] tem subpartes
final readonly class MimePart
{
public function __construct(
// tipo e subtipo MIME em minúsculas: text/plain, multipart/mixed, application/pdf...
public string $type,
public string $subType,
// parâmetros do tipo, por exemplo [charset => utf-8]
public array $parameters = [],
// codificação do conteúdo: 7bit, 8bit, base64, quoted-printable...
public string $encoding = "7bit",
// disposição (attachment, inline) ou null, e seus parâmetros, por exemplo [filename => x.pdf]
public ?string $disposition = null,
public array $dispositionParameters = [],
// as subpartes de uma parte [multipart/xxx]
public array $parts = [],
) {
}
// constrói a árvore de partes a partir da lista de tokens de BODYSTRUCTURE
public static function fromBodyStructure(array $structure): self
{
// parte múltipla: ((subparte 1) (subparte 2)... "subtipo" (parâmetros) disposição...)
if (is_array($structure[0])) {
// as subpartes são os primeiros elementos que são listas
$parts = [];
$i = 0;
while (is_array($structure[$i])) {
$parts[] = self::fromBodyStructure($structure[$i++]);
}
return new self(
type: "multipart",
subType: strtolower($structure[$i]),
parameters: self::dictionary($structure[$i + 1] ?? null),
disposition: self::disposition($structure[$i + 2] ?? null)[0],
dispositionParameters: self::disposition($structure[$i + 2] ?? null)[1],
parts: $parts,
);
}
// parte simples: ("tipo" "subtipo" (parâmetros) id descrição "codificação" tamanho ...)
$type = strtolower($structure[0]);
$subType = strtolower($structure[1]);
// a disposição vem depois de campos que dependem do tipo da parte
$dispositionIndex = match (true) {
// text/xxx: ... tamanho nbLinhas md5 disposição
$type === "text" => 9,
// message/rfc822: ... tamanho envelope estrutura nbLinhas md5 disposição
$type === "message" && $subType === "rfc822" => 11,
// outros: ... tamanho md5 disposição
default => 8,
};
[$disposition, $dispositionParameters] = self::disposition($structure[$dispositionIndex] ?? null);
return new self(
type: $type,
subType: $subType,
parameters: self::dictionary($structure[2]),
encoding: strtolower($structure[5] ?? "7bit"),
disposition: $disposition,
dispositionParameters: $dispositionParameters,
);
}
// o nome de arquivo de um anexo, ou null
public function fileName(): ?string
{
// o nome é o parâmetro [filename] da disposição ou, na falta dele, o parâmetro [name]
// do tipo. Ele pode ser codificado de duas maneiras:
// - filename*=utf-8''Tah%C3%A9.png (RFC 2231);
// - name="=?utf-8?Q?Tah=C3=A9.png?=" (RFC 2047);
$encoded = $this->dispositionParameters["filename*"] ?? $this->parameters["name*"] ?? null;
if ($encoded !== null) {
// conjunto de caracteres''nome codificado em URL
[$charset, , $name] = explode("'", $encoded, 3);
return mb_convert_encoding(rawurldecode($name), "UTF-8", $charset);
}
$name = $this->dispositionParameters["filename"] ?? $this->parameters["name"] ?? null;
return $name === null ? null : iconv_mime_decode($name, ICONV_MIME_DECODE_CONTINUE_ON_ERROR, "UTF-8");
}
// uma lista IMAP (key1 value1 key2 value2...) ou NIL transformada em dicionário
private static function dictionary(?array $list): array
{
$dictionary = [];
foreach (array_chunk($list ?? [], 2) as [$key, $value]) {
$dictionary[strtolower($key)] = $value;
}
return $dictionary;
}
// uma disposição IMAP ("attachment" (parâmetros)) ou NIL: retorna [disposição, parâmetros]
private static function disposition(mixed $disposition): array
{
if (!is_array($disposition)) {
return [null, []];
}
return [strtolower($disposition[0]), self::dictionary($disposition[1] ?? null)];
}
}
|
- linha 7: uma classe [readonly] (PHP 8.2) possui apenas propriedades somente leitura: depois de construído, um objeto [MimePart] não pode mais ser modificado;
- Linhas 9–22: todas as propriedades são declaradas por promoção dos parâmetros do construtor. Elas têm valores padrão, o que permite passar apenas certos parâmetros por nome (argumentos nomeados);
- linha 26: o método estático [fromBodyStructure] constrói a árvore de partes a partir da lista de tokens da resposta [BODYSTRUCTURE];
- linhas 29–42: uma parte múltipla começa com as listas de suas subpartes, cada uma das quais é convertida em um objeto [MimePart] por meio de uma chamada recursiva. Em seguida vêm seu subtipo (mixed, alternative etc.), seus parâmetros (boundary) e sua disposição;
- linhas 45–57: uma parte simples começa com seu tipo, subtipo, parâmetros, um identificador, uma descrição, sua codificação e seu tamanho. A posição da disposição depende do tipo da parte: uma parte [text/xxx] inclui também uma contagem de linhas; uma parte [message/rfc822] inclui também o envelope e a estrutura da mensagem, além de uma contagem de linhas. A expressão [match (true)] seleciona o primeiro ramo cuja condição é verdadeira;
- linhas 69–82: o nome de arquivo de um anexo. Vimos no [Mailpit] que ele pode ser codificado de duas maneiras:
- a codificação RFC 2231 [utf-8''Tah%C3%A9.png]: o conjunto de caracteres, dois apóstrofos, seguidos do nome codificado como em uma URL. Ele é decodificado com [rawurldecode] e depois convertido para UTF-8 com [mb_convert_encoding];
- a codificação RFC 2047 [=?utf-8?Q?Tah=C3=A9.png?=]: decodifique-a com a função [iconv_mime_decode];
- Linha 86: uma lista IMAP [("charset" "utf-8")] torna-se o dicionário [["charset" => "utf-8"]];
- linha 96: uma disposição [("attachment" ("filename" "x.pdf"))] torna-se o array [["attachment", ["filename" => "x.pdf"]]].
16.6.6. Cliente POP3 / IMAP [imap-01.php]
O script [imap-01.php] tem a mesma finalidade que o script de mesmo nome do curso de PHP 7, que usava as funções [imap_open], [imap_num_msg], [imap_search], [imap_headerinfo], [imap_body], [imap_delete], [imap_expunge] e [imap_close]. Ele usa o seguinte arquivo JSON [config-imap-01.json]:
| {
"imap.gmail.com:993": {
"enabled": false,
"protocol": "imap",
"server": "imap.gmail.com",
"port": 993,
"tls": true,
"verify-peer": true,
"user": "php8parlexemple@gmail.com",
"password": "application password",
"mailbox": "INBOX",
"output-dir": "output/gmail-imap"
},
"localhost:993": {
"protocol": "imap",
"server": "localhost",
"port": 993,
"tls": true,
"verify-peer": false,
"user": "guest@localhost",
"password": "guest",
"mailbox": "INBOX",
"output-dir": "output/localhost-imap"
},
"localhost:1110": {
"protocol": "pop3",
"server": "localhost",
"port": 1110,
"tls": false,
"user": "guest",
"password": "guest",
"output-dir": "output/localhost-pop3"
}
}
|
O arquivo [config-imap-01.json] define um dicionário de servidores IMAP / POP3 a serem contatados. Cada entrada tem a forma [key => value], em que:
- [key]: é um nome que designa o servidor. Temos três aqui:
- [imap.gmail.com:993]: o servidor IMAP do Gmail, que escuta na porta 993 com uma conexão criptografada. Ele está desativado ([enabled] igual a [false]): informe ali seu endereço do Gmail e uma senha de app e, em seguida, mude [enabled] para [true];
- [localhost:993]: o servidor IMAP local, com uma conexão criptografada por um certificado autoassinado, que não é verificado;
- [localhost:1110]: o servidor POP3 do [Mailpit];
- [value]: é um dicionário que especifica os seguintes pontos:
- [protocol]: o protocolo, [imap] ou [pop3];
- [server]: o nome do servidor, IMAP ou POP3;
- [port]: a porta do servidor (IMAP ou POP3);
- [tls]: a conexão é criptografada?
- [verify-peer]: o certificado do servidor deve ser verificado? No Windows, se a verificação falhar com um servidor público, confirme que a diretiva [openssl.cafile] do arquivo [php.ini] aponta para um arquivo de autoridades certificadoras, como faz o [Laragon];
- [user]: o proprietário da caixa de correio;
- [password]: a senha do proprietário da caixa de correio;
- [mailbox]: a caixa de correio IMAP a ser lida, sendo INBOX aquela em que chegam as novas mensagens;
- [output-dir]: a pasta em que as mensagens devem ser salvas.
Com o protocolo POP3, depois que uma mensagem é lida, ela é excluída. É assim que os servidores POP3 normalmente funcionam: uma mensagem lida não é mantida no servidor.
O script [imap-01.php] é o seguinte:
| <?php
declare(strict_types=1);
// cliente IMAP (Internet Message Access Protocol) / POP3 usado para ler e-mails
// as caixas de correio a serem lidas são descritas em um arquivo de configuração
require_once __DIR__ . "/ImapClient.php";
require_once __DIR__ . "/Pop3Client.php";
// os parâmetros para a leitura dos e-mails
const CONFIG_FILE_NAME = "config-imap-01.json";
// exibir as trocas cliente / servidor?
const TRACKING = false;
// recuperamos a configuração
$mailboxes = json_decode(file_get_contents(CONFIG_FILE_NAME), true);
// leitura das caixas de correio
foreach ($mailboxes as $name => $info) {
// caixa de correio desativada na configuração?
if (($info["enabled"] ?? true) === false) {
print "------------Mailbox [$name] disabled\n";
continue;
}
// acompanhamento
print "------------Reading the mailbox [$name]\n";
// leitura da caixa de correio
readmailbox($name, $info);
}
// fim
print "Done\n";
// --------------------------------------------------------------------------
function createClient(array $info): MailClient
{
// um cliente IMAP ou POP3 conforme a configuração
return match ($info["protocol"]) {
"imap" => new ImapClient($info, TRACKING),
"pop3" => new Pop3Client($info, TRACKING),
};
}
// --------------------------------------------------------------------------
function readmailbox(string $name, array $info): void
{
// o cliente da caixa de correio
$client = createClient($info);
try {
// conexão
$nbmsg = $client->connect();
print "Connection established with the server [$name].\n";
// total de mensagens na caixa de correio
print "There are [$nbmsg] messages in the mailbox [$name]\n";
if ($nbmsg === 0) {
return;
}
// mensagens não lidas na caixa de correio
print "Retrieving the list of the unread messages of the mailbox [$name]\n";
$msgNumbers = $client->unread();
if (count($msgNumbers) === 0) {
print "There are no new messages in the mailbox [$name]\n";
return;
}
foreach ($msgNumbers as $msgNumber) {
// recuperamos os cabeçalhos da mensagem nº $msgNumber
print "Headers of the message no. [$msgNumber] of the mailbox [$name]\n";
print_r($client->headers($msgNumber));
// recuperamos o texto completo da mensagem nº $msgNumber e o salvamos
saveMessage($client->message($msgNumber), $msgNumber, $info);
// se o protocolo for POP3, excluímos a mensagem
if ($info["protocol"] === "pop3") {
$client->delete($msgNumber);
}
}
} catch (RuntimeException $ex) {
print "Error: " . $ex->getMessage() . "\n";
} finally {
// em todos os casos, fechamos a conexão
try {
$client->close();
print "Connection closed successfully.\n";
} catch (RuntimeException $ex) {
print "Closing the connection failed: " . $ex->getMessage() . "\n";
}
}
}
// --------------------------------------------------------------------------
function saveMessage(string $message, int $msgNumber, array $info): void
{
// a mensagem é salva no arquivo [output-dir/message-N.eml]
$fileName = "{$info["output-dir"]}/message-$msgNumber.eml";
print "Saving the message in the file [$fileName]\n";
// criamos a pasta, se necessário (true: com suas pastas pai)
if (!is_dir($info["output-dir"])) {
mkdir($info["output-dir"], recursive: true);
}
// salvamos a mensagem
if (file_put_contents($fileName, $message) === false) {
print "Saving failed\n";
}
}
|
Comentários:
- linhas 8–9: as classes dos dois clientes são carregadas, e elas por sua vez carregam a classe [TcpClient] e a interface [MailClient];
- Linha 14: com [true], as trocas cliente/servidor são exibidas. Experimente;
- linhas 20–29: percorremos todos os servidores encontrados no arquivo de configuração, exceto os desativados;
- linhas 35–41: a função [createClient] devolve um cliente IMAP ou POP3, conforme a configuração. Seu tipo de retorno é a interface [MailClient]: o restante do script não sabe com qual protocolo está lidando. Isso é polimorfismo;
- linha 51: conexão e autenticação;
- linha 60: os números das mensagens não lidas;
- linha 68: os cabeçalhos da mensagem são exibidos com a função [print_r];
- linha 70: o texto completo da mensagem é salvo em um arquivo;
- linha 72: com o protocolo POP3, a mensagem é marcada para exclusão;
- linhas 78–86: em todos os casos, a conexão é fechada, o que exclui as mensagens marcadas. Se as instruções [return] do bloco [try] forem executadas, o bloco [finally] também é executado;
- linha 97: a função [mkdir] cria a pasta, junto com suas pastas pai, por meio do argumento nomeado [recursive: true].
Vamos executar o script [smtp-02.php] para que o usuário [guest@localhost] tenha novas mensagens. Feito isso, vamos executar o script [imap-01.php] para ler as caixas de correio. A saída no console é a seguinte:
| > php imap-01.php
------------Mailbox [imap.gmail.com:993] disabled
------------Reading the mailbox [localhost:993]
Connection established with the server [localhost:993].
There are [2] messages in the mailbox [localhost:993]
Retrieving the list of the unread messages of the mailbox [localhost:993]
Headers of the message no. [1] of the mailbox [localhost:993]
Array
(
[From] => guest@localhost
[To] => guest@localhost
[Subject] => test-localhost
[Message-ID] => <b80fff003b5b37b74244dc69674f3ce4@localhost>
[Date] => Thu, 01 Oct 2026 17:14:39 +0200
[Flags] =>
[Size] => 259683
)
Saving the message in the file [output/localhost-imap/message-1.eml]
Headers of the message no. [2] of the mailbox [localhost:993]
Array
(
[From] => guest@localhost
[To] => guest@localhost
[Subject] => test-secure-server
[Message-ID] => <759bf5367e3f1136ce964ded7f702e09@localhost>
[Date] => Thu, 01 Oct 2026 17:14:39 +0200
[Flags] =>
[Size] => 28101
)
Saving the message in the file [output/localhost-imap/message-2.eml]
Connection closed successfully.
------------Reading the mailbox [localhost:1110]
Connection established with the server [localhost:1110].
There are [2] messages in the mailbox [localhost:1110]
Retrieving the list of the unread messages of the mailbox [localhost:1110]
Headers of the message no. [1] of the mailbox [localhost:1110]
Array
(
[From] => guest@localhost
[To] => guest@localhost
[Subject] => test-secure-server
[Message-ID] => <759bf5367e3f1136ce964ded7f702e09@localhost>
[Date] => Thu, 01 Oct 2026 17:14:39 +0200
[Size] => 28101
)
Saving the message in the file [output/localhost-pop3/message-1.eml]
Headers of the message no. [2] of the mailbox [localhost:1110]
Array
(
[From] => guest@localhost
[To] => guest@localhost
[Subject] => test-localhost
[Message-ID] => <b80fff003b5b37b74244dc69674f3ce4@localhost>
[Date] => Thu, 01 Oct 2026 17:14:39 +0200
[Size] => 259683
)
Saving the message in the file [output/localhost-pop3/message-2.eml]
Connection closed successfully.
Done
|
- Com IMAP, as duas mensagens depositadas na caixa de correio INBOX são lidas. Os flags [Flags] estão vazios: as mensagens ainda não foram lidas;
- com POP3, encontramos as mesmas mensagens na caixa de correio do [Mailpit], em ordem inversa. As mensagens lidas são excluídas.
Se em seguida executarmos imediatamente o script [imap-01.php] novamente, os resultados são os seguintes:
| > php imap-01.php
------------Mailbox [imap.gmail.com:993] disabled
------------Reading the mailbox [localhost:993]
Connection established with the server [localhost:993].
There are [2] messages in the mailbox [localhost:993]
Retrieving the list of the unread messages of the mailbox [localhost:993]
There are no new messages in the mailbox [localhost:993]
Connection closed successfully.
------------Reading the mailbox [localhost:1110]
Connection established with the server [localhost:1110].
There are [0] messages in the mailbox [localhost:1110]
Connection closed successfully.
Done
|
- Continua havendo o mesmo número de mensagens na caixa de correio IMAP, mas não há mais mensagens não lidas. Isso mostra que a execução anterior mudou o estado das mensagens lidas de “não lida” para “lida” (flag [\Seen]);
- Não há mais mensagens na caixa de entrada POP3: elas foram excluídas durante a execução anterior.
As mensagens foram salvas localmente nas pastas [output/localhost-imap] e [output/localhost-pop3] , com os nomes [message-1.eml] e [message-2.eml]. A extensão de arquivo [.eml] é usada para arquivos de e-mail: um clique duplo em um desses arquivos o abre no cliente de e-mail do Windows. O conteúdo do arquivo é composto pelo texto completo da mensagem, como vimos na aba [Raw] do [Mailpit]: o texto da mensagem e o conteúdo codificado dos anexos estão misturados ali.
Vamos tentar melhorar esse script para que as diversas partes da mensagem e os anexos sejam armazenados em arquivos separados.
16.6.7. Cliente IMAP aprimorado ([imap-02.php])
O servidor IMAP pode nos fornecer a estrutura de uma mensagem (comando [BODYSTRUCTURE]) e depois o conteúdo de cada uma de suas partes (comando [FETCH n BODY[section]]). Vamos usar isso no script [imap-02.php]. O protocolo POP3, por outro lado, só reconhece a mensagem inteira: o script processará apenas as caixas de correio IMAP.
Vamos retomar a resposta ao comando [BODYSTRUCTURE] obtida quando descobrimos o protocolo IMAP. Ela descreve uma mensagem do tipo [multipart/mixed] que tem seis partes:
- a primeira parte é do tipo [multipart/alternative]. Ela mesma tem duas subpartes: [text/plain] e [text/html], codificadas em [quoted-printable] e com o parâmetro [charset=utf-8];
- as cinco partes seguintes são os anexos, codificados em [base64], cada um com a disposição [attachment] e um nome de arquivo.
As partes são numeradas da seguinte forma:
- a mensagem inteira, do tipo [multipart/mixed], não tem número. Suas partes são numeradas 1, 2...;
- quando uma parte tem subpartes, elas são numeradas x.1, x.2..., em que x é o número da parte que as contém. Assim, o texto [text/plain] da mensagem é a parte nº 1.1: foi a que solicitamos com o comando [FETCH 2 BODY.PEEK[1.1]].
O script [imap-02.php] é o seguinte:
| <?php
declare(strict_types=1);
// cliente IMAP que salva separadamente os textos e os anexos das mensagens não lidas
// ele usa a estrutura MIME das mensagens fornecida pelo servidor IMAP (comando BODYSTRUCTURE)
require_once __DIR__ . "/ImapClient.php";
// os parâmetros para a leitura dos e-mails
const CONFIG_FILE_NAME = "config-imap-01.json";
// recuperamos a configuração
$mailboxes = json_decode(file_get_contents(CONFIG_FILE_NAME), true);
// leitura das caixas de correio
foreach ($mailboxes as $name => $info) {
// só nos interessam as caixas de correio IMAP ativas
if (($info["enabled"] ?? true) === false || $info["protocol"] !== "imap") {
continue;
}
print "------------Reading the mailbox [$name]\n";
readmailbox($name, $info);
}
// fim
print "Done\n";
// --------------------------------------------------------------------------
function readmailbox(string $name, array $info): void
{
$client = new ImapClient($info);
try {
// conexão
$nbmsg = $client->connect();
print "Connection established with the server [$name].\n";
print "There are [$nbmsg] messages in the mailbox [$name]\n";
// mensagens não lidas
print "Retrieving the list of the unread messages of the mailbox [$name]\n";
$msgNumbers = $client->unread();
if (count($msgNumbers) === 0) {
print "There are no new messages in the mailbox [$name]\n";
}
foreach ($msgNumbers as $msgNumber) {
// os cabeçalhos da mensagem serão usados como prefixo de seus textos
$headers = $client->headers($msgNumber);
// a estrutura da mensagem
$structure = $client->structure($msgNumber);
// percorremos suas partes
$outputDir = "{$info["output-dir"]}/message-$msgNumber";
getParts($client, $msgNumber, $structure, "", $outputDir, $headers);
}
} catch (RuntimeException $ex) {
print "Error: " . $ex->getMessage() . "\n";
} finally {
try {
$client->close();
print "Connection closed successfully.\n";
} catch (RuntimeException $ex) {
print "Closing the connection failed: " . $ex->getMessage() . "\n";
}
}
}
// --------------------------------------------------------------------------
function getParts(ImapClient $client, int $msgNumber, MimePart $part, string $section,
string $outputDir, array $headers): void
{
// exibe o tipo da parte [$part] da mensagem nº $msgNumber e, em seguida:
// - se tiver subpartes, processa-as uma a uma (chamada recursiva);
// - caso contrário, salva-a na pasta [$outputDir]
// $section é o número IMAP da parte: 1, 2, 1.1, 1.2...
// a parte raiz (a mensagem inteira) não tem número: exibimos 0
print "-----content of the part no. [" . ($section === "" ? "0" : $section) . "]\n";
print "Content-Type: " . strtoupper("$part->type/$part->subType") . "\n";
print "Transfer-Encoding: $part->encoding\n";
// subpartes?
if ($part->type === "multipart") {
foreach ($part->parts as $i => $subpart) {
// as subpartes da parte nº x são numeradas x.1, x.2...
$subsection = $section === "" ? (string) ($i + 1) : "$section." . ($i + 1);
getParts($client, $msgNumber, $subpart, $subsection, $outputDir, $headers);
}
return;
}
// uma mensagem que não é multipart tem uma única parte, numerada 1
if ($section === "") {
$section = "1";
}
// salvamos a parte
savePart($client, $msgNumber, $part, $section, $outputDir, $headers);
}
// --------------------------------------------------------------------------
function savePart(ImapClient $client, int $msgNumber, MimePart $part, string $section,
string $outputDir, array $headers): void
{
// se a pasta não existir, nós a criamos
if (!is_dir($outputDir)) {
mkdir($outputDir, recursive: true);
}
// um anexo?
$fileName = $part->fileName();
if ($part->disposition === "attachment" && $fileName !== null) {
saveAttachment($client->part($msgNumber, $section), $part, "$outputDir/$fileName");
return;
}
// um texto?
match ("$part->type/$part->subType") {
"text/plain" => saveText("$outputDir/message.txt", false,
$client->part($msgNumber, $section), $part, $headers),
"text/html" => saveText("$outputDir/message.html", true,
$client->part($msgNumber, $section), $part, $headers),
// demais casos: esta parte não será processada
default => print "Part [$section] ignored\n",
};
}
// --------------------------------------------------------------------------
function decode(string $text, string $encoding): string
{
// decodificação de um conteúdo codificado em base64 ou em quoted-printable
return match ($encoding) {
"base64" => base64_decode($text),
"quoted-printable" => quoted_printable_decode($text),
// 7bit, 8bit, binary: sem codificação
default => $text,
};
}
// --------------------------------------------------------------------------
function saveText(string $fileName, bool $html, string $text, MimePart $part, array $headers): void
{
// o texto é decodificado e depois convertido para UTF-8 se usar outro conjunto de caracteres
$text = decode($text, $part->encoding);
$charset = $part->parameters["charset"] ?? "utf-8";
if (strtolower($charset) !== "utf-8") {
$text = mb_convert_encoding($text, "UTF-8", $charset);
}
// nós o precedemos com os cabeçalhos From, To, Subject da mensagem
$endOfLine = $html ? "<br/>\n" : "\n";
$content = "From: {$headers["From"]}$endOfLine"
. "To: {$headers["To"]}$endOfLine"
. "Subject: {$headers["Subject"]}$endOfLine$endOfLine"
. $text;
print "Saving a message in [$fileName]\n";
if (file_put_contents($fileName, $content) === false) {
print "Unable to create the file [$fileName]\n";
}
}
// --------------------------------------------------------------------------
function saveAttachment(string $content, MimePart $part, string $fileName): void
{
print "Saving the attachment in [$fileName]\n";
if (file_put_contents($fileName, decode($content, $part->encoding)) === false) {
print "The attachment could not be saved in [$fileName]\n";
}
}
|
Comentários:
- linha 19: apenas as caixas de correio IMAP ativas são lidas;
- linha 45: os cabeçalhos da mensagem serão usados como prefixo do texto armazenado;
- linha 47: a estrutura da mensagem: um objeto [MimePart];
- linha 50: a função [getParts] percorre as partes da mensagem. Ela começa pela parte raiz — a mensagem inteira —, que não tem número de seção;
- linha 65: a função [getParts] recebe os seguintes parâmetros:
- [$client]: o cliente IMAP;
- [$msgNumber]: o número da mensagem cujas partes são solicitadas;
- [$part]: um objeto que representa uma parte da mensagem;
- [$section]: o número dessa parte;
- [$outputDir]: a pasta em que as partes devem ser salvas;
- [$headers]: informações gerais sobre o e-mail (remetente, destinatário, assunto etc.);
- linhas 73–75: o número da parte, o tipo de conteúdo e a codificação são exibidos. A mensagem inteira é exibida como parte de número 0;
- linhas 77–83: se a parte tem subpartes, cada uma é obtida por meio de uma chamada recursiva à função [getParts]. Seu número de seção é [$section.i];
- linhas 86–87: uma mensagem que não é multipart (texto simples) tem apenas uma parte, numerada 1;
- linha 90: quando não há subpartes, o conteúdo da parte é armazenado;
- linha 94: a função [savePart] grava uma parte:
- se for um anexo (configuração [attachment]), ele é salvo com a função [saveAttachment] com seu nome de arquivo;
- se o texto for [text/plain] ou [text/html], ele é salvo com a função [saveText] no arquivo [message.txt] ou [message.html]. As demais partes são ignoradas;
- nos dois casos, o conteúdo da seção é solicitado ao servidor IMAP por meio do método [part] do cliente;
- linha 119: o conteúdo de uma seção é codificado. As funções [base64_decode] e [quoted_printable_decode] o decodificam;
- linha 131: o texto é decodificado e depois convertido para UTF-8 com a função [mb_convert_encoding] se usar outro conjunto de caracteres (parâmetro [charset]). Ele é precedido pelos cabeçalhos da mensagem [From], [To] e [Subject]. No caso de texto HTML, cada cabeçalho é seguido de uma tag [<br/>] para que apareça em sua própria linha em um navegador;
- linha 152: um anexo é decodificado e depois salvo.
Para testar o script [imap-02.php], envie primeiro um e-mail para [guest@localhost] com o script [smtp-02.php] (a mensagem [test-localhost] e seus cinco anexos), que é depositado na caixa de correio INBOX do servidor IMAP. Em seguida, ele é lido com [imap-02.php]. A saída no console é a seguinte:
| > php imap-02.php
------------Reading the mailbox [localhost:993]
Connection established with the server [localhost:993].
There are [3] messages in the mailbox [localhost:993]
Retrieving the list of the unread messages of the mailbox [localhost:993]
-----content of the part no. [0]
Content-Type: MULTIPART/MIXED
Transfer-Encoding: 7bit
-----content of the part no. [1]
Content-Type: MULTIPART/ALTERNATIVE
Transfer-Encoding: 7bit
-----content of the part no. [1.1]
Content-Type: TEXT/PLAIN
Transfer-Encoding: quoted-printable
Saving a message in [output/localhost-imap/message-3/message.txt]
-----content of the part no. [1.2]
Content-Type: TEXT/HTML
Transfer-Encoding: quoted-printable
Saving a message in [output/localhost-imap/message-3/message.html]
-----content of the part no. [2]
Content-Type: APPLICATION/VND.OPENXMLFORMATS-OFFICEDOCUMENT.WORDPROCESSINGML.DOCUMENT
Transfer-Encoding: base64
Saving the attachment in [output/localhost-imap/message-3/Hello from Symfony Mailer.docx]
-----content of the part no. [3]
Content-Type: APPLICATION/PDF
Transfer-Encoding: base64
Saving the attachment in [output/localhost-imap/message-3/Hello from Symfony Mailer.pdf]
-----content of the part no. [4]
Content-Type: APPLICATION/VND.OASIS.OPENDOCUMENT.TEXT
Transfer-Encoding: base64
Saving the attachment in [output/localhost-imap/message-3/Hello from Symfony Mailer.odt]
-----content of the part no. [5]
Content-Type: IMAGE/PNG
Transfer-Encoding: base64
Saving the attachment in [output/localhost-imap/message-3/Cours-Tutoriels-Serge-Tahé-1568x268.png]
-----content of the part no. [6]
Content-Type: MESSAGE/RFC822
Transfer-Encoding: base64
Saving the attachment in [output/localhost-imap/message-3/test-localhost.eml]
Connection closed successfully.
Done
|
A estrutura da mensagem é preservada corretamente. Os arquivos foram salvos na pasta [output/localhost-imap/message-3]:
| message-3
├── Cours-Tutoriels-Serge-Tahé-1568x268.png
├── Hello from Symfony Mailer.docx
├── Hello from Symfony Mailer.odt
├── Hello from Symfony Mailer.pdf
├── message.html
├── message.txt
└── test-localhost.eml
|
Os documentos Word, o PDF, o OpenOffice e a imagem abrem normalmente: eles foram decodificados corretamente.
A mensagem anexada [test-localhost.eml] foi salva como anexo. No entanto, ela própria é um e-mail que, por sua vez, contém texto e anexos. Observe na resposta [BODYSTRUCTURE] que o servidor não conseguiu analisar essa mensagem anexada porque ela está codificada em Base64: ele devolve um envelope vazio ([(NIL NIL ...)]) e uma estrutura reduzida a um texto vazio. Para ir além, seria preciso baixar a mensagem anexada, decodificá-la e analisar nós mesmos sua estrutura (MIME). E essa mensagem poderia conter ela própria um e-mail anexado, e assim por diante. Em vez de escrever esse analisador do zero, vamos usar uma biblioteca.
O curso de PHP 7 usava a biblioteca [php-mime-mail-parser], que exigia a extensão PHP [mailparse], a qual precisava ser baixada e instalada separadamente. Vamos usar a biblioteca [zbateson/mail-mime-parser] (https://github.com/zbateson/mail-mime-parser), escrita inteiramente em PHP: ela foi instalada pelo comando [composer install] junto com as demais dependências do curso, sem nenhuma outra ação necessária. Ela analisa o texto completo de uma mensagem, tal como devolvido pelos comandos [RETR] do POP3 e [FETCH n BODY[]] do IMAP. O script [imap-03.php] funcionará, portanto, com os dois protocolos.
Para testá-lo, enviaremos uma mensagem cujo último anexo, [test-localhost-2.eml], contém ele próprio um e-mail anexado, [test-localhost.eml]:
- [test-localhost-2.eml] contém 4 anexos (os documentos Word, o PDF, o OpenOffice e a imagem) e o e-mail [test-localhost.eml];
- [test-localhost.eml] contém os mesmos 4 anexos.
O arquivo de configuração [config-smtp-03.json] descreve esse e-mail:
| {
"mail to localhost via localhost": {
"smtp-server": "localhost",
"smtp-port": 1025,
"from": "guest@localhost",
"to": "guest@localhost",
"subject": "test-localhost-3",
"message": "line 1\nline 2\nline 3",
"tls": false,
"attachments": [
"/attachments/Hello from Symfony Mailer.docx",
"/attachments/Hello from Symfony Mailer.pdf",
"/attachments/Hello from Symfony Mailer.odt",
"/attachments/Cours-Tutoriels-Serge-Tahé-1568x268.png",
"/attachments/test-localhost-2.eml"
]
}
}
|
Ele é usado com o comando [php smtp-02.php config-smtp-03.json].
O script [imap-03.php] usa o mesmo arquivo de configuração, [config-imap-01.json], que os scripts anteriores. Ele é o seguinte:
| <?php
declare(strict_types=1);
// cliente IMAP / POP3 usado para ler e-mails
// a análise das mensagens é confiada à biblioteca [zbateson/mail-mime-parser]
// disponível na URL [https://github.com/zbateson/mail-mime-parser]
// dependências
require_once __DIR__ . "/../../../vendor/autoload.php";
require_once __DIR__ . "/ImapClient.php";
require_once __DIR__ . "/Pop3Client.php";
use ZBateson\MailMimeParser\IMessage;
use ZBateson\MailMimeParser\Message;
// os parâmetros para a leitura dos e-mails
const CONFIG_FILE_NAME = "config-imap-01.json";
// recuperamos a configuração
if (!file_exists(CONFIG_FILE_NAME)) {
print "The configuration file " . CONFIG_FILE_NAME . " does not exist\n";
exit(1);
}
$mailboxes = json_decode(file_get_contents(CONFIG_FILE_NAME), true);
// leitura das caixas de correio
foreach ($mailboxes as $name => $info) {
if (($info["enabled"] ?? true) === false) {
continue;
}
print "------------Reading the mailbox [$name]\n";
readmailbox($name, $info);
}
// fim
print "Done\n";
// --------------------------------------------------------------------------
function readmailbox(string $name, array $info): void
{
// um cliente IMAP ou POP3 conforme a configuração
$client = match ($info["protocol"]) {
"imap" => new ImapClient($info),
"pop3" => new Pop3Client($info),
};
try {
// conexão
$nbmsg = $client->connect();
print "Connection established with the server [$name].\n";
print "There are [$nbmsg] messages in the mailbox [$name]\n";
// mensagens não lidas
print "Retrieving the list of the unread messages of the mailbox [$name]\n";
$msgNumbers = $client->unread();
if (count($msgNumbers) === 0) {
print "There are no new messages in the mailbox [$name]\n";
}
// percorremos a lista das mensagens não lidas
foreach ($msgNumbers as $msgNumber) {
print "---message no. [$msgNumber]\n";
// recuperamos o texto completo da mensagem e o analisamos
getMailBody($client->message($msgNumber), "{$info["output-dir"]}/message-$msgNumber");
// se o protocolo for POP3, excluímos a mensagem após recuperá-la
if ($info["protocol"] === "pop3") {
$client->delete($msgNumber);
}
}
} catch (RuntimeException $ex) {
print "Error: " . $ex->getMessage() . "\n";
} finally {
try {
$client->close();
print "Connection closed successfully.\n";
} catch (RuntimeException $ex) {
print "Closing the connection failed: " . $ex->getMessage() . "\n";
}
}
}
// --------------------------------------------------------------------------
// análise do texto completo de uma mensagem
function getMailBody(string $text, string $outputDir): void
{
// a biblioteca analisa o texto da mensagem e o transforma em um objeto [IMessage]
// (false: o texto deixa de ser usado depois que o objeto é construído)
$message = Message::from($text, false);
// salvamos as diferentes partes da mensagem na pasta [$outputDir]
getParts($message, $outputDir);
}
// --------------------------------------------------------------------------
// salvamento das diferentes partes de uma mensagem
function getParts(IMessage $message, string $outputDir): void
{
// criamos, se necessário, a pasta onde a mensagem é salva
if (!is_dir($outputDir) && !mkdir($outputDir, recursive: true)) {
print "The folder [$outputDir] could not be created\n";
return;
}
// os cabeçalhos da mensagem (from, to, subject...), decodificados
$headers = [];
foreach ($message->getAllHeaders() as $header) {
$headers[] = "{$header->getName()}: {$header->getValue()}";
}
// salvamos as mensagens de texto
for ($i = 1; $i <= $message->getTextPartCount(); $i++) {
print "-- Saving a message of type [text/plain]\n";
saveMessage($message->getTextContent($i - 1), false, $headers, "$outputDir/message_$i.txt");
}
// salvamos as mensagens html
for ($i = 1; $i <= $message->getHtmlPartCount(); $i++) {
print "-- Saving a message of type [text/html]\n";
saveMessage($message->getHtmlContent($i - 1), true, $headers, "$outputDir/message_$i.html");
}
// percorremos a lista dos anexos
$iAttachment = 0;
foreach ($message->getAllAttachmentParts() as $attachment) {
// tipo e nome do anexo
$fileType = $attachment->getContentType();
$fileName = freeName($outputDir, $attachment->getFilename() ?? "attachment");
print "-- Saving an attachment of type [$fileType] in the file [$fileName]\n";
// salvamos o anexo, decodificado
$attachment->saveContent($fileName);
// caso especial do tipo message/rfc822
if ($fileType === "message/rfc822") {
// o anexo é, ele próprio, uma mensagem - nós a analisamos recursivamente
// em uma subpasta [rfc822-1], [rfc822-2]...
$iAttachment++;
$attachedMessage = Message::from($attachment->getBinaryContentStream()->getContents(), false);
getParts($attachedMessage, "$outputDir/rfc822-$iAttachment");
}
}
}
// --------------------------------------------------------------------------
// um nome de arquivo livre na pasta [$dir]: x.pdf, caso contrário x_1.pdf, x_2.pdf...
function freeName(string $dir, string $name): string
{
$info = pathinfo($name);
$extension = isset($info["extension"]) ? ".{$info["extension"]}" : "";
$candidate = "$dir/$name";
for ($i = 1; file_exists($candidate); $i++) {
$candidate = "$dir/{$info["filename"]}_$i$extension";
}
return $candidate;
}
// --------------------------------------------------------------------------
// salvamento de uma mensagem de texto precedida pelos cabeçalhos da mensagem
function saveMessage(string $text, bool $html, array $headers, string $filename): void
{
// em HTML, cada cabeçalho termina com <br/> para ficar sozinho em sua linha
$endOfLine = $html ? "<br/>\n" : "\n";
$contents = implode($endOfLine, $headers) . $endOfLine . $endOfLine . $text;
if (file_put_contents($filename, $contents) === false) {
print "The message could not be saved in the file [$filename]\n";
} else {
print "The message has been saved in the file [$filename]\n";
}
}
|
Comentários:
- linha 10: o carregador de classes do Composer para a biblioteca [zbateson/mail-mime-parser];
- Linhas 14–15: os dois tipos da biblioteca que utilizamos: a interface [IMessage] e a classe [Message] que a implementa;
- linha 21: verificamos se o arquivo de configuração existe;
- linha 39: a função [readmailbox] tem a mesma estrutura que em [imap-01.php]. O cliente IMAP ou POP3 agora é criado diretamente por uma expressão [match];
- linha 61: o texto completo da mensagem é solicitado à função [getMailBody];
- Linhas 81–87: o método estático [Message::from] analisa o texto da mensagem e devolve um objeto [IMessage]. A função [getParts] salva então suas diversas partes;
- linha 92: a função [getParts] recebe dois parâmetros:
- a mensagem [$message] a ser analisada;
- [$outputDir]: a pasta em que o texto e os anexos da mensagem devem ser salvos;
- linhas 101–102: os cabeçalhos da mensagem analisada (remetente, destinatário, assunto etc.) são obtidos. O método [getValue] devolve o valor decodificado de um cabeçalho;
- linhas 105–107: uma mensagem pode ter várias partes ([text/plain]). O método [getTextContent($i - 1)] devolve o texto da i-ésima parte (as partes são numeradas a partir de 0), decodificado e convertido para UTF-8. Salvamos todas, dando a cada uma um nome de arquivo diferente;
- linhas 110–112: mesmo procedimento para as partes [text/html];
- linha 116: percorre a lista de anexos da mensagem;
- linhas 118–119: o tipo do anexo (cabeçalho Content-Type) e seu nome, decodificado pela biblioteca independentemente de como esteja codificado. A função [freeName] devolve um nome de arquivo que ainda não existe na pasta;
- linha 122: o método [saveContent] salva em um arquivo o conteúdo decodificado do anexo;
- linhas 124–129: se o anexo for um e-mail, ele é por sua vez analisado por meio de uma chamada recursiva à função [getParts]. Seu conteúdo decodificado é obtido pelo método [getBinaryContentStream], que devolve um stream; todo o conteúdo desse stream é então lido com o método [getContents]. Se a mensagem analisada tiver dois e-mails anexados, o primeiro será salvo na pasta [$outputDir/rfc822-1] e o segundo na pasta [$outputDir/rfc822-2];
- Linha 136: se o arquivo [x.pdf] já existir, a função [freeName] tenta os nomes [x_1.pdf], [x_2.pdf]... até encontrar um nome de arquivo que não exista. A função [pathinfo] separa um nome de arquivo em nome e extensão;
- linha 149: a função [saveMessage] salva o texto da mensagem precedido pelos cabeçalhos da mensagem. No caso de um texto HTML, cada cabeçalho termina com a tag [<br/>].
Enviamos a mensagem com o comando [php smtp-02.php config-smtp-03.json]. [Mailpit] a armazena, e nós a colocamos também na caixa de correio INBOX do servidor IMAP. Em seguida, executamos o script [imap-03.php]. A saída no console é a seguinte:
| > php imap-03.php
------------Reading the mailbox [localhost:993]
Connection established with the server [localhost:993].
There are [4] messages in the mailbox [localhost:993]
Retrieving the list of the unread messages of the mailbox [localhost:993]
---message no. [4]
-- Saving a message of type [text/plain]
The message has been saved in the file [output/localhost-imap/message-4/message_1.txt]
-- Saving a message of type [text/html]
The message has been saved in the file [output/localhost-imap/message-4/message_1.html]
-- Saving an attachment of type [application/vnd.openxmlformats-officedocument.wordprocessingml.document] in the file [output/localhost-imap/message-4/Hello from Symfony Mailer.docx]
-- Saving an attachment of type [application/pdf] in the file [output/localhost-imap/message-4/Hello from Symfony Mailer.pdf]
-- Saving an attachment of type [application/vnd.oasis.opendocument.text] in the file [output/localhost-imap/message-4/Hello from Symfony Mailer.odt]
-- Saving an attachment of type [image/png] in the file [output/localhost-imap/message-4/Cours-Tutoriels-Serge-Tahé-1568x268.png]
-- Saving an attachment of type [message/rfc822] in the file [output/localhost-imap/message-4/test-localhost-2.eml]
-- Saving a message of type [text/plain]
The message has been saved in the file [output/localhost-imap/message-4/rfc822-1/message_1.txt]
-- Saving a message of type [text/html]
The message has been saved in the file [output/localhost-imap/message-4/rfc822-1/message_1.html]
-- Saving an attachment of type [application/vnd.openxmlformats-officedocument.wordprocessingml.document] in the file [output/localhost-imap/message-4/rfc822-1/Hello from Symfony Mailer.docx]
-- Saving an attachment of type [application/pdf] in the file [output/localhost-imap/message-4/rfc822-1/Hello from Symfony Mailer.pdf]
-- Saving an attachment of type [application/vnd.oasis.opendocument.text] in the file [output/localhost-imap/message-4/rfc822-1/Hello from Symfony Mailer.odt]
-- Saving an attachment of type [image/png] in the file [output/localhost-imap/message-4/rfc822-1/Cours-Tutoriels-Serge-Tahé-1568x268.png]
-- Saving an attachment of type [message/rfc822] in the file [output/localhost-imap/message-4/rfc822-1/test-localhost.eml]
-- Saving a message of type [text/plain]
The message has been saved in the file [output/localhost-imap/message-4/rfc822-1/rfc822-1/message_1.txt]
-- Saving a message of type [text/html]
The message has been saved in the file [output/localhost-imap/message-4/rfc822-1/rfc822-1/message_1.html]
-- Saving an attachment of type [application/vnd.openxmlformats-officedocument.wordprocessingml.document] in the file [output/localhost-imap/message-4/rfc822-1/rfc822-1/Hello from Symfony Mailer.docx]
-- Saving an attachment of type [application/pdf] in the file [output/localhost-imap/message-4/rfc822-1/rfc822-1/Hello from Symfony Mailer.pdf]
-- Saving an attachment of type [application/vnd.oasis.opendocument.text] in the file [output/localhost-imap/message-4/rfc822-1/rfc822-1/Hello from Symfony Mailer.odt]
-- Saving an attachment of type [image/png] in the file [output/localhost-imap/message-4/rfc822-1/rfc822-1/Cours-Tutoriels-Serge-Tahé-1568x268.png]
Connection closed successfully.
------------Reading the mailbox [localhost:1110]
Connection established with the server [localhost:1110].
There are [1] messages in the mailbox [localhost:1110]
Retrieving the list of the unread messages of the mailbox [localhost:1110]
---message no. [1]
-- Saving a message of type [text/plain]
The message has been saved in the file [output/localhost-pop3/message-1/message_1.txt]
-- Saving a message of type [text/html]
The message has been saved in the file [output/localhost-pop3/message-1/message_1.html]
-- Saving an attachment of type [application/vnd.openxmlformats-officedocument.wordprocessingml.document] in the file [output/localhost-pop3/message-1/Hello from Symfony Mailer.docx]
-- Saving an attachment of type [application/pdf] in the file [output/localhost-pop3/message-1/Hello from Symfony Mailer.pdf]
-- Saving an attachment of type [application/vnd.oasis.opendocument.text] in the file [output/localhost-pop3/message-1/Hello from Symfony Mailer.odt]
-- Saving an attachment of type [image/png] in the file [output/localhost-pop3/message-1/Cours-Tutoriels-Serge-Tahé-1568x268.png]
-- Saving an attachment of type [message/rfc822] in the file [output/localhost-pop3/message-1/test-localhost-2.eml]
-- Saving a message of type [text/plain]
The message has been saved in the file [output/localhost-pop3/message-1/rfc822-1/message_1.txt]
-- Saving a message of type [text/html]
The message has been saved in the file [output/localhost-pop3/message-1/rfc822-1/message_1.html]
-- Saving an attachment of type [application/vnd.openxmlformats-officedocument.wordprocessingml.document] in the file [output/localhost-pop3/message-1/rfc822-1/Hello from Symfony Mailer.docx]
-- Saving an attachment of type [application/pdf] in the file [output/localhost-pop3/message-1/rfc822-1/Hello from Symfony Mailer.pdf]
-- Saving an attachment of type [application/vnd.oasis.opendocument.text] in the file [output/localhost-pop3/message-1/rfc822-1/Hello from Symfony Mailer.odt]
-- Saving an attachment of type [image/png] in the file [output/localhost-pop3/message-1/rfc822-1/Cours-Tutoriels-Serge-Tahé-1568x268.png]
-- Saving an attachment of type [message/rfc822] in the file [output/localhost-pop3/message-1/rfc822-1/test-localhost.eml]
-- Saving a message of type [text/plain]
The message has been saved in the file [output/localhost-pop3/message-1/rfc822-1/rfc822-1/message_1.txt]
-- Saving a message of type [text/html]
The message has been saved in the file [output/localhost-pop3/message-1/rfc822-1/rfc822-1/message_1.html]
-- Saving an attachment of type [application/vnd.openxmlformats-officedocument.wordprocessingml.document] in the file [output/localhost-pop3/message-1/rfc822-1/rfc822-1/Hello from Symfony Mailer.docx]
-- Saving an attachment of type [application/pdf] in the file [output/localhost-pop3/message-1/rfc822-1/rfc822-1/Hello from Symfony Mailer.pdf]
-- Saving an attachment of type [application/vnd.oasis.opendocument.text] in the file [output/localhost-pop3/message-1/rfc822-1/rfc822-1/Hello from Symfony Mailer.odt]
-- Saving an attachment of type [image/png] in the file [output/localhost-pop3/message-1/rfc822-1/rfc822-1/Cours-Tutoriels-Serge-Tahé-1568x268.png]
Connection closed successfully.
Done
|
A mensagem foi lida duas vezes — primeiro por IMAP e depois por POP3 — e suas partes foram salvas a cada vez. Esta é a estrutura de diretórios da pasta [output/localhost-imap/message-4]:
| message-4
├── rfc822-1
│ ├── rfc822-1
│ │ ├── Cours-Tutoriels-Serge-Tahé-1568x268.png
│ │ ├── Hello from Symfony Mailer.docx
│ │ ├── Hello from Symfony Mailer.odt
│ │ ├── Hello from Symfony Mailer.pdf
│ │ ├── message_1.html
│ │ └── message_1.txt
│ ├── Cours-Tutoriels-Serge-Tahé-1568x268.png
│ ├── Hello from Symfony Mailer.docx
│ ├── Hello from Symfony Mailer.odt
│ ├── Hello from Symfony Mailer.pdf
│ ├── message_1.html
│ ├── message_1.txt
│ └── test-localhost.eml
├── Cours-Tutoriels-Serge-Tahé-1568x268.png
├── Hello from Symfony Mailer.docx
├── Hello from Symfony Mailer.odt
├── Hello from Symfony Mailer.pdf
├── message_1.html
├── message_1.txt
└── test-localhost-2.eml
|
- no nível superior, o texto e os 5 anexos do e-mail recebido por [guest@localhost];
- na pasta [rfc822-1], o texto do corpo e os 5 anexos do e-mail [test-localhost-2.eml];
- na pasta [rfc822-1/rfc822-1], o texto e os 4 anexos do e-mail [test-localhost.eml].
Se você abrir o arquivo [rfc822-1/rfc822-1/message_1.html] em um navegador, verá o seguinte:

Ele contém os cabeçalhos do e-mail [test-localhost.eml], seguidos do texto de seu corpo, com os caracteres acentuados corretamente decodificados.
O uso da biblioteca [zbateson/mail-mime-parser] torna muito mais fácil escrever o script de leitura de e-mails.