Skip to content

16. Funciones de red

Veremos ahora las funciones de red de PHP, que permiten programar con TCP / IP (Transmission Control Protocol / Internet Protocol). Los scripts de este capítulo se encuentran en la carpeta [scripts-console/inet] del código del curso:

1
2
3
4
5
6
7
8
9
php8-oct-2026
└── scripts-console
    └── inet
        ├── http
        ├── imap
        ├── ip
        ├── mailpit
        ├── smtp
        └── utilities

16.1. Fundamentos de la programación web

16.1.1. Generalidades

Consideremos la comunicación entre dos máquinas remotas, A y B:

Image

Cuando una aplicación AppA de la máquina A quiere comunicarse con una aplicación AppB de la máquina B en Internet, debe conocer varias cosas:

  • la dirección IP (Internet Protocol) o el nombre de la máquina B;
  • el número de puerto utilizado por la aplicación AppB. Esto se debe a que la máquina B puede alojar muchas aplicaciones que funcionan en Internet. Cuando recibe información de la red, debe saber a qué aplicación está destinada. Las aplicaciones de la máquina B acceden a la red a través de interfaces también llamadas puertos de comunicación. Esta información está contenida en el paquete que recibe la máquina B, de modo que pueda entregarse a la aplicación correcta;
  • los protocolos de comunicación que entiende la máquina B. En nuestro estudio, solo utilizaremos los protocolos TCP / IP;
  • el protocolo de comunicación que admite la aplicación AppB. En efecto, las máquinas A y B “conversarán” entre sí. Lo que se digan estará encapsulado en los protocolos TCP e IP. Sin embargo, cuando, en el otro extremo de la cadena, la aplicación AppB recibe la información enviada por la aplicación AppA, debe poder interpretarla. Es análogo a una situación en la que dos personas, A y B, se comunican por teléfono: su conversación es transportada por el teléfono. El habla es codificada en señales por el teléfono A, transmitida por las líneas telefónicas y llega al teléfono B para ser decodificada. La persona B escucha entonces el habla. Aquí es donde interviene el concepto de protocolo de comunicación: si A habla francés y B no entiende ese idioma, A y B no podrán comunicarse eficazmente.

Por lo tanto, las dos aplicaciones que se comunican deben ponerse de acuerdo sobre el tipo de diálogo que usarán. Por ejemplo, el diálogo con un servicio llamado FTP no es el mismo que con un servicio llamado POP: estos dos servicios no aceptan los mismos comandos. Tienen protocolos de diálogo diferentes.

16.1.2. Características del protocolo TCP

Aquí nos centraremos únicamente en las comunicaciones de red que utilizan el protocolo de transporte TCP, cuyas características principales son las siguientes:

  • El proceso que desea transmitir datos establece primero una conexión con el proceso que recibirá la información que está por transmitir. Esta conexión se establece entre un puerto de la máquina emisora y un puerto de la máquina receptora. Así se crea una ruta virtual entre los dos puertos, que quedará reservada exclusivamente para los dos procesos que establecieron la conexión;
  • Todos los paquetes enviados por el proceso de origen siguen esta ruta virtual y llegan en el orden en que fueron enviados;
  • Los datos transmitidos parecen continuos. El proceso emisor envía los datos a su propio ritmo. Estos datos no se envían necesariamente de inmediato: el protocolo TCP espera hasta tener suficientes datos para enviar. Se almacenan en una estructura llamada segmento TCP. Una vez lleno este segmento, se transmitirá a la capa IP, donde se encapsulará en un paquete IP;
  • Cada segmento enviado por el protocolo TCP está numerado. El protocolo TCP receptor verifica que recibe los segmentos en secuencia. Por cada segmento recibido correctamente, envía un acuse de recibo al emisor;
  • cuando el emisor recibe este acuse de recibo, se lo notifica al proceso emisor. Por lo tanto, el proceso emisor puede confirmar que un segmento se entregó correctamente;
  • si, transcurrido cierto tiempo, el protocolo TCP que envió un segmento no recibe un acuse de recibo, retransmite el segmento en cuestión, garantizando así la calidad del servicio de entrega de la información;
  • El circuito virtual establecido entre los dos procesos que se comunican es full-duplex: esto significa que la información puede circular en ambos sentidos. Así, el proceso de destino puede enviar acuses de recibo incluso mientras el proceso de origen sigue enviando información. Esto permite, por ejemplo, que el protocolo TCP de origen envíe varios segmentos sin esperar un acuse de recibo. Si, transcurrido cierto tiempo, se da cuenta de que no ha recibido el acuse de recibo de un segmento específico n.º n, reanudará el envío de segmentos a partir de ese punto.

16.1.3. La relación cliente-servidor

La comunicación por Internet suele ser asimétrica: la máquina A inicia una conexión para solicitar un servicio a la máquina B. Especifica que desea establecer una conexión con el servicio SB1 de la máquina B. La máquina B acepta o rechaza la solicitud. Si la acepta, la máquina A puede enviar sus solicitudes al servicio SB1. Estas solicitudes deben cumplir con el protocolo de comunicación que entiende el servicio SB1. Se establece así un diálogo de solicitud-respuesta entre la máquina A, llamada máquina cliente, y la máquina B, llamada máquina servidor. Uno de los dos interlocutores cerrará la conexión.

16.1.4. Arquitectura del cliente

La arquitectura de un programa de red que solicita servicios a una aplicación servidor será la siguiente:

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. Arquitectura del servidor

La arquitectura de un programa que ofrece servicios será la siguiente:

1
2
3
4
5
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

El programa servidor trata de manera distinta la solicitud inicial de conexión de un cliente y sus solicitudes posteriores de servicio. El programa no presta el servicio por sí mismo. Si lo hiciera, dejaría de escuchar las solicitudes de conexión mientras el servicio está en curso, y los clientes no serían atendidos. Por lo tanto, procede de otra manera: en cuanto se recibe una solicitud de conexión en el puerto de escucha y se acepta, el servidor crea una tarea encargada de prestar el servicio solicitado por el cliente. Este servicio se presta en otro puerto de la máquina servidor, llamado puerto de servicio. Esto permite atender varios clientes al mismo tiempo.

Una tarea de servicio tendrá la siguiente estructura:

1
2
3
4
5
6
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

Otra forma de atender a varios clientes a la vez, sin crear tareas, consiste en vigilar simultáneamente el puerto de escucha y los puertos de servicio mediante una función que espera a que alguno de ellos tenga algo que comunicar. Esto es lo que hará el servidor TCP que vamos a escribir, usando la función [stream_select] de PHP.

16.2. Exploración de los protocolos de comunicación de Internet

16.2.1. Introducción

Cuando un cliente se conecta a un servidor, se establece un diálogo entre ellos. La naturaleza de este diálogo constituye lo que se conoce como el protocolo de comunicación del servidor. Entre los protocolos de Internet más comunes se encuentran los siguientes:

  • HTTP: HyperText Transfer Protocol, el protocolo para comunicarse con un servidor web (servidor HTTP);
  • SMTP: Simple Mail Transfer Protocol, el protocolo para comunicarse con un servidor de envío de correo electrónico (servidor SMTP);
  • POP: Post Office Protocol, el protocolo para comunicarse con un servidor de almacenamiento de correo electrónico (servidor POP). Se utiliza para recuperar los mensajes recibidos, no para enviarlos;
  • IMAP: Internet Message Access Protocol, el protocolo para comunicarse con un servidor de almacenamiento de correo electrónico (servidor IMAP). Este protocolo ha ido reemplazando gradualmente al antiguo protocolo POP;
  • FTP: File Transfer Protocol, el protocolo para comunicarse con un servidor de almacenamiento de archivos (servidor FTP).

Todos estos protocolos están basados en texto: el cliente y el servidor intercambian líneas de texto. Si se dispone de un cliente capaz de:

  • establecer una conexión con un servidor TCP;
  • mostrar en la consola las líneas de texto enviadas por el servidor;
  • enviar al servidor las líneas de texto que un usuario escribiría con el teclado;

entonces podemos comunicarnos con un servidor TCP que utilice un protocolo basado en texto, siempre que conozcamos las reglas de ese protocolo.

16.2.2. Utilidades TCP

El curso de PHP 7 proporcionaba dos utilidades para Windows, [RawTcpClient] y [RawTcpServer], escritas en C#. Aquí las reemplazamos por dos scripts PHP, que examinaremos a continuación: es una oportunidad para explorar las funciones de red de PHP. Se encuentran en la carpeta [inet/utilities]:

1
2
3
4
utilities
├── keyboard.php
├── tcp-client.php
└── tcp-server.php
  • [tcp-client.php] permite conectarse al puerto P del servidor S;
  • [tcp-server.php] crea un servidor que escucha clientes en el puerto P;
  • [keyboard.php] contiene dos funciones utilizadas por los dos scripts anteriores.

Observe que también existen herramientas ya hechas para este tipo de pruebas. En Windows, el comando de PowerShell [Test-NetConnection localhost -Port 80] simplemente verifica si un servicio responde en un puerto. La herramienta [curl], que encontraremos con el protocolo HTTP, puede comunicarse con muchos servidores, y su opción [-v] (verbose) muestra los intercambios entre cliente y servidor. En cambio, nuestros dos scripts nos permiten escribir nosotros mismos los comandos del protocolo.

16.2.2.1. El servidor [tcp-server.php]

El servidor TCP [tcp-server.php] se invoca con la sintaxis [php tcp-server.php port] para crear un servicio TCP en el puerto [port] de la máquina local (la computadora en la que está trabajando):

  • El servidor puede atender a varios clientes simultáneamente;
  • el servidor ejecuta los comandos que el usuario escribe con el teclado. Estos comandos son los siguientes:
    • list: enumera los clientes conectados actualmente al servidor. Se muestran con el formato [id=x - name=y]. El campo [id] sirve para identificar a los clientes;
    • send x [text]: envía text al cliente n.º x (id=x). Los corchetes [] no se envían. Son obligatorios en el comando. Sirven para delimitar visualmente el texto enviado al cliente;
    • close x: cierra la conexión con el cliente n.º x;
    • quit: cierra todas las conexiones y detiene el servicio;
  • Las líneas enviadas por un cliente al servidor se muestran en la consola;
  • Toda la comunicación con un cliente se registra en un archivo de texto llamado [logs/machine-port.txt], donde [machine-port] identifica al cliente (su dirección IP y el puerto que utiliza).

El código del servidor es el siguiente:

<?php

declare(strict_types=1);

// servidor TCP genérico
// sintaxis: php tcp-server.php port
// - espera clientes en el puerto [port] de la máquina local y puede atender a varios a la vez;
// - muestra las líneas de texto enviadas por los clientes;
// - ejecuta los comandos escritos en el teclado:
//   list: lista los clientes conectados;
//   send id [text]: envía [text] (sin los corchetes) al cliente n.º id;
//   close id: cierra la conexión con el cliente n.º id;
//   quit: cierra todas las conexiones y detiene el servidor;
// - registra los intercambios con cada cliente en el archivo [logs/machine-port.txt]
//   donde [machine-port] identifica al cliente

require_once __DIR__ . "/keyboard.php";

// análisis de los argumentos de la línea de comandos
if (count($argv) !== 2 || !ctype_digit($argv[1])) {
    print "Syntax: php tcp-server.php port\n";
    exit(1);
}
$port = $argv[1];

// apertura del servicio en todas las interfaces de red de la 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");
}

// los clientes conectados: id => [socket, name, log file, buffer]
$clients = [];
$nextId = 1;
// el teclado lo lee un proceso hijo
[$reader, $keyboard] = startKeyboardReader();
$echo = !stream_isatty(STDIN);
$keyboardBuffer = "";

// bucle de servicio
$done = false;
while (!$done) {
    // vigilamos: el puerto de escucha, los clientes y el teclado
    $reads = [$server, $keyboard, ...array_column($clients, "socket")];
    $writes = $exceptions = null;
    stream_select($reads, $writes, $exceptions, null);
    foreach ($reads as $stream) {
        if ($stream === $server) {
            // un nuevo 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) {
            // se ha escrito un comando en el teclado
            $data = fread($keyboard, 8192);
            if ($data === false || $data === "") {
                // fin de la entrada estándar: detenemos el servidor
                $done = true;
                break;
            }
            foreach (extractLines($keyboardBuffer, $data) as $command) {
                if ($echo) {
                    print "$command\n";
                }
                if (execute($command, $clients)) {
                    $done = true;
                    break;
                }
            }
        } else {
            // un cliente ha hablado
            $id = array_find_key($clients, fn(array $client): bool => $client["socket"] === $stream);
            if ($id === null) {
                // cliente cerrado entretanto por el 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");
            }
        }
    }
}
// detención del servicio
foreach (array_keys($clients) as $id) {
    close($clients, $id);
}
fclose($server);
proc_terminate($reader);
print "Server stopped\n";

// --------------------------------------------------------------------------
// ejecuta un comando escrito en el teclado - devuelve true si es el 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;
    }
    // los demás 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;
    }
}

// --------------------------------------------------------------------------
// cierra la conexión con el cliente n.º [$id]
function close(array &$clients, int $id): void
{
    fclose($clients[$id]["socket"]);
    fclose($clients[$id]["log"]);
    unset($clients[$id]);
}

Comentarios:

  • línea 17: se carga el archivo [keyboard.php]; hablaremos de él más adelante;
  • línea 20: el arreglo [$argv] contiene los argumentos de la línea de comandos. [$argv[0]] es el nombre del script, [$argv[1]] es el primer argumento, en este caso el número de puerto. La función [ctype_digit] verifica que el número de puerto esté formado solo por dígitos;
  • Línea 27: la función [stream_socket_server] inicia un servicio TCP. Su primer parámetro es una dirección con el formato [tcp://interface:port]. La interfaz [0.0.0.0] hace referencia a todas las interfaces de red de la máquina: se puede acceder al servidor tanto mediante [localhost] como mediante la dirección IP de la máquina en la red local. En caso de fallo (por ejemplo, si el puerto ya está en uso), la función devuelve [false] y almacena un número de error y un mensaje de error en las dos variables pasadas como segundo y tercer parámetro. El operador [@] evita que PHP muestre su propia advertencia: mostramos nuestro mensaje;
  • línea 39: el diccionario de clientes conectados. Cada cliente se describe mediante su socket (la conexión que lo vincula con el servidor), su nombre [address:port], su archivo de registro y un búfer cuyo propósito explicaremos más adelante;
  • línea 42: el teclado lo lee un proceso hijo. Veremos por qué al estudiar el archivo [keyboard.php]. [$keyboard] es un flujo en el que se introducen las líneas escritas con el teclado;
  • Línea 43: la función [stream_isatty] determina si la entrada estándar es el teclado (una terminal) o no. Si la entrada estándar se redirigió a un archivo ([php tcp-server.php 100 < commands.txt]), los comandos leídos no se muestran en la pantalla. Entonces el servidor los mostrará él mismo;
  • líneas 48–52: el bucle de servicio. En cada iteración, el servidor espera a que alguno de los flujos que vigila tenga algo que comunicarle: el puerto de escucha (se conecta un nuevo cliente), el teclado (se escribió un comando) o uno de los clientes (envió texto). El operador [...] descompone el arreglo de sockets de los clientes (obtenido con [array_column]) en el arreglo [$reads];
  • Línea 52: la función [stream_select] espera a que alguno de los flujos del arreglo [$reads] esté listo para leerse. El último parámetro, [null], significa: esperar indefinidamente. Al regresar, la función ha eliminado del arreglo [$reads] los flujos que no tienen nada que leer. El segundo y el tercer parámetro se refieren a los flujos en los que queremos escribir y a los eventos excepcionales: no nos interesan. Como se pasan por referencia, debemos pasarles variables, en este caso [$writes] y [$exceptions], que son iguales a [null];
  • Líneas 54–60: se conecta un nuevo cliente. La función [stream_socket_accept] acepta la conexión. Devuelve el socket de servicio que conecta al servidor con este cliente y almacena la identidad del cliente en [$name] con el formato [address:port]. Un tiempo de espera de 0 significa que no hay espera: [stream_select] nos informó de que había un cliente esperando;
  • líneas 63–75: se escribió un comando con el teclado. La función [fread] lee todo lo que esté disponible (hasta 8192 bytes). Una cadena vacía significa que el flujo se cerró. La función [extractLines] divide lo leído en líneas completas;
  • líneas 81–95: un cliente envió texto. La función [array_find_key] (PHP 8.4) devuelve la clave del primer elemento del arreglo que cumple la condición expresada por la función flecha [fn] pasada como segundo parámetro: así se obtiene el id del cliente a partir de su socket. Si [fread] devuelve una cadena vacía, el cliente cerró la conexión. En caso contrario, cada línea recibida se muestra y se registra en el archivo de registro del cliente;
  • Líneas 110–141: la función [execute] ejecuta un comando introducido con el teclado. El comando [send id [text]] se reconoce mediante una expresión regular. El texto se envía al cliente seguido de la secuencia \r\n: los protocolos de Internet terminan las líneas de texto con los dos caracteres CR (\r) y LF (\n);
  • línea 150: la función [close] cierra la conexión con un cliente y lo elimina del diccionario [$clients], pasado por referencia ([&]).

16.2.2.2. El archivo [keyboard.php]

El archivo [keyboard.php] es el siguiente:

<?php

declare(strict_types=1);

// herramientas compartidas por [tcp-client.php] y [tcp-server.php]

// --------------------------------------------------------------------------
// inicia un proceso hijo que lee el teclado y nos devuelve cada línea escrita
// a través de un socket. ¿Por qué? Nuestros programas deben vigilar a la vez la red y el
// teclado con la función [stream_select]. Pero en Windows, [stream_select]
// solo puede vigilar sockets, no el teclado (STDIN).
// El descriptor ['socket'] de [proc_open] (PHP 8.0) conecta el proceso hijo con el
// proceso padre a través de un socket, que [stream_select] puede vigilar en cualquier sistema operativo.
// devuelve el proceso hijo y el socket que entrega las líneas escritas en el teclado
function startKeyboardReader(): array
{
    $process = proc_open(
        // el proceso hijo: un script PHP de una línea que copia su entrada a su salida
        [PHP_BINARY, "-r", 'while (($line = fgets(STDIN)) !== false) { echo $line; }'],
        // su entrada es nuestro teclado, su salida es un socket
        [0 => STDIN, 1 => ["socket"], 2 => STDERR],
        $pipes
    );
    if ($process === false) {
        throw new RuntimeException("Unable to start the keyboard reader");
    }
    return [$process, $pipes[1]];
}

// --------------------------------------------------------------------------
// agrega los bytes [$data] al búfer [$buffer] y extrae de él las líneas completas,
// devueltas sin su marca de fin de línea (\n o \r\n);
// el final del búfer (una línea incompleta) permanece en el búfer
function extractLines(string &$buffer, string $data): array
{
    $buffer .= $data;
    $lines = explode("\n", $buffer);
    // el último elemento es la línea actual, aún no terminada
    $buffer = array_pop($lines);
    return array_map(fn(string $line): string => rtrim($line, "\r"), $lines);
}

Comentarios:

  • Línea 15: nuestros dos scripts deben vigilar al mismo tiempo la red y el teclado. En Linux o macOS, podríamos pasar el flujo [STDIN] (el teclado) a [stream_select]. En Windows, esto no es posible: [stream_select] solo puede vigilar sockets allí. La solución alternativa consiste en hacer que un segundo proceso lea el teclado y nos envíe las líneas escritas a través de un socket;
  • Líneas 17–22: la función [proc_open] lanza un proceso hijo. Su primer parámetro es el comando que se va a ejecutar, en forma de arreglo: el intérprete de PHP que se está ejecutando ([PHP_BINARY]) con la opción [-r], que ejecuta el código PHP pasado como argumento. Este código copia cada línea leída de su entrada en su salida. El segundo parámetro describe los flujos del proceso hijo: su entrada (0) es nuestra entrada estándar (el teclado), su salida (1) es un socket creado por PHP (descriptor [['socket']], disponible desde PHP 8.0) y sus errores (2) se envían a nuestra salida de errores. El tercer parámetro recibe los flujos creados: [$pipes[1]] es nuestro extremo del socket;
  • línea 34: cuando [stream_select] indica que un flujo está listo para leerse, [fread] devuelve lo recibido: puede ser una línea, varias líneas o parte de una línea. La función [extractLines] agrega estos bytes al búfer [$buffer] (pasado por referencia), extrae de él las líneas completas y conserva en el búfer la línea inconclusa. Observe la función flecha [fn(string $line): string => rtrim($line, "\r")], que elimina el \r final de las líneas que terminan en \r\n.

Podríamos haber leído las líneas con la función [fgets]. Sin embargo, [fgets] lee los datos por bloques y guarda las líneas que aún no ha entregado en un búfer interno de PHP. [stream_select], que solo vigila la red, no las vería. Leer con [fread] y dividir nosotros mismos las líneas evita este escollo.

16.2.2.3. El cliente [tcp-client.php]

El cliente TCP [tcp-client.php] se invoca con la sintaxis [php tcp-client.php [--quit command] [--tls] server port] para conectarse al puerto [port] del servidor [server]:

  • Las líneas que el usuario escribe con el teclado se envían al servidor;
  • las líneas enviadas por el servidor se muestran en la consola apenas llegan;
  • toda la comunicación se registra en un archivo de texto llamado [logs/server-port.txt];
  • el comando [quit] detiene el cliente. La opción [--quit] permite elegir otro comando;
  • La opción [--tls] cifra la conexión. La necesitaremos para comunicarnos con servidores seguros.

Su código es el siguiente:

<?php

declare(strict_types=1);

// cliente TCP genérico
// sintaxis: php tcp-client.php [--quit command] [--tls] server port
// - se conecta al puerto [port] de la máquina [server];
// - muestra las líneas de texto enviadas por el servidor en cuanto llegan;
// - envía al servidor las líneas de texto escritas en el teclado;
// - registra todos los intercambios en el archivo [logs/server-port.txt]
// opciones:
// --quit command: el comando que detiene el cliente ([quit] por defecto)
// --tls: la conexión se cifra (TLS) en cuanto se abre

require_once __DIR__ . "/keyboard.php";

// análisis de los argumentos de la línea de comandos
$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;

// apertura de la conexión con el servidor
// con --tls, no se verifica el certificado del servidor: es una herramienta de descubrimiento
$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";

// archivo de registro
if (!is_dir(__DIR__ . "/logs")) {
    mkdir(__DIR__ . "/logs");
}
$log = fopen(__DIR__ . "/logs/$server-$port.txt", "w");

// el teclado lo lee un proceso hijo
[$reader, $keyboard] = startKeyboardReader();
// si la entrada estándar es un archivo (php tcp-client.php ... < commands.txt),
// los comandos leídos no se muestran en pantalla: los mostraremos nosotros mismos
$echo = !stream_isatty(STDIN);
// búferes de las líneas incompletas recibidas del servidor y del teclado
$serverBuffer = "";
$keyboardBuffer = "";

// bucle de diálogo con el servidor
$done = false;
while (!$done) {
    // esperamos hasta que el servidor o el teclado tenga algo que decirnos
    $reads = $keyboard !== null ? [$connection, $keyboard] : [$connection];
    $writes = $exceptions = null;
    // sin teclado (fin de la entrada estándar), no esperamos al servidor más de 2 segundos
    if (stream_select($reads, $writes, $exceptions, $keyboard !== null ? null : 2) === 0) {
        break;
    }
    // ¿ha hablado el servidor?
    if (in_array($connection, $reads, true)) {
        $data = fread($connection, 8192);
        if ($data === false || $data === "") {
            // el servidor ha cerrado la conexión
            if ($serverBuffer !== "") {
                display("<-- [$serverBuffer]", $log);
            }
            print "Connection with the server lost...\n";
            break;
        }
        foreach (extractLines($serverBuffer, $data) as $line) {
            display("<-- [$line]", $log);
        }
    }
    // ¿se ha escrito una línea en el teclado?
    if ($keyboard !== null && in_array($keyboard, $reads, true)) {
        $data = fread($keyboard, 8192);
        if ($data === false || $data === "") {
            // fin de la entrada estándar
            $keyboard = null;
            continue;
        }
        foreach (extractLines($keyboardBuffer, $data) as $command) {
            if ($echo) {
                print "$command\n";
            }
            // ¿fin del cliente?
            if ($command === $quit) {
                $done = true;
                break;
            }
            // enviamos el comando al servidor: los protocolos de internet
            // terminan las líneas con la secuencia \r\n
            fwrite($connection, "$command\r\n");
            fwrite($log, "--> [$command]\n");
        }
    }
}
// cierre de la conexión, del archivo de registro y del lector de teclado
fclose($connection);
fclose($log);
proc_terminate($reader);
print "End of the client\n";

// --------------------------------------------------------------------------
// muestra una línea recibida y la registra en el archivo de registro
function display(string $line, $log): void
{
    print "$line\n";
    fwrite($log, "$line\n");
}

Comentarios:

  • Líneas 21–26: análisis de los argumentos. La expresión [match] (PHP 8.0) compara su argumento con los valores de sus ramas mediante el operador [===] y evalúa la rama correspondiente. Aquí, cada rama es una asignación. [$argv[++$i] ?? $quit] devuelve el argumento que sigue a [--quit] si existe, y [$quit] en caso contrario;
  • línea 32: desempaquetado de arreglos: [$server] recibe [$arguments[0]], y [$port] recibe [$arguments[1]];
  • Líneas 36–39: la función [stream_socket_client] establece una conexión con el servicio [tcp://server:port]. Con la opción [--tls], la dirección pasa a ser [tls://server:port]: PHP cifra entonces la conexión mediante el protocolo TLS (Transport Layer Security). El contexto creado por [stream_context_create] especifica aquí que no se debe verificar el certificado del servidor: para una herramienta de exploración, esto evita problemas con servidores de prueba que tienen certificados autofirmados. El cuarto parámetro es el tiempo máximo (en segundos) permitido para establecer la conexión;
  • línea 44: la función [stream_socket_get_name] devuelve, según se indique si la conexión es local (false) o remota (true), la dirección con el formato [address:port];
  • Líneas 65–70: el bucle de diálogo. Tiene la misma estructura que el del servidor: [stream_select] espera a que el servidor o el teclado envíen algo. Cuando la entrada estándar se termina (como en el caso de una entrada redirigida a un archivo), el cliente sigue mostrando lo que envía el servidor, pero no lo espera más de 2 segundos;
  • líneas 73–85: las líneas enviadas por el servidor se muestran entre corchetes y se escriben en el archivo de registro. Si el servidor cierra la conexión, el bucle se detiene;
  • líneas 88–108: cada línea escrita con el teclado se envía al servidor, seguida de la secuencia \r\n, excepto el comando de detención del cliente;
  • línea 115: por último, se termina el proceso hijo que lee el teclado.

16.2.2.4. Un ejemplo

Veamos un ejemplo. Abra dos terminales (en VS Code, el botón [+] de la vista [Terminal] abre una nueva) y vaya a la carpeta [inet/utilities] en cada una de ellas. En la primera terminal, inicie el servidor en el puerto 100. En la segunda, inicie el cliente e indíquele que se conecte al puerto 100 de la máquina local [localhost], y luego escriba una línea de texto. Vuelva al servidor, responda al cliente n.º 1, solicite la lista de clientes, cierre la conexión con el cliente n.º 1 y detenga el servidor.

Esto es lo que muestra el servidor (los comandos escritos con el teclado son las líneas [send 1 ...], [list], [close 1], y [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]: se detectó un cliente. El servidor le asignó el número 1. El cliente utiliza el puerto 47966 de la máquina con la dirección IP 127.0.0.1. Esta dirección pertenece a [localhost], la máquina local;
  • [<-- client no. 1 [hello from client]]: la línea recibida del cliente se muestra entre corchetes;
  • [send 1 [hello from server]]: la respuesta enviada al cliente n.º 1. Solo se envía el texto que está dentro de los corchetes, no los corchetes;
  • [list]: la lista de clientes y su respuesta;
  • [close 1] seguido de [quit]: se cierra la conexión con el cliente n.º 1 y luego se apaga el servidor.

Y esto es lo que muestra el cliente:

1
2
3
4
5
6
7
> 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]: la línea escrita con el teclado;
  • [<-- [hello from server]]: la respuesta recibida del servidor. El texto recibido es el que está entre corchetes;
  • [Connection with the server lost...]: el cliente detectó que el servidor cerró la conexión.

Se crearon dos archivos de registro en la carpeta [utilities/logs], uno por el servidor y otro por el cliente. El archivo del servidor lleva el nombre del cliente, [127.0.0.1-47966.txt]:

<-- [hello from client]
--> [hello from server]

El archivo del cliente lleva el nombre del servidor, [localhost-100.txt]:

--> [hello from client]
<-- [hello from server]

16.3. Obtención del nombre o de la dirección IP de una máquina en Internet

Las computadoras en Internet se identifican por una dirección (IP, IPv4 o IPv6) y, la mayoría de las veces, por un nombre. Sin embargo, en última instancia solo se utiliza la dirección. Por lo tanto, a veces es necesario conocer la dirección IP de una máquina identificada por su nombre. Esta es la función del servicio DNS (Domain Name System).

El script [inet/ip/ip-01.php] es el siguiente:

<?php

declare(strict_types=1);

// direcciones IP y nombres de máquinas de internet

// las máquinas cuya dirección IP y nombre queremos
const HOSTS = ["istia.univ-angers.fr", "www.univ-angers.fr", "www.ibm.com", "www.php.net", "yahoo.com", "localhost", "xx"];

// agregamos la máquina local, cuyo nombre lo da [gethostname]
foreach ([...HOSTS, gethostname()] as $host) {
    getIPandName($host);
}
// fin
print "Done\n";

// --------------------------------------------------------------------------
function getIPandName(string $machineName): void
{
    // $machineName: nombre de la máquina cuya dirección IP queremos
    print "---------------\n";
    // machineName → dirección IP
    $ip = gethostbyname($machineName);
    if ($ip === $machineName) {
        print "Error, machine [$machineName] not found\n";
        return;
    }
    print "ip[$machineName]=$ip\n";
    // todas las direcciones IPv4 de la máquina
    $ips = gethostbynamel($machineName);
    if ($ips !== false && count($ips) > 1) {
        print "all the IPv4 addresses of [$machineName]: " . implode(", ", $ips) . "\n";
    }
    // dirección 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";
    }
}

Comentarios:

  • línea 8: la lista de máquinas de las que queremos obtener el nombre y la dirección IP;
  • línea 11: el nombre de la máquina local, devuelto por la función [gethostname], se agrega a esta lista. El operador [...] copia los elementos del arreglo [HOSTS] en el nuevo arreglo;
  • línea 18: las funciones de red de PHP se utilizan en la función [getIPandName];
  • Línea 23: la función [gethostbyname($machineName)] devuelve la dirección IPv4 "ip3.ip2.ip1.ip0" de la máquina llamada $machineName. Si la máquina $machineName no existe, la función devuelve $machineName como resultado;
  • línea 30: una máquina puede tener varias direcciones, por ejemplo IPv4. La función [gethostbynamel] las devuelve todas en un arreglo (o [false] si la operación falla);
  • línea 35: la función [gethostbyaddr($ip)] obtiene el nombre de la máquina que tiene la dirección $ip. Si la dirección $ip no tiene nombre, la función devuelve $ip como resultado, y [false] si la dirección tiene un formato incorrecto.

Las funciones [gethostbyname] y [gethostbynamel] solo reconocen direcciones con formato IPv4. Para obtener las direcciones IPv6 de una máquina, se usaría la función [dns_get_record] con el 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
  • Las máquinas [istia.univ-angers.fr] y [www.univ-angers.fr] tienen la misma dirección IP. El nombre obtenido a partir de la dirección IP, conocido como nombre canónico, es otro nombre más;
  • el nombre [www.ibm.com] está asociado a un servidor perteneciente a Akamai, una empresa que aloja sitios web de numerosas compañías;
  • La máquina [yahoo.com] tiene seis direcciones IPv4: las solicitudes se distribuyen entre varios servidores;
  • [localhost] tiene la dirección 127.0.0.1, conocida como dirección de bucle invertido (loopback): siempre hace referencia a la máquina local;
  • La máquina [xx] no existe;
  • la última máquina es la máquina local, llamada aquí [vm]. Los resultados dependen de la configuración de la máquina: en una computadora con Windows, obtendrá el nombre de su computadora y, según la configuración, su dirección en la red local (192.168.x.y, por ejemplo).

Los resultados obtenidos para las máquinas de Internet cambian con el tiempo: es probable que no obtenga los mismos resultados.

16.4. El protocolo HTTP (HyperText Transfer Protocol)

16.4.1. Ejemplo 1

Image

Cuando un navegador muestra una URL, actúa como cliente de un servidor web, es decir, de un servidor HTTP. El navegador toma la iniciativa y comienza enviando una serie de comandos al servidor. Para este primer ejemplo:

  • el servidor será la utilidad [tcp-server.php];
  • el cliente será un navegador web.

Primero iniciamos el servidor en el puerto 100 y luego, desde un navegador, solicitamos la URL [http://localhost:100], es decir, le indicamos que el servidor HTTP al que consultamos se ejecuta en el puerto 100 de la máquina local. El navegador espera la respuesta. Volvamos a la ventana del servidor. Allí vemos las líneas enviadas por el navegador. Luego escribimos una respuesta en formato HTTP, línea por línea, cerramos la conexión y detenemos el 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]: el navegador que se conectó;
  • seguido de las líneas de texto que envió:
    • [GET / HTTP/1.1]: esta línea tiene el formato [GET URL HTTP/1.1]. Solicita la URL / e indica al servidor que utilice el protocolo HTTP 1.1;
    • [Host: localhost:100]: esta línea tiene el formato [Host: server:port]. Las mayúsculas y minúsculas del encabezado [Host] no importan. Observe que el cliente consulta un servidor local que opera en el puerto 100;
    • el encabezado [Connection] especifica el modo de conexión deseado: [keep-alive] indica que la conexión debe mantenerse después de la respuesta, para posibles solicitudes posteriores;
    • el encabezado [User-Agent] proporciona la identidad del cliente. En este caso, se trata de un navegador Chromium. Los encabezados [sec-ch-ua...] y [Sec-Fetch...] son propios de los navegadores recientes. Los valores exactos dependen del navegador y del sistema operativo utilizados;
    • el encabezado [Accept] especifica los tipos de documento que acepta el cliente;
    • el encabezado [Accept-Language] especifica el idioma preferido para los documentos solicitados si están disponibles en varios idiomas;
    • el encabezado [Accept-Encoding] indica que el cliente acepta documentos comprimidos;
    • el cliente termina sus comandos con una línea en blanco;
  • Los comandos [send 1 [...]] envían la respuesta al navegador: una primera línea, [HTTP/1.1 200 OK], que indica que se encontró el documento solicitado; encabezados; una línea en blanco; y luego el documento. El encabezado [Content-Type] especifica el tipo de documento (en este caso, HTML codificado en UTF-8) y el encabezado [Connection: close] indica que el servidor cerrará la conexión al final del documento;
  • [close 1]: el cierre de la conexión le indica al navegador que el documento está completo.

El navegador muestra entonces el documento recibido:

Image

¡Acabamos de escribir un servidor web «desde cero»!

16.4.2. Ejemplo 2

Ahora que conocemos los comandos que envía un navegador para solicitar una URL, vamos a solicitar una URL usando nuestro cliente TCP [tcp-client.php]. El servidor Apache de [Laragon] será nuestro servidor web: inícielo (el botón [Start All] en [Laragon]). La carpeta [inet/http/pages] contiene una 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 el directorio [php8-oct-2026] se encuentra dentro del directorio [<laragon>/www], esta página es accesible mediante la URL [http://localhost/php8-oct-2026/scripts-console/inet/http/pages/hello.html]. Vamos a solicitarla con nuestro cliente TCP, conectado al puerto 80 del servidor [localhost], donde se ejecuta el servidor web. Ingresamos los comandos que descubrimos en el apartado 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]: el comando [GET] con la ruta del documento solicitado;
  • [Host: localhost:80]: el encabezado [Host];
  • estos son los únicos dos comandos esenciales. Para los demás encabezados, el servidor web utilizará valores predeterminados;
  • la línea vacía que debe terminar los comandos del cliente;
  • Debajo de la línea en blanco viene la respuesta del servidor web Apache:
    • [HTTP/1.1 200 OK]: la línea de estado. El código 200 significa que se encontró el documento;
    • a continuación vienen los encabezados HTTP de la respuesta, seguidos de una línea en blanco. El encabezado [Content-Length] especifica el tamaño del documento en bytes;
    • después de la línea en blanco viene el documento HTML solicitado;
    • el encabezado [Server] identifica al servidor web: en este caso, un servidor Apache 2.4. Con [Laragon], verá la entrada [(Win64)] y las versiones de OpenSSL y de PHP;
  • [quit]: ingresamos [quit] para terminar la conexión del cliente. El servidor, por su parte, mantiene la conexión abierta unos segundos (modo keep-alive de HTTP/1.1) mientras espera otra solicitud y luego la cierra.

El archivo de registro [utilities/logs/localhost-80.txt] contiene los intercambios:

--> [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>]

Ya tenemos los fundamentos para programar un cliente TCP que solicite una URL.

16.4.3. Ejemplo 3

Image

El script [inet/http/http-01.php] es un cliente HTTP configurado mediante el archivo JSON [config-http-01.json]. El contenido de este último es el siguiente:

{
    "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"
    }
}
  • línea 2: el nombre de la máquina que aloja el servidor web al que se accede;
  • línea 3: el puerto en el que opera este servidor web;
  • línea 4: la URL del documento deseado;
  • línea 5: la máquina de destino en el formato machine:port;
  • línea 6: el identificador del cliente HTTP: puede ingresar lo que quiera;
  • línea 7: el tipo de documento que acepta el cliente, en este caso texto HTML;
  • línea 8: el idioma deseado para el documento solicitado;
  • línea 9: se le indica al servidor que cierre la conexión una vez enviado el documento. Sin este encabezado, un servidor HTTP/1.1 mantiene la conexión abierta unos segundos mientras espera otra solicitud, y nuestro cliente, que lee hasta que se cierra la conexión, esperaría innecesariamente;
  • línea 10: el carácter de fin de línea de los comandos enviados por el cliente. El protocolo HTTP exige la secuencia \r\n.

El script [http-01.php] es el siguiente:

<?php

declare(strict_types=1);

// cliente HTTP básico: solicita un documento a un servidor web y lo guarda en un archivo
// el archivo de configuración puede pasarse como argumento (php http-01.php config.json)
$configFileName = $argv[1] ?? "config-http-01.json";

// recuperamos la configuración
$config = json_decode(file_get_contents($configFileName), true);
// obtener el texto HTML de las URL del archivo de configuración
foreach ($config as $site => $protocol) {
    // lectura de la URL del sitio $site
    $result = getURL($site, $protocol);
    // visualización del resultado
    print "$result\n";
}

// --------------------------------------------------------------------------
function getURL(string $site, array $protocol, bool $tracking = true): string
{
    // lee la URL $protocol["GET"] del sitio $site y la almacena en el archivo output/$site.html
    // el diálogo cliente / servidor sigue el protocolo $protocol
    //
    // apertura de una conexión en el puerto $protocol["port"] de $site
    $connection = @stream_socket_client("tcp://$site:{$protocol["port"]}", $errorNumber, $error, 10);
    // retornar si hay error
    if ($connection === false) {
        return "Failed to connect to the site [$site:{$protocol["port"]}]: $error";
    }
    // $connection representa un flujo de comunicación bidireccional
    // entre el cliente (este programa) y el servidor web contactado
    // este canal se usa para el intercambio de comandos e información
    // el protocolo de diálogo es HTTP
    //
    // creación del archivo 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]";
    }
    // el cliente va a iniciar el diálogo HTTP con el servidor
    if ($tracking) {
        print "Client: start of the communication with the server [$site] ----------------------------\n";
    }
    // las líneas enviadas por el cliente deben terminar con \r\n
    $endOfLine = $protocol["endOfLine"];
    // por simplicidad, no se prueban los casos de error en la comunicación cliente / servidor
    // el cliente envía el comando GET para solicitar la URL $protocol["GET"]
    // sintaxis GET URL HTTP/1.1
    $command = "GET {$protocol["GET"]} HTTP/1.1$endOfLine";
    if ($tracking) {
        print "--> $command";
    }
    fwrite($connection, $command);
    // envío de los demás encabezados HTTP
    foreach ($protocol as $verb => $value) {
        if (!in_array($verb, ["GET", "port", "endOfLine"], true)) {
            // construimos el comando
            $command = "$verb: $value$endOfLine";
            if ($tracking) {
                print "--> $command";
            }
            // enviamos el comando al servidor
            fwrite($connection, $command);
        }
    }
    // los encabezados del protocolo HTTP deben terminar con una línea vacía
    fwrite($connection, $endOfLine);
    //
    // el servidor va a responder ahora por el canal $connection. Enviará todos
    // sus datos y luego cerrará el canal (Connection: close). Por lo tanto, el cliente lee todo
    // lo que viene de $connection hasta que el canal se cierre
    //
    // primero leemos los encabezados HTTP enviados por el servidor
    // también terminan con una línea vacía
    if ($tracking) {
        print "Response of the server [$site] ----------------------------\n";
    }
    while (($line = fgets($connection)) !== false) {
        // eliminamos los espacios de fin de línea (incluidos \r\n)
        $line = rtrim($line);
        // ¿tenemos la línea vacía que termina los encabezados?
        if ($line === "") {
            break;
        }
        // mostramos el encabezado HTTP
        if ($tracking) {
            print "<-- $line\n";
        }
    }
    // leemos el documento HTML que sigue a la línea vacía y lo almacenamos en el archivo
    while (($line = fgets($connection)) !== false) {
        fwrite($html, $line);
    }
    // el servidor ha cerrado la conexión - el cliente la cierra a su vez
    fclose($connection);
    fclose($html);
    // retorno
    return "End of the communication with the site [$site]. Check the file [output/$site.html]";
}

Comentarios sobre el código:

  • línea 7: el archivo de configuración puede pasarse como argumento. Usaremos varios archivos de configuración;
  • línea 10: el archivo de configuración se utiliza para crear un diccionario:
    • las claves del diccionario son los servidores web que se consultarán;
    • los valores especifican el protocolo HTTP que se utilizará;
  • línea 12: el programa recorre la lista de servidores web de la configuración;
  • línea 20: la función [getURL($site, $protocol, $tracking)] solicita un documento al sitio web $site y lo almacena en el archivo de texto [output/$site.html]. De forma predeterminada, los intercambios cliente/servidor se muestran en la consola ($tracking=true);
  • línea 26: la función [stream_socket_client] establece una conexión con un servicio TCP / IP que se ejecuta en el puerto [port] de la máquina $site. Una vez abierta la conexión cliente/servidor, muchos servicios TCP / IP intercambian líneas de texto. Es el caso del protocolo HTTP. El flujo de datos del servidor al cliente puede entonces tratarse como un archivo de texto leído con [fgets]. Lo mismo ocurre con el flujo de datos del cliente al servidor, que puede escribirse con [fwrite];
  • línea 40: creación del archivo [output/$site.html], en el que se almacenará el documento HTML recibido;
  • línea 54: el primer comando del cliente debe ser [GET URL HTTP/1.1]. Significa: «quiero (GET) la página [URL] del sitio web al que estoy conectado. Utilizo el protocolo HTTP, versión 1.1»;
  • líneas 60–70: se envían las demás líneas del protocolo HTTP [Host, User-Agent, Accept, Accept-Language, Connection]. Su orden no importa. El curso de PHP 7 probaba las claves que se debían excluir una por una; la función [in_array] con el tercer parámetro [true] (comparación estricta) es más legible;
  • línea 72: se envía una línea vacía al servidor para indicar que el cliente terminó de enviar sus encabezados HTTP y ahora espera el documento solicitado;
  • líneas 83–94: el servidor enviará primero una serie de encabezados HTTP que proporcionan diversos detalles sobre el documento solicitado. Estos encabezados terminan con una línea en blanco. Leemos una línea con [fgets], eliminamos los espacios en blanco finales (incluido \r\n) con [rtrim] y comprobamos si es la línea en blanco que marca el fin de los encabezados. Si no lo es, se muestra el encabezado;
  • líneas 95–97: las líneas de texto del documento pueden leerse una por una mediante un bucle while y guardarse en el archivo de texto [output/$site.html]. Una vez que el servidor web ha enviado todo el documento, cierra su conexión con el cliente. Del lado del cliente, esto se detecta como el fin del archivo: [fgets] pasa a ser [false].

Ejecutemos el script en un terminal abierto en la carpeta [inet/http]. La consola muestra los siguientes registros:

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

En nuestro ejemplo, el archivo recibido [output/localhost.html] es el siguiente:

<!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 es, en efecto, el documento [hello.html]: también es el que muestra un navegador.

16.4.4. Ejemplo 4

En este ejemplo mostraremos que el cliente HTTP que escribimos es insuficiente.

16.4.4.1. El protocolo HTTPS

Actualicemos el archivo de configuración. El archivo [config-http-01-https.json] es el siguiente:

{
    "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"
    }
}

Aquí solicitaremos el documento [hello.html] al puerto 443 del servidor [localhost]. El puerto 443 es el que utiliza el protocolo HTTP seguro, conocido como HTTPS. En este protocolo, el diálogo cliente-servidor comienza con un intercambio de información que asegura la conexión: esta se cifrará mediante el protocolo TLS. Por lo tanto, el cliente debe utilizar el protocolo HTTPS en lugar del protocolo HTTP, cosa que nuestro cliente no hace.

El servidor Apache de [Laragon] admite el protocolo HTTPS, pero no está habilitado de forma predeterminada. Se habilita desde el menú de [Laragon]: haga clic con el botón derecho en la ventana de [Laragon] y luego seleccione [Apache / SSL / Enabled]. El servidor Apache se reinicia y escucha entonces en dos puertos: el puerto 80 (HTTP) y el puerto 443 (HTTPS). [Laragon] ha generado para él un certificado autofirmado. Volveremos sobre este punto en el próximo capítulo.

Con este archivo de configuración ([php http-01.php config-http-01-https.json]), la salida de la consola es la siguiente:

> 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]: el servidor respondió que la solicitud del cliente no era válida.

El contenido del archivo [output/localhost.html] es el siguiente:

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

El servidor indica claramente que no utilizamos el protocolo correcto: «You’re speaking plain HTTP to an SSL-enabled server port» (se está hablando HTTP a un puerto reservado para SSL, el antiguo nombre de TLS).

16.4.4.2. Documento enviado en fragmentos

La carpeta [inet/http/pages] contiene un segundo documento, el script PHP [index.php]:

<?php

declare(strict_types=1);

// una página enviada en varias partes: [flush] fuerza el envío inmediato de lo que ya se ha escrito
// el servidor no conoce entonces el tamaño total del documento cuando envía los encabezados
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";
  • Línea 8: la función [flush] indica al servidor que envíe de inmediato al cliente lo que el script ya haya escrito. Como resultado, el script envía su documento en cinco partes separadas. Al enviar los encabezados de la respuesta HTTP, el servidor no conoce, por lo tanto, el tamaño total del documento.

Ahora usemos el siguiente archivo de configuración [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"
    }
}
  • Línea 4: solicitamos el archivo [pages/]. El servidor Apache envía entonces su documento predeterminado, en este caso [index.php].

La salida de la consola es la siguiente:

> 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]
  • El encabezado [X-Powered-By] indica que el documento fue generado por PHP 8.5;
  • el encabezado [Transfer-Encoding: chunked] indica que el servidor envía el documento en fragmentos. No hay encabezado [Content-Length]: el servidor no anuncia el tamaño del documento.

Esto da lugar a la presencia de números en el flujo enviado al cliente: cada fragmento va precedido de una línea que indica su tamaño en hexadecimal, y el documento termina con un fragmento de tamaño 0. Este es el archivo [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]: el tamaño hexadecimal del primer fragmento, que es de 97 bytes: las primeras cuatro líneas del documento;
  • [13]: el tamaño de los tres fragmentos siguientes, que es de 19 bytes;
  • [10]: el tamaño del último fragmento, 16 bytes;
  • [0]: el fragmento de 0 bytes que termina el documento.

Un buen cliente HTTP no debería dejar estos números en el documento final.

16.4.4.3. Redirección

Aquí está un último archivo de configuración, [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"
    }
}

Se parece al ejemplo anterior, pero la URL solicitada no termina con el carácter /. No son la misma URL. La ejecución del cliente HTTP produce entonces la siguiente salida en la consola:

> 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]: el código 301 indica que el documento solicitado se ha trasladado de forma permanente a la URL;
  • [Location: ...]: la nueva URL. Observe el carácter / al final esta vez: [pages] es un directorio, y el servidor Apache indica al cliente que se refiera a él mediante una URL que termina con /.

El archivo [output/localhost.html] queda entonces así:

1
2
3
4
5
6
7
8
9
<!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>

Un cliente HTTP debería poder seguir las redirecciones. En este caso, debería solicitar automáticamente la nueva URL [http://localhost/php8-oct-2026/scripts-console/inet/http/pages/].

16.4.5. Ejemplo 5

Los ejemplos anteriores nos han mostrado que nuestro cliente HTTP era insuficiente. Ahora presentaremos una herramienta llamada [curl] que permite obtener documentos web y resuelve los problemas mencionados: el protocolo HTTPS, los documentos enviados en fragmentos, las redirecciones… La herramienta [curl] viene incluida con Windows (a partir de Windows 10) y con [Laragon]. En un terminal de PowerShell, debe escribir [curl.exe], no [curl]: en PowerShell 5, [curl] es un alias de otro comando, [Invoke-WebRequest].

El comando [curl --help] muestra las principales opciones de configuración de [curl]. Hay varias decenas. Usaremos muy pocas. Para solicitar una URL, basta con escribir el comando [curl URL]. Este comando mostrará el documento solicitado en la consola. Si también desea ver los intercambios HTTP entre el cliente y el servidor, escriba [curl --verbose URL]. Por último, para guardar el documento HTML solicitado en un archivo, escriba [curl --verbose --output file URL].

Para no saturar las carpetas del curso, vayamos a una carpeta de trabajo (por ejemplo, [c:\temp\curl] ; créela si no existe) y solicitemos la 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
  • Las líneas que comienzan con [*] contienen información de [curl]: encontró dos direcciones para [localhost], la dirección IPv6 [::1] y la dirección IPv4 [127.0.0.1], y se conectó a la segunda;
  • las líneas que comienzan con [>] son las líneas que [curl] envía al servidor [localhost]. Se reconoce el protocolo HTTP;
  • las líneas que comienzan con [<] son las líneas que envía el servidor como respuesta;
  • las demás líneas muestran la barra de progreso de la descarga.

El archivo [localhost.html] contiene el documento solicitado. Puede comprobarlo abriendo el archivo en un editor de texto.

Ahora solicitemos la URL [https://localhost/php8-oct-2026/scripts-console/inet/http/pages/hello.html]. Para obtener la URL, el cliente HTTP debe poder comunicarse mediante HTTPS. Este es el caso del cliente [curl]. Como el certificado del servidor es autofirmado, [curl] se negaría a continuar. La opción [--insecure] le indica que no verifique el certificado. La salida de la consola es la siguiente:

> 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
  • Las líneas [TLSv1.3 ...] muestran los intercambios cliente/servidor para asegurar la conexión: la conexión estará cifrada;
  • las líneas [Server certificate] describen el certificado enviado por el servidor. Fue emitido para la máquina [localhost] (CN=localhost) por esa misma máquina (issuer: CN=localhost): es un certificado autofirmado. [curl] informa que no pudo verificar el certificado, pero continúa de todos modos;
  • A continuación vienen los intercambios HTTP habituales, cifrados. [HTTP/1.1 200 OK]: se encontró el documento solicitado.

Ahora solicitemos la URL [http://localhost/php8-oct-2026/scripts-console/inet/http/pages]. Habíamos visto que para esta URL había una redirección a la misma URL terminada con el carácter /. La salida de la consola es entonces la siguiente:

> 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 la opción [--location] para indicar que queremos seguir las redirecciones enviadas por el servidor;
  • [HTTP/1.1 301 Moved Permanently] y [Location]: el servidor indica que el documento solicitado se encuentra en otra URL;
  • [Issue another request to this URL]: [curl] envía una nueva solicitud, esta vez a la nueva URL, reutilizando la misma conexión;
  • [HTTP/1.1 200 OK]: el servidor responde que encontró el documento solicitado;
  • [Transfer-Encoding: chunked]: lo envía en fragmentos. [curl] elimina los tamaños de los fragmentos.

El documento solicitado se encontrará en el archivo [pages.html].

16.4.6. Ejemplo 6

PHP tiene una extensión llamada [curl] que permite utilizar las capacidades de la herramienta [curl] dentro de un programa PHP. Está habilitada en el PHP de [Laragon]: esto puede verificarse con el comando [php -m], que lista las extensiones cargadas. Si no estuviera habilitada, tendría que quitar el comentario de la línea [extension=curl] en el archivo [php.ini].

Escribiremos un script llamado [http-02.php] que utilizará el siguiente archivo de configuración 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 del diccionario [key => value] tiene la siguiente estructura:

  • key: un nombre que se usará para nombrar el archivo donde se guardará el documento;
  • value: un diccionario con las siguientes claves:
    • timeout: tiempo máximo de espera de una respuesta del servidor. Transcurrido este tiempo, el cliente se desconectará;
    • url: URL del documento solicitado;
    • verify-peer: ¿se debe verificar el certificado del servidor (HTTPS)? True de forma predeterminada.

El código del script [http-02.php] es el siguiente:

<?php

declare(strict_types=1);

// cliente HTTP escrito con la extensión [curl] de PHP
// puede hablar HTTPS, seguir redirecciones y recibir un documento enviado por fragmentos

// constantes
const CONFIG_FILE_NAME = "config-http-02.json";

// recuperamos la configuración
$config = json_decode(file_get_contents(CONFIG_FILE_NAME), true);

// obtener el texto HTML de las URL del archivo de configuración
foreach ($config as $site => $info) {
    // lectura de la URL del sitio $site
    $result = getUrl($site, $info["url"], $info["timeout"], $info["verify-peer"] ?? true);
    // visualización del resultado
    print "$result\n";
}

// --------------------------------------------------------------------------
function getUrl(string $site, string $url, int $timeout, bool $verifyPeer = true): string
{
    // lee la URL $url y la almacena en el archivo output/$site.html
    //
    // seguimiento
    print "Client: start of the communication with the server [$site] ----------------------------\n";
    // inicialización de una sesión cURL: desde PHP 8.0, [curl_init] devuelve un objeto [CurlHandle]
    $curl = curl_init($url);
    if ($curl === false) {
        return "Error while initializing the cURL session for the site [$site]";
    }
    // opciones de curl
    $options = [
        // modo detallado: se muestran los intercambios cliente / servidor...
        CURLOPT_VERBOSE => true,
        // ... en la salida estándar (por defecto, es la salida de error)
        CURLOPT_STDERR => STDOUT,
        // nueva conexión - sin caché
        CURLOPT_FRESH_CONNECT => true,
        // tiempo de espera de la solicitud (en segundos)
        CURLOPT_TIMEOUT => $timeout,
        CURLOPT_CONNECTTIMEOUT => $timeout,
        // verificar o no la validez del certificado del servidor (HTTPS)
        CURLOPT_SSL_VERIFYPEER => $verifyPeer,
        CURLOPT_SSL_VERIFYHOST => $verifyPeer ? 2 : 0,
        // seguir las redirecciones
        CURLOPT_FOLLOWLOCATION => true,
        // recuperar el documento solicitado como cadena de caracteres
        CURLOPT_RETURNTRANSFER => true,
    ];
    // configuración de curl
    curl_setopt_array($curl, $options);
    // ejecución de la solicitud
    $pageContent = curl_exec($curl);
    // la sesión cURL se cierra automáticamente cuando el objeto $curl desaparece
    // ([curl_close] es inútil desde PHP 8.0 y está obsoleta desde PHP 8.5)
    //
    // uso del resultado
    if ($pageContent === false) {
        // hubo un error de comunicación
        return "Error communicating with the server [$site]: " . curl_error($curl);
    }
    // guardado del resultado en 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 exitoso
    return "End of the communication with the server [$site]. Check the file [output/$site.html]";
}

Comentarios:

  • línea 12: el archivo de configuración se utiliza para crear el diccionario [$config];
  • línea 15: recorremos la lista de sitios que se encuentra en la configuración;
  • línea 17: para cada sitio se llama a la función [getUrl] para descargar la URL [$info["url"]] con un tiempo de espera de [$info["timeout"]];
  • línea 30: se inicia una sesión [curl]. [curl_init] todavía no se conecta al servidor web. A partir de PHP 8.0, devuelve un objeto de la clase [CurlHandle] (en lugar de un recurso), que servirá como parámetro de todas las funciones [curl] posteriores. Si falla la inicialización de la sesión, la función devuelve el booleano [false];
  • líneas 35–52: el diccionario [$options] configura la conexión [curl] con el servidor:
    • [CURLOPT_VERBOSE]: muestra los intercambios cliente/servidor, de forma similar a la opción [--verbose] de la herramienta [curl]. [CURLOPT_STDERR] los envía a la salida estándar ([STDOUT]) en lugar de a la salida de errores, lo que preserva el orden de las visualizaciones;
    • [CURLOPT_SSL_VERIFYPEER] y [CURLOPT_SSL_VERIFYHOST]: verifican el certificado del servidor y el nombre que contiene;
    • [CURLOPT_FOLLOWLOCATION]: sigue las redirecciones, de forma similar a la opción [--location];
    • [CURLOPT_RETURNTRANSFER]: devuelve el documento recibido como una cadena;
  • línea 54: las opciones de conexión se pasan al objeto [$curl];
  • línea 56: conexión a la URL solicitada con las opciones definidas. Debido a la opción [CURLOPT_RETURNTRANSFER => true], la función [curl_exec] devuelve el documento enviado por el servidor como una cadena, sin los tamaños de fragmento si se envió en fragmentos. La función [curl_exec] devuelve el valor booleano [false] si la conexión falla. La función [curl_error] devuelve entonces la causa del error;
  • línea 57: el curso de PHP 7 cerraba la sesión con la función [curl_close]. Desde PHP 8.0, esta función ya no hace nada: la sesión se cierra cuando el objeto [CurlHandle] deja de utilizarse. Está obsoleta desde PHP 8.5;
  • línea 69: la página recibida se guarda en un archivo local.

Al ejecutar el script [http-02.php], se muestra la siguiente salida en la consola:

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

Se producen los mismos intercambios de datos que con la herramienta [curl]: las líneas que comienzan con [>] se envían al servidor; las que comienzan con [<] se reciben del servidor; y las que comienzan con [*] contienen información de [curl]. Se siguió la redirección y se estableció la conexión HTTPS.

16.4.7. Conclusión

En esta sección exploramos el protocolo HTTP y escribimos un script [http-02.php] capaz de descargar una URL de la web. En el próximo capítulo utilizaremos para ello el componente [HttpClient] del framework Symfony.

16.5. El protocolo SMTP (Simple Mail Transfer Protocol)

16.5.1. Introducción

Image

En este capítulo:

  • [Server B] será un servidor SMTP local que instalaremos;
  • [Client A] será un cliente SMTP en diversas formas:
    • el cliente [tcp-client.php] para descubrir el protocolo SMTP;
    • un script PHP que reproduce el protocolo SMTP descubierto con [tcp-client.php];
    • un script PHP que utiliza la biblioteca [Symfony Mailer] para enviar todo tipo de correos electrónicos.

16.5.2. Instalación de un servidor SMTP de prueba: [Mailpit]

El curso de PHP 7 instalaba el servidor de correo [hMailServer], que ya no recibe mantenimiento, y lo configuraba para retransmitir los correos a través del servidor SMTP de Gmail. En su lugar, usaremos [Mailpit] (https://mailpit.axllent.org), una herramienta gratuita diseñada para desarrolladores:

  • es un servidor SMTP que acepta todos los correos que se le envían, sin importar el remitente o el destinatario, pero no los reenvía: los almacena. Esto significa que puede enviar correos a cualquier dirección sin riesgo de molestar a nadie;
  • ofrece una interfaz web que permite leer los correos recibidos;
  • también ofrece un servidor POP3, que usaremos para leer correos de forma programática;
  • es un único archivo ejecutable que no requiere instalación.

[Mailpit] puede descargarse desde https://github.com/axllent/mailpit/releases. En Windows, descargue el archivo [mailpit-windows-amd64.zip] de la última versión y copie el archivo [mailpit.exe] que contiene en la carpeta [inet/mailpit] del código del curso. Esta carpeta ya contiene los siguientes archivos:

1
2
3
4
5
6
mailpit
├── mailpit.bat
├── mailpit-secure.bat
├── pop3-users.txt
├── relay.yml
└── smtp-users.txt

El archivo [pop3-users.txt] define los usuarios del servidor POP3 de [Mailpit] en la forma [user:password]. Solo hay uno:

guest:guest

El archivo [mailpit.bat] inicia [Mailpit] con este archivo de usuarios:

1
2
3
@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 la carpeta del archivo [.bat]: por lo tanto, puede iniciar [mailpit.bat] desde cualquier carpeta, por ejemplo haciendo doble clic en él en el Explorador de Windows;
  • la opción [--pop3-auth-file] inicia el servidor POP3 de [Mailpit].

También puede escribir el comando directamente en un terminal abierto en la carpeta [inet/mailpit]: [.\mailpit.exe --pop3-auth-file pop3-users.txt]. [Mailpit] mostrará entonces líneas de registro que indican que ofrece tres servicios:

  • un servidor SMTP en el puerto 1025 (el puerto estándar del protocolo SMTP es el 25, pero los puertos por debajo de 1024 suelen estar reservados o bloqueados);
  • un servidor POP3 en el puerto 1110 (el puerto estándar es el 110);
  • una interfaz web en la URL [http://localhost:8025].

El terminal debe permanecer abierto mientras quiera usar [Mailpit]: la combinación de teclas [Ctrl-C] lo cierra. Los correos recibidos se almacenan en memoria mientras [Mailpit] esté en ejecución. Volveremos a ver [Mailpit] en las próximas versiones del servidor de cálculo de impuestos, que enviará correos a su administrador.

El segundo archivo, [mailpit-secure.bat], inicia una segunda instancia de [Mailpit], que usaremos más adelante para examinar las conexiones seguras:

1
2
3
4
@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]: el servidor SMTP de esta instancia escucha en el puerto 1587;
  • [--listen 0.0.0.0:8026 --ui-tls-cert sans:localhost --ui-tls-key sans:localhost]: su interfaz web está en el puerto 8026 (el puerto 8025 está ocupado por la primera instancia), en HTTPS;
  • [--smtp-tls-cert sans:localhost --smtp-tls-key sans:localhost]: [Mailpit] genera su propio certificado autofirmado para la máquina [localhost]. Este certificado le permite cifrar las comunicaciones con sus clientes;
  • [--smtp-require-starttls]: los clientes deben cifrar la conexión (mediante el comando STARTTLS, del que hablaremos más adelante) antes de enviar un correo;
  • [--smtp-auth-file smtp-users.txt]: los clientes deben autenticarse con una de las cuentas del archivo [smtp-users.txt]. Solo hay una: [guest@localhost] con la contraseña [guest];
  • [--smtp-relay-config relay.yml --smtp-relay-all]: los correos entrantes se reenvían al servidor SMTP definido en [relay.yml], es decir, a la primera instancia de [Mailpit] (localhost, puerto 1025):
1
2
3
4
# relé SMTP de la instancia "segura" de Mailpit (puerto 1587)
# a la instancia principal (puerto 1025)
host: localhost
port: 1025

Esta segunda instancia actúa como lo haría un servidor SMTP público, como el de Gmail ([smtp.gmail.com], puerto 587), que también exige una conexión cifrada y autenticación. Lo usaremos con una cuenta de Gmail llegado el momento, para quienes tengan una.

Iniciemos la primera instancia de [Mailpit] y abramos su interfaz web [http://localhost:8025] en un navegador:

Image

Veremos cómo se llena esta página a medida que avancemos con los ejemplos.

16.5.3. El protocolo SMTP

Image

Exploraremos el protocolo SMTP utilizando el siguiente entorno:

  • el cliente A será el cliente TCP genérico ([tcp-client.php]);
  • el servidor B será el servidor SMTP de [Mailpit];
  • el cliente A le pedirá al servidor B que entregue un correo al usuario [guest@localhost];
  • verificaremos mediante la interfaz web de [Mailpit] que el correo se recibió correctamente.

En una ventana de terminal abierta en la carpeta [inet/utilities], iniciamos el cliente e ingresamos los comandos del 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]: nos conectamos al puerto 1025 de la máquina local, donde se ejecuta el servicio SMTP de [Mailpit]. El argumento [--quit bye] indica que el usuario saldrá del programa ingresando el comando [bye]. Sin este argumento, el comando para terminar el programa es [quit]. Sin embargo, [QUIT] también es un comando del protocolo SMTP. Por lo tanto, debemos evitar esta ambigüedad;
  • [220 vm Mailpit ESMTP Service ready]: en cuanto se establece la conexión, el servidor envía su mensaje de bienvenida. El código [220] indica que el servidor está listo. [vm] es el nombre de la máquina que ejecuta [Mailpit]: usted verá el nombre de su computadora;
  • [EHLO localhost]: el cliente envía el comando [EHLO client-machine-name]. El servidor responde con una serie de líneas de la forma [250-xx], la última de las cuales tiene la forma [250 xx] (un espacio, no un guion, después del código). El código [250] indica que el comando enviado por el cliente se ejecutó correctamente. Las líneas siguientes enumeran las extensiones del protocolo SMTP que admite el servidor, como el tamaño máximo del mensaje [SIZE];
  • [MAIL FROM: <guest@localhost>]: el cliente especifica el remitente del mensaje y el servidor lo acepta (código 250);
  • [RCPT TO: <guest@localhost>]: el cliente especifica el destinatario del mensaje. Puede haber varios comandos [RCPT TO] para varios destinatarios;
  • [DATA]: este comando informa al servidor que el cliente está a punto de enviar el contenido del mensaje. El servidor responde con el código [354] e indica cómo terminar el mensaje;
  • A continuación, el cliente envía una lista de líneas de texto que termina con una línea que contiene únicamente un punto. El mensaje puede comenzar con líneas [Subject:, From:, To:] para definir, respectivamente, el asunto del mensaje, el remitente y el destinatario. Estos encabezados deben ir seguidos de una línea en blanco y luego del texto del mensaje;
  • [250 2.0.0 Ok: queued as ...]: una vez que el servidor ha recibido la línea que contiene únicamente un punto, pone el mensaje en cola para su entrega;
  • [QUIT]: el cliente notifica al servidor que ha terminado. El servidor responde con el código [221] y luego cierra la conexión, lo cual el cliente detecta.

Verifiquemos en la interfaz web de [Mailpit] que el usuario [guest@localhost] efectivamente recibió el mensaje:

Image

El remitente aparece en [From], el destinatario en [To], el asunto en [Subject], y se muestra el texto del mensaje. La pestaña [Headers] muestra todos los encabezados del mensaje, y la pestaña [Raw] muestra el texto sin formato recibido por [Mailpit].

Nuestro cliente [tcp-client.php] envió el mensaje con éxito. Ya tenemos la base para crear un cliente SMTP escrito en PHP.

16.5.4. Un cliente SMTP básico escrito en PHP

Reproduciremos en PHP lo que aprendimos antes sobre el protocolo SMTP.

Image

El script [inet/smtp/smtp-01.php] se configura mediante el siguiente archivo 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] es un diccionario en el que cada elemento tiene la forma [name => info]. El valor [info] es a su vez un diccionario con las siguientes claves y valores:

  • [smtp-server]: el nombre del servidor SMTP que se utilizará;
  • [smtp-port]: el número de puerto del servicio SMTP;
  • [from]: el remitente del mensaje;
  • [to]: el destinatario del mensaje;
  • [subject]: el asunto del mensaje;
  • [message]: el mensaje que se enviará.

Se envían tres mensajes:

  • el primero utiliza el servidor SMTP de [Mailpit] para enviar un correo al usuario [guest@localhost];
  • el segundo utiliza el mismo servidor para enviar un correo a una dirección de Gmail. [Mailpit] retendrá este correo sin entregarlo;
  • el tercero utiliza la segunda instancia de [Mailpit], la del puerto 1587, que exige una conexión cifrada. Por lo tanto, debe haberse iniciado [mailpit-secure.bat].

El código [smtp-01.php] del cliente SMTP es el siguiente:

<?php

declare(strict_types=1);

// cliente SMTP (Simple Mail Transfer Protocol) usado para enviar un mensaje
// protocolo de comunicación cliente-servidor SMTP
// -> el cliente se conecta al puerto del servidor SMTP (25, 587, 1025...)
// <- el servidor le envía un mensaje de bienvenida
// -> el cliente envía el comando EHLO nombre de su máquina
// <- el servidor responde OK o no
// -> el cliente envía el comando MAIL FROM: <sender>
// <- el servidor responde OK o no
// -> el cliente envía el comando RCPT TO: <recipient>
// <- el servidor responde OK o no
// -> el cliente envía el comando DATA
// <- el servidor responde OK o no
// -> el cliente envía todas las líneas de su mensaje y termina con una línea que contiene el
// único carácter .
// <- el servidor responde OK o no
// -> el cliente envía el comando QUIT
// <- el servidor responde OK o no
// las respuestas del servidor tienen la forma xxx texto donde xxx es un número de 3 dígitos. Cualquier
// número xxx >= 400 señala un error.
// La respuesta puede tener varias líneas de la forma xxx-texto, excepto la última
// que tiene la forma xxx texto (espacio después del código)
// las líneas de texto intercambiadas deben terminar con los caracteres CR (13) y LF (10)

// los parámetros para el envío de los correos
const CONFIG_FILE_NAME = "config-smtp-01.json";

// recuperamos la configuración
$mails = json_decode(file_get_contents(CONFIG_FILE_NAME), true);

// envío de los correos
foreach ($mails as $name => $info) {
    // seguimiento
    print "Sending the mail [$name]\n";
    // envío del correo
    $result = sendmail($info, verbose: true);
    // visualización del resultado
    print "$result\n";
}
// fin
print "Done\n";

// --------------------------------------------------------------------------
function sendmail(array $info, bool $verbose = true): string
{
    // envía el mensaje descrito por [$info]
    // si $verbose=true, hace seguimiento de los intercambios cliente-servidor
    //
    // el nombre de la máquina cliente
    $client = gethostname();
    // apertura de una conexión con el 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 un flujo de comunicación bidireccional
    // entre el cliente (este programa) y el servidor SMTP contactado
    try {
        // después de la conexión, el servidor envía un mensaje de bienvenida que leemos
        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);
        // el mensaje: encabezados (From, To, Subject), una línea vacía, el texto
        // y una línea reducida a un punto
        // los finales de línea del texto deben ser \r\n
        $text = str_replace("\n", "\r\n", $info["message"]);
        // una línea del texto que empieza con un punto debe empezar con dos puntos
        $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) {
        // el servidor señaló un error
        return "Error: " . $ex->getMessage();
    } finally {
        // en todos los casos, cerramos la conexión
        fclose($connection);
    }
}

// --------------------------------------------------------------------------
function sendCommand($connection, string $command, bool $verbose): void
{
    // envía $command al canal $connection y lee la respuesta del servidor
    // modo detallado si $verbose=true
    // lanza una RuntimeException si el servidor señala un error
    //
    // envío del comando si no está vacío
    if ($command !== "") {
        fwrite($connection, "$command\r\n");
        if ($verbose) {
            display($command, 1);
        }
    }
    // lectura de la respuesta: líneas [xxx-text] terminadas por una línea [xxx text]
    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 de la respuesta
    $code = (int) substr($response, 0, 3);
    // ¿error devuelto por el servidor?
    if ($code >= 400) {
        throw new RuntimeException(rtrim(substr($response, 4)));
    }
}

// --------------------------------------------------------------------------
function display(string $exchange, int $direction): void
{
    // muestra $exchange en pantalla
    // si $direction=1 muestra → [$exchange] (con finales de línea \n en lugar de \r\n)
    // si $direction=2 muestra ← [$exchange] sin los caracteres de fin de línea \r\n
    print match ($direction) {
        1 => "--> [" . str_replace("\r\n", "\n", $exchange) . "]\n",
        2 => "<-- [" . rtrim($exchange, "\r\n") . "]\n",
    };
}

Comentarios:

  • línea 32: se procesa el archivo de configuración. El segundo parámetro, [true], de [json_decode] exige arreglos asociativos en lugar de objetos;
  • línea 35: recorremos los elementos del diccionario [$mails]. Cada elemento tiene la forma [name => info], donde [name] es un nombre cualquiera e [info] es un diccionario que contiene la información necesaria para enviar un correo;
  • línea 39: el correo se envía mediante la función [sendmail], que recibe dos parámetros:
    • $info: el diccionario que contiene la información necesaria para enviar el correo;
    • $verbose: un booleano que indica si los intercambios cliente/servidor deben mostrarse o no en la consola. Observe el argumento con nombre [verbose: true] (PHP 8.0), que hace la llamada más legible que un simple [true];
  • línea 53: el nombre de la máquina cliente, utilizado por el comando EHLO;
  • línea 55: apertura de una conexión con el servidor SMTP. El curso de PHP 7 usaba la función [fsockopen], que sigue disponible. [stream_socket_client] es más general: es la que usamos en [tcp-client.php];
  • líneas 61–86: la función [sendmail] envía los diversos comandos que debe enviar un cliente SMTP: lectura del mensaje de bienvenida, EHLO, MAIL FROM, RCPT TO, DATA, el mensaje, QUIT. Cada comando se envía mediante la función [sendCommand], que lanza una excepción [RuntimeException] si el servidor responde con un código de error. Por lo tanto, todos los comandos están contenidos en un bloque [try]: el primer error hace que el programa entre en el bloque [catch], que devuelve el mensaje de error. El bloque [finally] se ejecuta en todos los casos: ahí es donde se cierra la conexión. El código es así mucho más corto que el del curso de PHP 7, que verificaba el resultado de cada comando;
  • líneas 75–78: preparación del mensaje. Las líneas del mensaje deben terminar con \r\n. Si una línea de texto contiene únicamente un punto, el servidor supondrá que el mensaje está completo. Para evitarlo, el protocolo SMTP exige que el cliente duplique el punto al comienzo de una línea: el servidor eliminará ese punto adicional. La expresión regular [/^\./m] (opción m: multilínea) coincide con un punto al comienzo de una línea;
  • línea 93: la función [sendCommand] se encarga de enviar los comandos del cliente al servidor SMTP y de leer la respuesta. Acepta tres parámetros:
    • [$connection]: la conexión que une al cliente con el servidor;
    • [$command]: el comando que se enviará. Si está vacío, no se envía nada; la función simplemente lee una respuesta (como en el caso del mensaje de bienvenida);
    • [$verbose]: si es true, los intercambios cliente/servidor se muestran en la consola;
  • líneas 107–115: lee todas las líneas de la respuesta. Cada línea tiene la forma [XXX-YYY], donde XXX es un código numérico, excepto la última línea de la respuesta, que tiene la forma [XXX YYY] (falta el guion). Por lo tanto, el bucle [do ... while] se detiene cuando el cuarto carácter de la línea no es un guion;
  • línea 119: si el código numérico XXX es mayor o igual que 400, el servidor devolvió un error (los códigos 4xx indican errores temporales y los códigos 5xx indican errores permanentes);
  • línea 125: la función [display] utiliza una expresión [match] para seleccionar el texto que se mostrará según la dirección del intercambio.

La ejecución del script produce la siguiente salida en la consola:

> 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
  • Los dos primeros envíos se realizan con éxito;
  • el tercero falla: después del comando [MAIL FROM], el servidor del puerto 1587 devuelve un código de error 530 con el mensaje [Must issue a STARTTLS command first]. Observe que en su respuesta al comando EHLO anunció la extensión [STARTTLS] y la autenticación [AUTH LOGIN PLAIN]. El cliente SMTP debe primero cifrar la conexión (comando STARTTLS) y luego autenticarse (comando AUTH). Nuestro cliente no lo hizo y por eso es rechazado. El servidor SMTP de Gmail ([smtp.gmail.com], puerto 587) responde exactamente de la misma manera.

La interfaz web de [Mailpit] muestra los correos recibidos. Observe que el correo destinado a [php8parlexemple@gmail.com] está efectivamente ahí: [Mailpit] no lo reenvió a Gmail.

16.5.5. Un segundo cliente SMTP, que utiliza la biblioteca [Symfony Mailer]

El cliente anterior tiene al menos dos deficiencias:

  • no puede usar una conexión segura si el servidor la exige;
  • no puede adjuntar archivos al mensaje.

En nuestro nuevo script utilizaremos la biblioteca [Symfony Mailer] (https://symfony.com/doc/current/mailer.html). El curso de PHP 7 usaba la biblioteca [SwiftMailer], que no recibe mantenimiento desde 2021: [Symfony Mailer] es su sucesora, escrita por el mismo equipo. La biblioteca se instaló junto con las demás dependencias del curso mediante el comando [composer install] (vea el archivo [composer.json] en la raíz de la carpeta [php8-oct-2026]) y se encuentra en la carpeta [vendor/symfony/mailer]. Utiliza el componente [symfony/mime], que puede generar mensajes de cualquier formato.

El script [inet/smtp/smtp-02.php] utilizará el siguiente archivo de configuración 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"
        ]
    }
}

Contiene los mismos campos que el archivo [config-smtp-01.json], además de campos adicionales:

  • [tls]: establecido en [true], especifica que debe utilizarse una conexión segura y autenticada con el servidor SMTP. En este caso, deben agregarse los siguientes campos:
    • [user]: el nombre de usuario con el que se autentica la conexión;
    • [password]: su contraseña;
    • [verify-peer]: ¿se debe verificar el certificado enviado por el servidor? Esto debe hacerse con un servidor público. Con nuestro servidor de prueba, que tiene un certificado autofirmado, debe establecerlo en [false];
  • [attachments]: especifica los nombres de los archivos que se adjuntarán al correo. Se encuentran en la carpeta [smtp/attachments];
  • [enabled]: cuando se establece en [false], deshabilita el envío. Es el caso del tercer envío, que utiliza el servidor SMTP de Gmail.

Para usar el servidor SMTP de Gmail, necesita una cuenta de Gmail (reemplace [php8parlexemple@gmail.com] por su dirección) con la verificación en dos pasos habilitada, y debe crear para ella una «contraseña de aplicación» en la sección [Security] de la configuración de su cuenta de Google. Esta contraseña de 16 caracteres reemplaza la contraseña de la cuenta en aplicaciones como la nuestra. Ingrésela en el campo [password] y cambie el valor de [enabled] a [true].

El código del script [smtp-02.php] es el siguiente:

<?php

declare(strict_types=1);

// cliente SMTP (Simple Mail Transfer Protocol) escrito con la biblioteca [Symfony Mailer]
// puede usar una conexión segura y adjuntar archivos al mensaje

// dependencias
require_once __DIR__ . "/../../../vendor/autoload.php";

use Symfony\Component\Mailer\Mailer;
use Symfony\Component\Mailer\Transport;
use Symfony\Component\Mime\Email;

// los parámetros para el envío de los correos: el archivo de configuración
// puede pasarse como argumento (php smtp-02.php config.json)
$configFileName = $argv[1] ?? "config-smtp-02.json";

// recuperamos la configuración
$mails = json_decode(file_get_contents($configFileName), true);

// envío de los correos
foreach ($mails as $name => $info) {
    // ¿envío desactivado en la configuración?
    if (($info["enabled"] ?? true) === false) {
        print "Sending of the mail [$name] disabled\n";
        continue;
    }
    // seguimiento
    print "Sending the mail [$name]\n";
    // envío del correo
    $result = sendmail($name, $info);
    // visualización del resultado
    print "$result\n";
}
// fin
print "Done\n";

// --------------------------------------------------------------------------
function sendmail(string $name, array $info): string
{
    // envía $info["message"] al servidor SMTP $info["smtp-server"] en el puerto $info["smtp-port"]
    // si $info["tls"] es true, la conexión es segura y autenticada
    // el correo se envía en nombre de $info["from"]
    // para el destinatario $info["to"]
    // los documentos $info["attachments"] se adjuntan al mensaje
    // el mensaje tiene el asunto $info["subject"]
    //
    try {
        // creación del mensaje
        $email = (new Email())
            // remitente
            ->from($info["from"])
            // destinatario (puede haber varios: to(a, b, c), cc(...), bcc(...))
            ->to($info["to"])
            // asunto del mensaje
            ->subject($info["subject"])
            // texto del mensaje
            ->text($info["message"])
            // variante HTML del texto
            ->html("<b>" . str_replace("\n", "<br/>", $info["message"]) . "</b>");
        // archivos adjuntos
        foreach ($info["attachments"] as $attachment) {
            // ruta del archivo adjunto
            $fileName = __DIR__ . $attachment;
            // verificamos que el archivo exista
            if (file_exists($fileName)) {
                // adjuntamos el documento al mensaje
                $email->attachFromPath($fileName);
            } else {
                print "The attachment [$fileName] does not exist\n";
            }
        }
        // el transporte del mensaje: un DSN (Data Source Name) de la forma
        // smtp://user:password@server:port?options
        $dsn = "smtp://{$info["smtp-server"]}:{$info["smtp-port"]}";
        if ($info["tls"]) {
            // conexión segura (STARTTLS) y 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);
        }
        // el gestor de envío
        $mailer = new Mailer(Transport::fromDsn($dsn));
        // envío del mensaje
        $mailer->send($email);
        // fin
        return "Message [$name] sent";
    } catch (Throwable $ex) {
        // error
        return "Error while sending the message [$name]: " . $ex->getMessage();
    }
}

Comentarios:

  • línea 9: cargamos el archivo [vendor/autoload.php] creado por Composer. Este archivo permite cargar los archivos de definición de clases de las bibliotecas en cuanto esas clases se utilizan por primera vez. Esto nos evita tener que crear tantos archivos [require] como clases e interfaces de [Symfony Mailer] utilicemos. La ruta es relativa a la carpeta del script ([__DIR__]): el script funciona sin importar la ubicación de la carpeta [php8-oct-2026];
  • líneas 11–13: las clases de [Symfony Mailer] están en espacios de nombres. Las instrucciones [use] nos permiten referirnos a ellas por sus nombres cortos;
  • línea 17: el archivo de configuración puede pasarse como argumento al script; de lo contrario, se usa de forma predeterminada [config-smtp-02.json];
  • línea 25: un envío se deshabilita si su campo [enabled] está establecido en [false]. El operador [??] devuelve [true] si el campo no existe;
  • línea 40: la nueva función [sendmail], que tiene dos parámetros:
    • [$name], que sirve para distinguir los mensajes;
    • [$info]: la información necesaria para enviar el mensaje a su destinatario;
  • líneas 51–61: definimos el mensaje mediante la clase [Email]. Sus métodos devuelven el propio objeto, lo que permite encadenarlos:
    • [from] establece el remitente del mensaje;
    • [to] establece el destinatario del mensaje;
    • [subject] establece el asunto del mensaje;
    • [text] establece el cuerpo del mensaje;
    • [html] define una variante (HTML) del mensaje. Aquí cambiamos los caracteres de fin de línea por la etiqueta HTML [<br/>] y damos formato de negrita a todo el texto. Cuando el mensaje tiene variantes, los clientes de correo muestran la variante preferida por el usuario;
  • líneas 63–72: el método [attachFromPath] adjunta un archivo al mensaje. El tipo de archivo (application/pdf...) se infiere de su extensión;
  • líneas 76–82: una vez definido el mensaje que se enviará, hay que especificar cómo enviarlo. [Symfony Mailer] describe el transporte del mensaje mediante una cadena llamada DSN (Data Source Name), de la forma [smtp://user:password@server:port?options]. Para una conexión segura, se agregan el usuario y la contraseña, codificados con [rawurlencode] (el carácter @ de [guest@localhost] se convierte en %40), junto con dos opciones: [require_tls=1] exige el cifrado de la conexión y [verify_peer=0] desactiva la verificación del certificado del servidor. Observe que [Symfony Mailer] usa automáticamente el comando STARTTLS cuando el servidor lo anuncia;
  • línea 85: la clase [Mailer] envía los mensajes. Se le debe pasar el transporte seleccionado, que se creó a partir del DSN mediante el método estático [Transport::fromDsn];
  • línea 87: se envía el mensaje;
  • línea 90: la biblioteca lanza una excepción en cuanto algo sale mal.

Al ejecutar el script [smtp-02.php] (con ambas instancias de [Mailpit] ya en ejecución), se muestra la siguiente salida en la consola:

1
2
3
4
5
6
7
> 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

La interfaz web de [Mailpit] muestra ambos mensajes. El mensaje [test-secure-server] pasó por la instancia segura, que lo retransmitió a la instancia principal. Este es el mensaje [test-localhost]:

Image

  • en la esquina superior derecha, la insignia [Attachments (5)] indica los cinco archivos adjuntos, cuyas miniaturas son visibles en la parte inferior de la página;
  • la pestaña [HTML] muestra la variante HTML del mensaje (en negrita), mientras que la pestaña [Text] muestra su variante de texto.

La pestaña [Raw] muestra el texto sin formato del mensaje recibido. Aquí está, con las líneas que codifican el contenido de los archivos adjuntos eliminadas:

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] y [Received]: estos encabezados fueron agregados por [Mailpit] al recibir el mensaje. Cada servidor por el que pasa un mensaje agrega un encabezado [Received];
  • [From], [To], [Subject]: el remitente, el destinatario y el asunto;
  • [Content-Type: multipart/mixed; boundary=...]: el mensaje consta de varias partes, separadas por líneas con la etiqueta [--boundary]. A la última le sigue la línea [--boundary--]. Este es el formato MIME (Multipurpose Internet Mail Extensions);
  • la primera parte es a su vez de tipo [multipart/alternative]: contiene dos variantes del mensaje, en [text/plain] y en [text/html]. Están codificadas en [quoted-printable], una codificación que deja sin codificar los caracteres ASCII y codifica los demás (é se convierte en =C3=A9);
  • A continuación están los cinco archivos adjuntos ([Content-Disposition: attachment]), codificados en [base64], una codificación que transforma cualquier contenido binario en líneas de caracteres ASCII;
  • el nombre de archivo [Cours-Tutoriels-Serge-Tahé-1568x268.png] contiene el carácter [é]. Está codificado de dos maneras: [name="=?utf-8?Q?...?="] (conocida como la codificación RFC 2047) y [filename*=utf-8''...%C3%A9...] (conocida como la codificación RFC 2231). Volveremos a encontrarlas al leer los correos;
  • el último archivo adjunto, de tipo [message/rfc822], es a su vez un correo: el archivo [test-localhost.eml], que también tiene archivos adjuntos.

Por último, veamos dos errores comunes. El archivo [config-smtp-02-errors.json] describe dos envíos a la instancia segura: el primero verifica el certificado del servidor ([verify-peer] en [true]) y el segundo usa una contraseña incorrecta:

{
    "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": []
    }
}

Ejecutemos el script con este archivo de configuración mediante el comando [php smtp-02.php config-smtp-02-errors.json]:

1
2
3
4
5
6
7
> 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
  • primer intento: el certificado autofirmado de [Mailpit] no fue emitido por una autoridad de certificación conocida. La verificación falla y el cliente se niega a continuar; esto es lo que protege a un cliente de la suplantación de un servidor. Con [smtp.gmail.com], cuyo certificado es válido, la verificación tiene éxito;
  • segundo intento: el servidor rechaza la autenticación con el código de error 535.

16.6. Los protocolos POP3 (Post Office Protocol) e IMAP (Internet Message Access Protocol)

16.6.1. Introducción

Hay dos protocolos para leer los correos almacenados en un servidor de correo:

  • el protocolo POP3 (Post Office Protocol), históricamente el primero, pero rara vez utilizado hoy en día;
  • el protocolo IMAP (Internet Message Access Protocol), que es más reciente que POP3 y actualmente el más utilizado.

Para explorar estos protocolos, usaremos la siguiente arquitectura:

Image

  • [Server B] será:
    • para POP3, el servidor POP3 de [Mailpit] (puerto 1110);
    • para IMAP, un servidor IMAP. Podría ser el servidor de Gmail ([imap.gmail.com], puerto 993), usando la cuenta de Gmail y la contraseña de aplicación mencionadas para el protocolo SMTP. Los resultados presentados aquí se obtuvieron con un servidor IMAP local, el servidor de código abierto [Dovecot] (https://www.dovecot.org), que tiene un usuario llamado [guest@localhost] con la contraseña [guest]. Colocamos los correos enviados por nuestros scripts SMTP en el buzón INBOX del usuario. Con Gmail, obtendrá resultados en el mismo formato;
  • [Client A] será un cliente POP3 / IMAP en diversas formas:
    • el cliente [tcp-client.php] para descubrir los protocolos POP3 e IMAP;
    • un script PHP que reproduce el protocolo POP3 descubierto con [tcp-client.php];
    • scripts PHP que utilizan las clases POP3 e IMAP, que escribiremos, seguidas de la biblioteca [zbateson/mail-mime-parser] para analizar los mensajes.

El curso de PHP 7 usaba las funciones [imap_*] de la extensión [imap] de PHP, que admitía tanto IMAP como POP3. Esta extensión, basada en una biblioteca de C abandonada desde hacía años, se eliminó en PHP 8.4. Por lo tanto, vamos a escribir nosotros mismos los clientes POP3 e IMAP que necesitamos, usando las funciones de sockets de PHP. Es una oportunidad para comprender a fondo estos dos protocolos.

16.6.2. Exploración del protocolo POP3

Primero usamos el script [smtp-01.php] para enviar dos correos: uno a [guest@localhost] y el otro a [php8parlexemple@gmail.com] (el tercer intento falla, como vimos). El servidor POP3 de [Mailpit] muestra todos los correos recibidos por [Mailpit] en un único buzón, sin importar sus destinatarios. Para leerlo, debe iniciar sesión con un usuario del archivo [pop3-users.txt], en este caso [guest], con la contraseña [guest].

Veamos cómo acceder a este buzón con el 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]: el servidor POP3 suele utilizar el puerto 110. Aquí, es el puerto 1110 de [Mailpit];
  • [USER guest]: el comando [USER] sirve para especificar el usuario cuyo buzón se desea leer;
  • [PASS guest]: el comando [PASS] sirve para establecer la contraseña del usuario;
  • [LIST]: el comando [LIST] solicita una lista de los mensajes del buzón del usuario. El servidor responde con el número de mensajes y su tamaño total, seguido de una línea [number size] por mensaje;
  • [RETR 1]: el comando [RETR] solicita el mensaje especificado por el número indicado. Se incluyen los encabezados [From], [To] y [Subject], enviados por [smtp-01.php], junto con los encabezados agregados por [Mailpit]. [Mailpit] muestra los mensajes del más reciente al más antiguo: el mensaje n.º 1 es el recibido más recientemente;
  • [DELE 1]: el comando [DELE] marca el mensaje con el número especificado como «por eliminar». El mensaje deja de aparecer en la lista;
  • [QUIT]: el comando [QUIT] le indica al servidor que ha terminado. En ese momento, el servidor elimina los mensajes marcados. Ambos mensajes han desaparecido de la interfaz web de [Mailpit].

La respuesta del servidor puede tomar varias formas:

  • una sola línea que comienza con [+OK] para indicar que el comando anterior del cliente tuvo éxito;
  • una sola línea que comienza con [-ERR] para indicar que el comando anterior del cliente falló;
  • varias líneas en las que:
    • la primera línea comienza con [+OK];
    • la última línea consta de un único punto.

16.6.3. Un script básico que implementa el protocolo POP3

Image

Como el protocolo POP3 tiene la misma estructura que el protocolo SMTP, el script [inet/imap/pop3-01.php] es una adaptación del script [smtp-01.php]. Tiene el siguiente archivo de configuración, [config-pop3-01.json]:

1
2
3
4
5
6
7
8
9
{
    "localhost:1110": {
        "server": "localhost",
        "port": 1110,
        "user": "guest",
        "password": "guest",
        "maxmails": 5
    }
}
  • líneas 3–4: el servidor POP3 consultado es el de [Mailpit];
  • líneas 5–6: el usuario y su contraseña;
  • línea 7: se recuperarán como máximo 5 correos.

El script [pop3-01.php] es el siguiente:

<?php

declare(strict_types=1);

// cliente POP3 (Post Office Protocol) usado para leer los mensajes de un buzón
// protocolo de comunicación cliente-servidor POP3
// -> el cliente se conecta al puerto del servidor POP3 (110, 1110...)
// <- el servidor le envía un mensaje de bienvenida
// -> el cliente envía el comando USER user
// <- el servidor responde OK o no
// -> el cliente envía el comando PASS password
// <- el servidor responde OK o no
// -> el cliente envía el comando LIST
// <- el servidor responde OK o no. Si es OK envía la lista [n.º tamaño] de los mensajes
// -> el cliente envía el comando RETR n.º para cada uno de los mensajes
// <- el servidor responde OK o no. Si es OK envía el contenido del mensaje solicitado
// -> el cliente envía el comando DELE n.º para eliminar un mensaje
// <- el servidor responde OK o no
// -> el cliente envía el comando QUIT para terminar el diálogo con el servidor
// <- el servidor responde OK o no
// las respuestas del servidor tienen la forma +OK texto o -ERR texto
// La respuesta puede tener varias líneas. Entonces la última consta de un solo punto
// las líneas de texto intercambiadas deben terminar con los caracteres CR (13) y LF (10)

// los parámetros para la lectura de los buzones
const CONFIG_FILE_NAME = "config-pop3-01.json";

// recuperamos la configuración
$mailboxes = json_decode(file_get_contents(CONFIG_FILE_NAME), true);

// lectura de los buzones
foreach ($mailboxes as $name => $info) {
    // seguimiento
    print "Reading the mailbox [$name]\n";
    // lectura del buzón
    $result = readmail($info, verbose: true);
    // visualización del resultado
    print "$result\n";
}
// fin
print "Done\n";

// --------------------------------------------------------------------------
function readmail(array $info, bool $verbose = true): string
{
    // lee como máximo $info["maxmails"] mensajes del buzón descrito por [$info]
    // cada mensaje se elimina después de leerse
    // si $verbose=true, hace seguimiento de los intercambios cliente-servidor
    //
    // apertura de una conexión con el 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 {
        // después de la conexión, el servidor envía un mensaje de bienvenida que leemos
        sendCommand($connection, "", $verbose);
        // comando USER
        sendCommand($connection, "USER {$info["user"]}", $verbose);
        // comando PASS
        sendCommand($connection, "PASS {$info["password"]}", $verbose);
        // comando LIST: la 1.ª línea de la respuesta tiene la forma [+OK n messages...]
        $response = sendCommand($connection, "LIST", $verbose, multiline: true);
        preg_match('/^\+OK (\d+)/', $response[0], $fields);
        $nbMessages = (int) ($fields[1] ?? 0);
        // recorremos los mensajes
        for ($i = 1; $i <= min($nbMessages, $info["maxmails"]); $i++) {
            // comando RETR: el mensaje está en las líneas 1 a n-1 de la respuesta
            sendCommand($connection, "RETR $i", $verbose, multiline: true);
            // comando DELE
            sendCommand($connection, "DELE $i", $verbose);
        }
        // comando QUIT: es el que elimina los mensajes marcados por DELE
        sendCommand($connection, "QUIT", $verbose);
        return "Reading done";
    } catch (RuntimeException $ex) {
        // el servidor señaló un error
        return "Error: " . $ex->getMessage();
    } finally {
        // en todos los casos, cerramos la conexión
        fclose($connection);
    }
}

// --------------------------------------------------------------------------
function sendCommand($connection, string $command, bool $verbose, bool $multiline = false): array
{
    // envía $command al canal $connection y devuelve las líneas de la respuesta
    // modo detallado si $verbose=true
    // si $multiline=true, la respuesta termina con una línea reducida a un punto
    // lanza una RuntimeException si el servidor señala un error
    //
    // envío del comando si no está vacío
    if ($command !== "") {
        fwrite($connection, "$command\r\n");
        if ($verbose) {
            display($command, 1);
        }
    }
    // lectura de la 1.ª línea de la respuesta
    $line = readServerLine($connection, $verbose);
    // ¿error?
    if (str_starts_with($line, "-ERR")) {
        throw new RuntimeException(substr($line, 5));
    }
    $response = [$line];
    // ¿respuesta de varias líneas?
    if ($multiline) {
        while (($line = readServerLine($connection, $verbose)) !== ".") {
            // se envió una línea del mensaje que empieza con un punto
            // con un punto adicional: lo eliminamos
            $response[] = str_starts_with($line, "..") ? substr($line, 1) : $line;
        }
    }
    return $response;
}

// --------------------------------------------------------------------------
function readServerLine($connection, bool $verbose): string
{
    // lee una línea enviada por el servidor y la devuelve sin los 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
{
    // muestra $exchange en pantalla
    // si $direction=1 muestra → [$exchange]
    // si $direction=2 muestra ← [$exchange]
    print match ($direction) {
        1 => "--> [$exchange]\n",
        2 => "<-- [$exchange]\n",
    };
}

Comentarios

Como mencionamos, [pop3-01.php] es una adaptación del script [smtp-01.php] que ya analizamos. Solo comentaremos las principales diferencias:

  • línea 44: la función [readmail] se encarga de leer los correos del buzón. La información de inicio de sesión de este buzón se almacena en el diccionario [$info];
  • línea 51: establece una conexión con el servidor POP3;
  • línea 57: lee el mensaje de bienvenida enviado por el servidor;
  • líneas 59–61: se envían los comandos [USER] y [PASS] para identificar al usuario cuyos correos se desean;
  • líneas 63–65: se envía el comando [LIST] para determinar cuántos correos hay en el buzón. La función [sendCommand] ahora devuelve las líneas de la respuesta. En la primera línea de su respuesta al comando LIST, el servidor indica cuántos mensajes hay. Esto se obtiene mediante una expresión regular. [$fields[1] ?? 0] devuelve 0 si la expresión regular no encontró nada;
  • líneas 67–71: recorremos los mensajes. Para cada uno, enviamos dos comandos:
    • RETR i: para recuperar el mensaje n.º i;
    • DELE i: para eliminarlo una vez leído;
  • línea 74: se envía el comando [QUIT] para indicarle al servidor que hemos terminado;
  • línea 86: el parámetro [$multiline] indica si la respuesta esperada tiene varias líneas, la última de las cuales consta de un único punto. Es el caso de los comandos [LIST] y [RETR]. Un error se indica mediante una primera línea que comienza con [-ERR] (función [str_starts_with] de PHP 8.0);
  • líneas 110–112: al igual que con SMTP, el servidor duplica el punto al comienzo de una línea del mensaje. El cliente debe eliminar ese punto adicional.

Enviamos dos correos más con [smtp-01.php] y luego ejecutamos [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

Aquí tenemos un cliente POP3 básico al que le faltan ciertas capacidades:

  • la capacidad de comunicarse con un servidor seguro;
  • la capacidad de leer los archivos adjuntos de los mensajes.

Antes de agregar estas funcionalidades, exploremos el protocolo IMAP.

16.6.4. Exploración del protocolo IMAP

El protocolo IMAP es más rico en funcionalidades que el protocolo POP3. El servidor administra varios buzones por usuario (INBOX, Sent, Trash, etc.) y hace seguimiento del estado de los mensajes: leído, respondido, por eliminar... Estos estados se denominan indicadores (flags). Lo más importante es que el cliente puede solicitar al servidor la estructura de un mensaje y descargar solo una parte de él.

Cada comando del cliente va precedido de una etiqueta elegida por el cliente, por ejemplo, [A1]. El servidor responde con líneas que comienzan con un asterisco [*], seguidas de una línea que comienza con la etiqueta del comando, seguida de [OK] (éxito), [NO] (fallo) o [BAD] (comando no válido).

Los servidores IMAP públicos aceptan únicamente conexiones cifradas en el puerto 993 desde el momento en que se inician. Con Gmail, se iniciaría el cliente TCP con la opción [--tls]: [php tcp-client.php --tls --quit bye imap.gmail.com 993]. Nuestro servidor local también acepta conexiones sin cifrar en el puerto estándar 143, lo cual es útil para el descubrimiento. Enviamos dos correos con el script [smtp-02.php] (configuración [config-smtp-02.json]) y fueron entregados en el buzón INBOX del usuario [guest@localhost]. Este es un diálogo con el 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]: el comando [LOGIN user password] autentica al usuario. El servidor responde con una lista de las capacidades del usuario (CAPABILITY);
  • [A2 SELECT INBOX]: el comando [SELECT] selecciona el buzón al que se aplicarán los comandos siguientes. El servidor enumera los indicadores disponibles (FLAGS), el número de mensajes (2 EXISTS) y el número del primer mensaje no leído (UNSEEN 1)...;
  • [A3 SEARCH UNSEEN]: el comando [SEARCH] busca mensajes según un criterio. Hay unos veinte criterios de este tipo. Aquí buscamos los mensajes que todavía no se han leído (UNSEEN). El servidor devuelve sus números: 1 y 2;
  • [A4 FETCH 2 (...)]: el comando [FETCH] solicita información sobre un mensaje. Aquí recupera los indicadores del mensaje (FLAGS), su tamaño (RFC822.SIZE) y cuatro de sus encabezados. El formato [BODY.PEEK[...]] solicita una parte del mensaje sin marcarlo como leído. El texto de los encabezados se envía como un literal: [{114}] al final de la línea indica que los siguientes 114 bytes forman parte de la respuesta, sin importar su contenido (incluidos los saltos de línea). La respuesta termina con un paréntesis de cierre después del literal;
  • [A5 FETCH 2 BODY.PEEK[1.1]]: se solicita la parte 1.1 del mensaje n.º 2; aquí, su texto es [text/plain]. Pronto veremos cómo se numeran las partes de un mensaje;
  • [A6 FETCH 1 BODYSTRUCTURE]: solicitamos la estructura del mensaje n.º 1, el que tiene cinco archivos adjuntos. La respuesta es una lista de listas entre paréntesis. Podemos reconocer las partes del mensaje que vimos en [Mailpit]: una lista [(("text" "plain" ...)("text" "html" ...) "alternative" ...)] para la parte [multipart/alternative], seguida de una lista por cada archivo adjunto, con su tipo, parámetros (nombre), codificación (base64), tamaño y disposición («attachment» con el nombre del archivo). La estructura termina con el subtipo [mixed] del mensaje completo;
  • [A7 LOGOUT]: el fin del diálogo.

16.6.5. Clases para los protocolos POP3 e IMAP

Nuestros scripts de lectura de correos usarán indistintamente un servidor POP3 o un servidor IMAP. Por lo tanto, escribiremos:

  • una interfaz [MailClient] que describe lo que puede hacer un cliente de correo;
  • una clase abstracta [TcpClient] que agrupa lo que es común a ambos protocolos: una conexión TCP, que puede estar cifrada, por la que se intercambian líneas de texto;
  • dos clases, [Pop3Client] e [ImapClient], que heredan de [TcpClient] e implementan la interfaz [MailClient];
  • una clase llamada [MimePart] que describe la estructura de un mensaje, obtenida mediante el comando IMAP [BODYSTRUCTURE].

Se encuentran en la carpeta [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. La interfaz [MailClient]

<?php

declare(strict_types=1);

// lo que puede hacer un cliente de lectura de correo, ya sea que hable POP3 o IMAP
// los mensajes se designan por su número (1, 2...) en el buzón
interface MailClient
{
    // conexión y autenticación - devuelve el número de mensajes del buzón
    public function connect(): int;

    // los números de los mensajes no leídos
    public function unread(): array;

    // los encabezados principales del mensaje n.º $n (Date, From, To, Subject...)
    public function headers(int $n): array;

    // el texto completo del mensaje n.º $n (encabezados y cuerpo)
    public function message(int $n): string;

    // marca el mensaje n.º $n como "por eliminar"
    public function delete(int $n): void;

    // elimina los mensajes marcados y cierra la conexión
    public function close(): void;
}
  • línea 10: conexión al servidor y autenticación del usuario. El método devuelve el número de mensajes del buzón;
  • línea 13: los números de los mensajes no leídos;
  • línea 16: los principales encabezados de un mensaje, en forma de diccionario;
  • línea 19: el texto completo de un mensaje, es decir, lo que vimos en la pestaña [Raw] de [Mailpit];
  • línea 22: marca un mensaje como «por eliminar»;
  • línea 25: elimina los mensajes marcados y cierra la conexión.

16.6.5.2. La clase [TcpClient]

<?php

declare(strict_types=1);

// clase base de los clientes POP3 e IMAP: una conexión TCP, posiblemente
// cifrada (TLS), por la que se intercambian líneas de texto terminadas en \r\n
abstract class TcpClient
{
    // la conexión con el servidor (un recurso de tipo stream)
    protected mixed $connection = null;

    // $info: la configuración del servidor (server, port, tls, verify-peer, user, password...)
    // $tracking: si es true, los intercambios cliente / servidor se muestran en la consola
    public function __construct(protected readonly array $info, protected readonly bool $tracking = false)
    {
    }

    // apertura de la conexión con el servidor
    protected function openConnection(): void
    {
        // ¿conexión cifrada desde su apertura (tls://) o no (tcp://)?
        $transport = ($this->info["tls"] ?? false) ? "tls" : "tcp";
        // ¿se debe verificar el certificado del servidor? (sí por defecto)
        $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;
    }

    // envío de una línea al servidor - $display: lo que se debe mostrar en modo de seguimiento
    protected function send(string $line, ?string $display = null): void
    {
        fwrite($this->connection, "$line\r\n");
        $this->display("--> " . ($display ?? $line));
    }

    // lectura de una línea enviada por el servidor, devuelta sin los caracteres \r\n
    // $display: ¿se debe mostrar la línea en modo de seguimiento?
    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;
    }

    // lectura de $nbBytes bytes enviados por el 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;
    }

    // cierre de la conexión
    protected function closeConnection(): void
    {
        if ($this->connection !== null) {
            fclose($this->connection);
            $this->connection = null;
        }
    }

    // se muestra en modo de seguimiento
    protected function display(string $message): void
    {
        if ($this->tracking) {
            print "$message\n";
        }
    }

    // análisis de los encabezados de un mensaje: devuelve el diccionario [nombre => valor] de los
    // encabezados decodificados (los encabezados no ASCII están codificados, por ejemplo =?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;
    }
}
  • línea 7: la clase es abstracta; no puede instanciarse. Sirve como clase padre de las clases [Pop3Client] e [ImapClient];
  • línea 10: la conexión al servidor. Las funciones de PHP la representan como un recurso, un tipo que no se puede declarar en PHP: se utiliza el tipo [mixed];
  • línea 14: el constructor usa la promoción de parámetros (PHP 8.0): los parámetros [$info] y [$tracking] se convierten en propiedades de la clase, en este caso de solo lectura ([readonly], PHP 8.1). El cuerpo del constructor está vacío. [$info] es la configuración del servidor, leída de un archivo JSON. [$tracking] solicita que se muestren los intercambios cliente/servidor;
  • líneas 19–32: establecimiento de la conexión. Si la configuración contiene [tls: true], la conexión se cifra en cuanto se establece (transporte [tls://]). El contexto especifica si se debe verificar el certificado del servidor (entrada [verify-peer], true de forma predeterminada);
  • línea 36: envío de una línea al servidor. El parámetro [$display] permite mostrar algo distinto de lo que se envía: lo usaremos para ocultar las contraseñas;
  • línea 44: lectura de una línea. Si el servidor ha cerrado la conexión, se lanza una excepción;
  • línea 58: lee un número determinado de bytes. Lo usaremos para los literales de IMAP. La función [fread] puede devolver menos bytes de los solicitados: iteramos hasta haber recibido todo;
  • línea 91: la función [iconv_mime_decode_headers] analiza un bloque de encabezados de correo y devuelve el diccionario [name => value]. Concatena los encabezados distribuidos en varias líneas y decodifica los encabezados codificados (=?utf-8?Q?...?=).

16.6.5.3. La clase [Pop3Client]

<?php

declare(strict_types=1);

require_once __DIR__ . "/TcpClient.php";
require_once __DIR__ . "/MailClient.php";

// cliente POP3: los comandos USER, PASS, STAT, TOP, LIST, RETR, DELE, QUIT
final class Pop3Client extends TcpClient implements MailClient
{
    // número de mensajes del buzón
    private int $nbMessages = 0;

    #[\Override]
    public function connect(): int
    {
        $this->openConnection();
        // mensaje de bienvenida del servidor
        $this->command("");
        // autenticación
        $this->command("USER {$this->info["user"]}");
        $this->command("PASS {$this->info["password"]}", "PASS *****");
        // STAT: la respuesta tiene la forma [+OK nbMessages totalSize]
        $response = $this->command("STAT");
        $this->nbMessages = (int) explode(" ", $response[0])[1];
        return $this->nbMessages;
    }

    #[\Override]
    public function unread(): array
    {
        // POP3 no recuerda los mensajes leídos: todos los mensajes presentes son nuevos
        return $this->nbMessages === 0 ? [] : range(1, $this->nbMessages);
    }

    #[\Override]
    public function headers(int $n): array
    {
        // TOP n 0: los encabezados del mensaje n.º n seguidos de 0 líneas del cuerpo
        $lines = $this->command("TOP $n 0", multiline: true);
        $headers = self::parseHeaders(implode("\r\n", array_slice($lines, 1)));
        // LIST n: la respuesta tiene la forma [+OK n size]
        $response = $this->command("LIST $n");
        // solo conservamos los encabezados principales
        $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: la 1.ª línea de la respuesta es [+OK...], las siguientes son el mensaje
        $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 que hacer si no se pudo abrir la conexión
        if ($this->connection === null) {
            return;
        }
        try {
            // es el comando QUIT el que elimina los mensajes marcados con DELE
            $this->command("QUIT");
        } finally {
            $this->closeConnection();
        }
    }

    // envía un comando al servidor (si no está vacío) y devuelve las líneas de la respuesta
    // $multiline: ¿la respuesta termina con una línea que contiene solo un punto?
    private function command(string $command, ?string $display = null, bool $multiline = false): array
    {
        if ($command !== "") {
            $this->send($command, $display);
        }
        // 1.ª línea: +OK o -ERR
        $line = $this->readLine();
        if (str_starts_with($line, "-ERR")) {
            throw new RuntimeException("[" . ($display ?? $command) . "]: $line");
        }
        $response = [$line];
        if ($multiline) {
            // las líneas siguientes, hasta la línea [.], no se muestran en modo de seguimiento
            while (($line = $this->readLine(false)) !== ".") {
                // el servidor duplica el punto con el que empieza una línea: lo quitamos
                $response[] = str_starts_with($line, "..") ? substr($line, 1) : $line;
            }
            $this->display("<-- ... " . (count($response) - 1) . " lines ...");
            $this->display("<-- .");
        }
        return $response;
    }
}
  • línea 9: la clase hereda de [TcpClient] e implementa [MailClient]. Se declara como [final]: no se pueden derivar clases de ella;
  • línea 14: el atributo [#[\Override]] (PHP 8.3) indica que el método implementa un método de una interfaz o sobrescribe un método de una clase padre. Si no es así (por ejemplo, por un error de escritura en el nombre), PHP informa un error;
  • líneas 15–26: la conexión. Aquí están presentes los comandos de [pop3-01.php]. El comando [STAT] devuelve en una sola línea el número de mensajes y su tamaño total. La contraseña se muestra en la forma [*****];
  • líneas 30–33: el protocolo POP3 no lleva el registro de los mensajes leídos; todos los mensajes se tratan como nuevos. La función [range(1, n)] devuelve el arreglo [1, 2, ..., n];
  • líneas 37–46: el comando [TOP n 0] devuelve los encabezados del mensaje n.º n seguidos de 0 líneas de su cuerpo. El comando [LIST n] devuelve su tamaño. La función [array_intersect_key] conserva solo los encabezados cuyos nombres son claves del arreglo devuelto por [array_flip]. El operador [...] copia estos encabezados en el arreglo devuelto, al que se agrega el tamaño;
  • líneas 50–54: el comando [RETR n] devuelve el mensaje n.º n;
  • líneas 64–74: el comando [QUIT] elimina los mensajes marcados por el comando [DELE]. La conexión se cierra en todos los casos (bloque [finally]);
  • línea 80: el método [command] es la función [sendCommand] de [pop3-01.php]. En el modo de seguimiento, las líneas de una respuesta de varias líneas no se muestran; solo se muestra su número.

16.6.5.4. La clase [ImapClient]

<?php

declare(strict_types=1);

require_once __DIR__ . "/TcpClient.php";
require_once __DIR__ . "/MailClient.php";
require_once __DIR__ . "/MimePart.php";

// cliente IMAP: los comandos LOGIN, SELECT, SEARCH, FETCH, STORE, EXPUNGE, LOGOUT
// cada comando va precedido de una etiqueta (A0001, A0002...); el servidor envía
// respuestas [* ...] y termina con una respuesta [tag OK|NO|BAD ...]
final class ImapClient extends TcpClient implements MailClient
{
    // número del último comando enviado (sirve para construir las etiquetas)
    private int $number = 0;
    // ¿hay mensajes marcados como "por eliminar"?
    private bool $deletions = false;

    #[\Override]
    public function connect(): int
    {
        $this->openConnection();
        // mensaje de bienvenida del servidor: [* OK ...]
        [$welcome] = $this->readResponse();
        if (!str_starts_with($welcome, "* OK")) {
            throw new RuntimeException("the server refuses the connection: $welcome");
        }
        // autenticación
        $this->command("LOGIN " . self::quote($this->info["user"]) . " " . self::quote($this->info["password"]),
            "LOGIN " . self::quote($this->info["user"]) . " *****");
        // selección del buzón: una de las respuestas tiene la 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
    {
        // la respuesta tiene la 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]: los encabezados del mensaje, sin marcarlo como leído
        $data = $this->fetch($n, "(FLAGS RFC822.SIZE BODY.PEEK[HEADER])");
        $headers = self::parseHeaders($data["BODY[HEADER]"]);
        // solo conservamos los encabezados principales
        $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[]: el mensaje completo; el servidor lo marca como leído (indicador \Seen)
        return $this->fetch($n, "BODY[]")["BODY[]"];
    }

    // la estructura MIME del mensaje n.º $n
    public function structure(int $n): MimePart
    {
        return MimePart::fromBodyStructure($this->fetch($n, "BODYSTRUCTURE")["BODYSTRUCTURE"]);
    }

    // el contenido (codificado) de la parte n.º $section (1, 1.2...) del mensaje 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
    {
        // agregamos el indicador \Deleted al mensaje
        $this->command("STORE $n +FLAGS (\\Deleted)");
        $this->deletions = true;
    }

    #[\Override]
    public function close(): void
    {
        // nada que hacer si no se pudo abrir la conexión
        if ($this->connection === null) {
            return;
        }
        try {
            // EXPUNGE elimina los mensajes que tienen el indicador \Deleted
            if ($this->deletions) {
                $this->command("EXPUNGE");
            }
            $this->command("LOGOUT");
        } finally {
            $this->closeConnection();
        }
    }

    // comando FETCH n items: devuelve el diccionario [item => valor] de la respuesta
    // [* 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;
    }

    // envía un comando con etiqueta y devuelve sus respuestas [* ...], cada una dividida en tokens
    // $display: lo que se debe mostrar en modo de seguimiento (para ocultar una contraseña)
    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();
            // ¿respuesta 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;
            }
            // respuesta [* ...]
            if (str_starts_with($text, "* ")) {
                $position = 2;
                $responses[] = self::tokens($text, $position, $literals);
            }
        }
    }

    // lee una respuesta del servidor: una línea que puede contener literales. Un literal
    // se anuncia con {n} al final de la línea: siguen n bytes y luego el resto de la línea.
    // devuelve el texto de la respuesta, donde el literal n.º k se reemplaza por \0k\0, y los literales
    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 en tokens desde la posición $position, hasta el final del texto o
    // hasta un paréntesis de cierre. Una lista (...) se convierte en un arreglo, NIL en null,
    // una cadena "..." o un literal en una cadena, y todo lo demás (átomo) también
    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 === "(") {
                // una lista: llamada recursiva
                $position++;
                $tokens[] = self::tokens($text, $position, $literals);
            } elseif ($c === ")") {
                // fin de la lista actual
                $position++;
                return $tokens;
            } elseif ($c === '"') {
                // una cadena entre comillas donde \" y \\ representan " y \
                $string = "";
                for ($position++; $text[$position] !== '"'; $position++) {
                    if ($text[$position] === "\\") {
                        $position++;
                    }
                    $string .= $text[$position];
                }
                $position++;
                $tokens[] = $string;
            } elseif ($c === "\0") {
                // un literal
                $end = strpos($text, "\0", $position + 1);
                $tokens[] = $literals[(int) substr($text, $position + 1, $end - $position - 1)];
                $position = $end + 1;
            } else {
                // un átomo: hasta el siguiente espacio o paréntesis, excepto dentro de corchetes
                // (BODY[HEADER.FIELDS (FROM TO)] es un solo á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;
    }

    // una cadena IMAP: entre comillas, con \ antes de los caracteres " y \
    private static function quote(string $text): string
    {
        return '"' . addcslashes($text, '"\\') . '"';
    }
}
  • línea 15: el número del último comando. Se utiliza para generar las etiquetas [A0001], [A0002]...;
  • líneas 20–34: la conexión. El servidor envía primero un mensaje de bienvenida: [* OK ...]. Luego se envían los comandos [LOGIN] y [SELECT] . El método [command] devuelve las respuestas del servidor [* ...], cada una dividida en tokens: la respuesta [* 2 EXISTS] se convierte en el arreglo [["2", "EXISTS"]]. La función [array_find] (PHP 8.4) devuelve el primer elemento del arreglo que cumple la condición, o [null];
  • líneas 38–43: el comando [SEARCH UNSEEN]. El resultado [* SEARCH 1 2] se convierte en [["SEARCH", "1", "2"]]. Conservamos los elementos a partir del número 1 ([array_slice]), que se convierten en enteros mediante la función [intval]. La notación [intval(...)] (PHP 8.1) crea una función a partir de la función [intval]: es la sintaxis de los first-class callables;
  • líneas 47–54: el comando [FETCH n (FLAGS RFC822.SIZE BODY.PEEK[HEADER])] devuelve los indicadores, el tamaño y los encabezados del mensaje n.º n;
  • líneas 58–61: el comando [FETCH n BODY[]] devuelve el mensaje n.º n completo. El servidor le agrega el indicador [\Seen]: el mensaje queda ahora marcado como leído;
  • líneas 65–67: el comando [FETCH n BODYSTRUCTURE] devuelve la estructura del mensaje, que la clase [MimePart] transforma en un árbol de objetos;
  • líneas 71–73: el comando [FETCH n BODY[section]] devuelve el contenido de la parte n.º [section] del mensaje, tal como está codificado en el mensaje (Base64, quoted-printable, etc.);
  • líneas 77–81: el comando [STORE n +FLAGS (\Deleted)] agrega el indicador [\Deleted] al mensaje. Todavía no se ha eliminado;
  • líneas 85–98: el comando [EXPUNGE] elimina los mensajes que tienen el indicador [\Deleted]. El comando [LOGOUT] pone fin al diálogo;
  • líneas 104–115: el método [fetch] envía un comando [FETCH] y convierte la lista de respuesta [[* n FETCH (item1 value1 item2 value2...)]] en un diccionario [[item1 => value1, item2 => value2...]]. La función [array_chunk] divide la lista en pares, que el bucle [foreach] desempaqueta en [[$key, $value]];
  • líneas 120–133: el método [command] envía un comando precedido de su etiqueta y luego lee las respuestas del servidor hasta encontrar la que comienza con la etiqueta. Si esta última respuesta no es [OK], se lanza una excepción;
  • líneas 146–153: lectura de una respuesta. Si una línea termina con [{n}], le siguen n bytes (el literal) y luego el resto de la respuesta. En el texto de la respuesta, cada literal se reemplaza por un marcador [\0k\0] (\0 es el carácter con código 0, que no puede aparecer en una línea de texto IMAP) y su contenido se almacena en el arreglo [$literals];
  • líneas 163–209: el método [tokens] divide el texto de una respuesta en tokens:
    • una lista encerrada entre paréntesis se convierte en un arreglo. El método se llama a sí mismo (llamada recursiva) para analizar el contenido de la lista y devuelve el control al llegar al paréntesis de cierre;
    • una cadena encerrada entre comillas o un literal se convierte en una cadena;
    • [NIL] se convierte en [null];
    • todo lo demás (un átomo) se convierte en una cadena. Un átomo puede contener corchetes, que a su vez pueden contener espacios y paréntesis: [BODY[HEADER.FIELDS (FROM TO)]] es un único átomo. La expresión [match] suma 1 al contador de corchetes abiertos con [[] y le resta 1 con []];
    • El parámetro [$position], pasado por referencia, es la posición actual en el texto: avanza a medida que progresa el análisis, incluso dentro de las llamadas recursivas;
  • Línea 213: una cadena IMAP se encierra entre comillas. La función [addcslashes] antepone un carácter [\] a los caracteres ["] y [\].

16.6.5.5. La clase [MimePart]

<?php

declare(strict_types=1);

// una parte de un mensaje MIME, tal como la describe la respuesta BODYSTRUCTURE de un servidor IMAP
// un mensaje es un árbol de partes: una parte [multipart/xxx] tiene subpartes
final readonly class MimePart
{
    public function __construct(
        // tipo y subtipo MIME en minúsculas: text/plain, multipart/mixed, application/pdf...
        public string $type,
        public string $subType,
        // parámetros del tipo, por ejemplo [charset => utf-8]
        public array $parameters = [],
        // codificación del contenido: 7bit, 8bit, base64, quoted-printable...
        public string $encoding = "7bit",
        // disposición (attachment, inline) o null, y sus parámetros, por ejemplo [filename => x.pdf]
        public ?string $disposition = null,
        public array $dispositionParameters = [],
        // las subpartes de una parte [multipart/xxx]
        public array $parts = [],
    ) {
    }

    // construye el árbol de partes a partir de la lista de tokens de BODYSTRUCTURE
    public static function fromBodyStructure(array $structure): self
    {
        // parte múltiple: ((subparte 1) (subparte 2)... "subtipo" (parámetros) disposición...)
        if (is_array($structure[0])) {
            // las subpartes son los primeros elementos que son 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 simple: ("tipo" "subtipo" (parámetros) id descripción "codificación" tamaño ...)
        $type = strtolower($structure[0]);
        $subType = strtolower($structure[1]);
        // la disposición viene después de campos que dependen del tipo de la parte
        $dispositionIndex = match (true) {
            // text/xxx: ... tamaño nbLines md5 disposición
            $type === "text" => 9,
            // message/rfc822: ... tamaño envelope estructura nbLines md5 disposición
            $type === "message" && $subType === "rfc822" => 11,
            // otros: ... tamaño md5 disposición
            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,
        );
    }

    // el nombre de archivo de un adjunto, o null
    public function fileName(): ?string
    {
        // el nombre es el parámetro [filename] de la disposición o, en su defecto, el parámetro [name]
        // del tipo. Puede estar codificado de dos maneras:
        // - 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) {
            // juego de caracteres''nombre codificado como 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");
    }

    // una lista IMAP (key1 value1 key2 value2...) o NIL convertida en diccionario
    private static function dictionary(?array $list): array
    {
        $dictionary = [];
        foreach (array_chunk($list ?? [], 2) as [$key, $value]) {
            $dictionary[strtolower($key)] = $value;
        }
        return $dictionary;
    }

    // una disposición IMAP ("attachment" (parámetros)) o NIL: devuelve [disposición, parámetros]
    private static function disposition(mixed $disposition): array
    {
        if (!is_array($disposition)) {
            return [null, []];
        }
        return [strtolower($disposition[0]), self::dictionary($disposition[1] ?? null)];
    }
}
  • línea 7: una clase [readonly] (PHP 8.2) tiene únicamente propiedades de solo lectura: una vez construido, un objeto [MimePart] ya no puede modificarse;
  • Líneas 9–22: todas las propiedades se declaran mediante la promoción de los parámetros del constructor. Tienen valores predeterminados, lo que permite pasar solo algunos parámetros por nombre (argumentos con nombre);
  • línea 26: el método estático [fromBodyStructure] construye el árbol de partes a partir de la lista de tokens de la respuesta [BODYSTRUCTURE];
  • líneas 29–42: una parte múltiple comienza con las listas de sus subpartes, cada una de las cuales se convierte en un objeto [MimePart] mediante una llamada recursiva. Luego vienen su subtipo (mixed, alternative, etc.), sus parámetros (boundary) y su disposición;
  • líneas 45–57: una parte simple comienza con su tipo, subtipo, parámetros, un identificador, una descripción, su codificación y su tamaño. La posición de la disposición depende del tipo de la parte: una parte [text/xxx] incluye además un número de líneas; una parte [message/rfc822] incluye además el sobre y la estructura del mensaje, así como un número de líneas. La expresión [match (true)] selecciona la primera rama cuya condición es verdadera;
  • líneas 69–82: el nombre de archivo de un adjunto. Vimos en [Mailpit] que puede codificarse de dos maneras:
    • la codificación RFC 2231 [utf-8''Tah%C3%A9.png]: el juego de caracteres, dos apóstrofes y luego el nombre codificado como en una URL. Se decodifica con [rawurldecode] y luego se convierte a UTF-8 con [mb_convert_encoding];
    • la codificación RFC 2047 [=?utf-8?Q?Tah=C3=A9.png?=]: se decodifica con la función [iconv_mime_decode];
  • Línea 86: una lista IMAP [("charset" "utf-8")] se convierte en el diccionario [["charset" => "utf-8"]];
  • línea 96: una disposición [("attachment" ("filename" "x.pdf"))] se convierte en el arreglo [["attachment", ["filename" => "x.pdf"]]].

16.6.6. Cliente POP3 / IMAP [imap-01.php]

El script [imap-01.php] cumple la misma función que el script del mismo nombre del curso de PHP 7, que utilizaba las funciones [imap_open], [imap_num_msg], [imap_search], [imap_headerinfo], [imap_body], [imap_delete], [imap_expunge] e [imap_close]. Utiliza el siguiente archivo 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"
    }
}

El archivo [config-imap-01.json] define un diccionario de servidores IMAP / POP3 con los que se establecerá contacto. Cada entrada tiene la forma [key => value], donde:

  • [key]: es un nombre que designa al servidor. Aquí tenemos tres:
    • [imap.gmail.com:993]: el servidor IMAP de Gmail, que escucha en el puerto 993 con una conexión cifrada. Está deshabilitado ([enabled] con valor [false]): ingrese allí su dirección de Gmail y su contraseña de aplicación, y luego cambie [enabled] a [true];
    • [localhost:993]: el servidor IMAP local, con una conexión cifrada mediante un certificado autofirmado, que no se verifica;
    • [localhost:1110]: el servidor POP3 de [Mailpit];
  • [value]: es un diccionario que especifica los siguientes puntos:
    • [protocol]: el protocolo, [imap] o [pop3];
    • [server]: el nombre del servidor, IMAP o POP3;
    • [port]: el puerto del servidor (IMAP o POP3);
    • [tls]: ¿la conexión está cifrada?
    • [verify-peer]: ¿debe verificarse el certificado del servidor? En Windows, si la verificación falla con un servidor público, compruebe que la directiva [openssl.cafile] del archivo [php.ini] apunte a un archivo de autoridades de certificación, como lo hace [Laragon];
    • [user]: el propietario del buzón;
    • [password]: la contraseña del propietario del buzón;
    • [mailbox]: el buzón IMAP que se va a leer, donde INBOX es aquel en el que llegan los mensajes nuevos;
    • [output-dir]: la carpeta donde deben guardarse los mensajes.

Con el protocolo POP3, después de leer un mensaje, este se elimina. Así funcionan normalmente los servidores POP3: un mensaje leído no se conserva en el servidor.

El script [imap-01.php] es el siguiente:

<?php

declare(strict_types=1);

// cliente IMAP (Internet Message Access Protocol) / POP3 usado para leer correos
// los buzones que se deben leer se describen en un archivo de configuración

require_once __DIR__ . "/ImapClient.php";
require_once __DIR__ . "/Pop3Client.php";

// los parámetros para leer el correo
const CONFIG_FILE_NAME = "config-imap-01.json";
// ¿mostrar los intercambios cliente / servidor?
const TRACKING = false;

// recuperamos la configuración
$mailboxes = json_decode(file_get_contents(CONFIG_FILE_NAME), true);

// lectura de los buzones
foreach ($mailboxes as $name => $info) {
    // ¿buzón deshabilitado en la configuración?
    if (($info["enabled"] ?? true) === false) {
        print "------------Mailbox [$name] disabled\n";
        continue;
    }
    // seguimiento
    print "------------Reading the mailbox [$name]\n";
    // lectura del buzón
    readmailbox($name, $info);
}
// fin
print "Done\n";

// --------------------------------------------------------------------------
function createClient(array $info): MailClient
{
    // un cliente IMAP o POP3 según la configuración
    return match ($info["protocol"]) {
        "imap" => new ImapClient($info, TRACKING),
        "pop3" => new Pop3Client($info, TRACKING),
    };
}

// --------------------------------------------------------------------------
function readmailbox(string $name, array $info): void
{
    // el cliente del buzón
    $client = createClient($info);
    try {
        // conexión
        $nbmsg = $client->connect();
        print "Connection established with the server [$name].\n";
        // total de mensajes del buzón
        print "There are [$nbmsg] messages in the mailbox [$name]\n";
        if ($nbmsg === 0) {
            return;
        }
        // mensajes no leídos del buzón
        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 los encabezados del mensaje n.º $msgNumber
            print "Headers of the message no. [$msgNumber] of the mailbox [$name]\n";
            print_r($client->headers($msgNumber));
            // recuperamos el texto completo del mensaje n.º $msgNumber y lo guardamos
            saveMessage($client->message($msgNumber), $msgNumber, $info);
            // si el protocolo es POP3, eliminamos el mensaje
            if ($info["protocol"] === "pop3") {
                $client->delete($msgNumber);
            }
        }
    } catch (RuntimeException $ex) {
        print "Error: " . $ex->getMessage() . "\n";
    } finally {
        // en todos los casos, cerramos la conexión
        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
{
    // el mensaje se guarda en el archivo [output-dir/message-N.eml]
    $fileName = "{$info["output-dir"]}/message-$msgNumber.eml";
    print "Saving the message in the file [$fileName]\n";
    // creamos la carpeta si es necesario (true: con sus carpetas padre)
    if (!is_dir($info["output-dir"])) {
        mkdir($info["output-dir"], recursive: true);
    }
    // guardamos el mensaje
    if (file_put_contents($fileName, $message) === false) {
        print "Saving failed\n";
    }
}

Comentarios:

  • líneas 8–9: se cargan las clases de ambos clientes, que a su vez cargan la clase [TcpClient] y la interfaz [MailClient];
  • Línea 14: con el valor [true], se muestran los intercambios cliente/servidor. Pruébelo;
  • líneas 20–29: se recorren todos los servidores del archivo de configuración, excepto los que están deshabilitados;
  • líneas 35–41: la función [createClient] devuelve un cliente IMAP o POP3, según la configuración. Su tipo de retorno es la interfaz [MailClient]: el resto del script no sabe con qué protocolo está tratando. Esto es polimorfismo;
  • línea 51: conexión y autenticación;
  • línea 60: el número de mensajes no leídos;
  • línea 68: los encabezados del mensaje se muestran con la función [print_r];
  • línea 70: el texto completo del mensaje se guarda en un archivo;
  • línea 72: con el protocolo POP3, el mensaje se marca para su eliminación;
  • líneas 78–86: en todos los casos se cierra la conexión, lo que elimina los mensajes marcados. Si se ejecutan las instrucciones [return] del bloque [try], el bloque [finally] también se ejecuta;
  • línea 97: la función [mkdir] crea la carpeta, junto con sus carpetas superiores, mediante el argumento con nombre [recursive: true].

Ejecutemos el script [smtp-02.php] para que el usuario [guest@localhost] tenga mensajes nuevos. Una vez hecho esto, ejecutemos el script [imap-01.php] para leer los buzones. La salida de la consola es la siguiente:

> 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
  • Con IMAP, se leen los dos mensajes depositados en el buzón INBOX. Los indicadores [Flags] están vacíos: los mensajes aún no se han leído;
  • con POP3, encontramos los mismos mensajes en el buzón de [Mailpit], en orden inverso. Los mensajes leídos se eliminan.

Si volvemos a ejecutar de inmediato el script [imap-01.php], los resultados son los siguientes:

> 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
  • En el buzón IMAP siguen estando la misma cantidad de mensajes, pero ya no hay mensajes no leídos. Esto demuestra que la ejecución anterior cambió el estado de los mensajes leídos de «no leído» a «leído» (indicador [\Seen]);
  • Ya no hay mensajes en la bandeja de entrada POP3: se eliminaron durante la ejecución anterior.

Los mensajes se guardaron localmente en las carpetas [output/localhost-imap] y [output/localhost-pop3] , con los nombres [message-1.eml] y [message-2.eml]. La extensión de archivo [.eml] se utiliza para los archivos de correo electrónico: al hacer doble clic en uno de ellos, se abre en el cliente de correo de Windows. El contenido del archivo consiste en el texto completo del mensaje, tal como vimos en la pestaña [Raw] de [Mailpit]: allí se mezclan el texto del mensaje y el contenido codificado de los adjuntos.

Intentemos mejorar este script para que las distintas partes del mensaje y los adjuntos se almacenen en archivos separados.

16.6.7. Cliente IMAP mejorado ([imap-02.php])

El servidor IMAP puede proporcionarnos la estructura de un mensaje (comando [BODYSTRUCTURE]) y luego el contenido de cada una de sus partes (comando [FETCH n BODY[section]]). Lo aprovecharemos en el script [imap-02.php]. El protocolo POP3, en cambio, solo reconoce el mensaje completo: el script procesará únicamente los buzones IMAP.

Retomemos la respuesta al comando [BODYSTRUCTURE] obtenida cuando descubrimos el protocolo IMAP. Describe un mensaje de tipo [multipart/mixed] que tiene seis partes:

  • la primera parte es de tipo [multipart/alternative]. Tiene a su vez dos subpartes: [text/plain] y [text/html], codificadas en [quoted-printable] y con un parámetro [charset=utf-8];
  • las cinco partes siguientes son los adjuntos, codificados en [base64], cada uno con una disposición [attachment] y un nombre de archivo.

Las partes se numeran de la siguiente manera:

  • el mensaje completo, de tipo [multipart/mixed], no tiene número. Sus partes se numeran 1, 2...;
  • cuando una parte tiene subpartes, estas se numeran x.1, x.2..., donde x es el número de la parte que las contiene. Así, el texto [text/plain] del mensaje es la parte n.º 1.1: es la que solicitamos con el comando [FETCH 2 BODY.PEEK[1.1]].

El script [imap-02.php] es el siguiente:

<?php

declare(strict_types=1);

// cliente IMAP que guarda por separado los textos y los adjuntos de los mensajes no leídos
// usa la estructura MIME de los mensajes que proporciona el servidor IMAP (comando BODYSTRUCTURE)

require_once __DIR__ . "/ImapClient.php";

// los parámetros para leer el correo
const CONFIG_FILE_NAME = "config-imap-01.json";

// recuperamos la configuración
$mailboxes = json_decode(file_get_contents(CONFIG_FILE_NAME), true);

// lectura de los buzones
foreach ($mailboxes as $name => $info) {
    // solo nos interesan los buzones IMAP activos
    if (($info["enabled"] ?? true) === false || $info["protocol"] !== "imap") {
        continue;
    }
    print "------------Reading the mailbox [$name]\n";
    readmailbox($name, $info);
}
// fin
print "Done\n";

// --------------------------------------------------------------------------
function readmailbox(string $name, array $info): void
{
    $client = new ImapClient($info);
    try {
        // conexión
        $nbmsg = $client->connect();
        print "Connection established with the server [$name].\n";
        print "There are [$nbmsg] messages in the mailbox [$name]\n";
        // mensajes no leídos
        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) {
            // los encabezados del mensaje se usarán como prefijo de sus textos
            $headers = $client->headers($msgNumber);
            // la estructura del mensaje
            $structure = $client->structure($msgNumber);
            // recorremos sus 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
{
    // muestra el tipo de la parte [$part] del mensaje n.º $msgNumber y luego:
    // - si tiene subpartes, las procesa una por una (llamada recursiva);
    // - de lo contrario, la guarda en la carpeta [$outputDir]
    // $section es el número IMAP de la parte: 1, 2, 1.1, 1.2...
    // la parte raíz (el mensaje completo) no tiene número: mostramos 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) {
            // las subpartes de la parte n.º x se numeran x.1, x.2...
            $subsection = $section === "" ? (string) ($i + 1) : "$section." . ($i + 1);
            getParts($client, $msgNumber, $subpart, $subsection, $outputDir, $headers);
        }
        return;
    }
    // un mensaje que no es multipart tiene una sola parte, numerada 1
    if ($section === "") {
        $section = "1";
    }
    // guardamos la parte
    savePart($client, $msgNumber, $part, $section, $outputDir, $headers);
}

// --------------------------------------------------------------------------
function savePart(ImapClient $client, int $msgNumber, MimePart $part, string $section,
    string $outputDir, array $headers): void
{
    // si la carpeta no existe, la creamos
    if (!is_dir($outputDir)) {
        mkdir($outputDir, recursive: true);
    }
    // ¿un adjunto?
    $fileName = $part->fileName();
    if ($part->disposition === "attachment" && $fileName !== null) {
        saveAttachment($client->part($msgNumber, $section), $part, "$outputDir/$fileName");
        return;
    }
    // ¿un 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),
        // otros casos: esta parte no se procesará
        default => print "Part [$section] ignored\n",
    };
}

// --------------------------------------------------------------------------
function decode(string $text, string $encoding): string
{
    // decodificación de un contenido codificado en base64 o en quoted-printable
    return match ($encoding) {
        "base64" => base64_decode($text),
        "quoted-printable" => quoted_printable_decode($text),
        // 7bit, 8bit, binary: sin codificación
        default => $text,
    };
}

// --------------------------------------------------------------------------
function saveText(string $fileName, bool $html, string $text, MimePart $part, array $headers): void
{
    // el texto se decodifica y luego se convierte a UTF-8 si usa otro juego 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);
    }
    // lo precedemos con los encabezados From, To, Subject del mensaje
    $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";
    }
}

Comentarios:

  • línea 19: solo se leen los buzones IMAP activos;
  • línea 45: los encabezados del mensaje se utilizarán como prefijo del texto almacenado;
  • línea 47: la estructura del mensaje: un objeto [MimePart];
  • línea 50: la función [getParts] recorre las partes del mensaje. Comienza con la parte raíz (el mensaje completo), que no tiene número de sección;
  • línea 65: la función [getParts] recibe los siguientes parámetros:
    • [$client]: el cliente IMAP;
    • [$msgNumber]: el número del mensaje cuyas partes se solicitan;
    • [$part]: un objeto que representa una parte del mensaje;
    • [$section]: el número de esa parte;
    • [$outputDir]: la carpeta donde deben guardarse las partes;
    • [$headers]: información general sobre el correo (remitente, destinatario, asunto, etc.);
  • líneas 73–75: se muestran el número de la parte, el tipo de contenido y la codificación. El mensaje completo se muestra como la parte número 0;
  • líneas 77–83: si la parte tiene subpartes, cada una se obtiene mediante una llamada recursiva a la función [getParts]. Su número de sección es [$section.i];
  • líneas 86–87: un mensaje que no es multiparte (texto sin formato) tiene una sola parte, numerada 1;
  • línea 90: cuando no hay subpartes, se almacena el contenido de la parte;
  • línea 94: la función [savePart] registra una parte:
    • si es un adjunto (parámetro [attachment]), se guarda con la función [saveAttachment] con su nombre de archivo;
    • si el texto es [text/plain] o [text/html], se guarda con la función [saveText] en el archivo [message.txt] o [message.html]. Las demás partes se ignoran;
    • en ambos casos, el contenido de la sección se solicita al servidor IMAP mediante el método [part] del cliente;
  • línea 119: el contenido de una sección está codificado. Las funciones [base64_decode] y [quoted_printable_decode] lo decodifican;
  • línea 131: el texto se decodifica y luego se convierte a UTF-8 con la función [mb_convert_encoding] si utiliza un juego de caracteres diferente (parámetro [charset]). Va precedido de los encabezados del mensaje [From], [To] y [Subject]. En el caso de un texto HTML, cada encabezado va seguido de una etiqueta [<br/>] para que aparezca en su propia línea en un navegador;
  • línea 152: un adjunto se decodifica y luego se guarda.

Para probar el script [imap-02.php], primero envíe un correo a [guest@localhost] con el script [smtp-02.php] (el mensaje [test-localhost] y sus cinco adjuntos), que se deposita en el buzón INBOX del servidor IMAP. Luego se lee con [imap-02.php]. La salida de la consola es la siguiente:

> 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

La estructura del mensaje se conserva correctamente. Los archivos se guardaron en la carpeta [output/localhost-imap/message-3]:

1
2
3
4
5
6
7
8
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

Los documentos de Word, el PDF, el documento de OpenOffice y la imagen se abren con normalidad: se decodificaron correctamente.

El mensaje adjunto [test-localhost.eml] se guardó como un adjunto. Sin embargo, es en sí mismo un correo que, a su vez, contiene texto y adjuntos. Observe en la respuesta [BODYSTRUCTURE] que el servidor no pudo analizar este mensaje adjunto porque está codificado en Base64: devuelve un sobre vacío ([(NIL NIL ...)]) y una estructura reducida a un texto vacío. Para ir más lejos, tendríamos que descargar el mensaje adjunto, decodificarlo y analizar nosotros mismos su estructura (MIME). Y este mensaje podría contener a su vez un correo adjunto, y así sucesivamente. En lugar de escribir este analizador desde cero, utilizaremos una biblioteca.

16.6.8. Cliente POP3 / IMAP con la biblioteca [zbateson/mail-mime-parser]

El curso de PHP 7 utilizaba la biblioteca [php-mime-mail-parser], que requería PHP y la extensión [mailparse], que debían descargarse e instalarse por separado. Nosotros utilizaremos la biblioteca [zbateson/mail-mime-parser] (https://github.com/zbateson/mail-mime-parser), escrita íntegramente en PHP: se instaló con el comando [composer install] junto con las demás dependencias del curso, sin necesidad de ninguna otra acción. Analiza el texto completo de un mensaje, tal como lo devuelven los comandos [RETR] de POP3 y [FETCH n BODY[]] de IMAP. Por lo tanto, el script [imap-03.php] funcionará con ambos protocolos.

Para probarlo, enviaremos un mensaje cuyo último adjunto, [test-localhost-2.eml], contiene a su vez un correo adjunto, [test-localhost.eml]:

  • [test-localhost-2.eml] contiene 4 adjuntos (los documentos de Word, el PDF, el documento de OpenOffice y la imagen) y el correo [test-localhost.eml];
  • [test-localhost.eml] contiene los mismos 4 adjuntos.

El archivo de configuración [config-smtp-03.json] describe este correo:

{
    "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"
        ]
    }
}

Se utiliza con el comando [php smtp-02.php config-smtp-03.json].

El script [imap-03.php] utiliza el mismo archivo de configuración, [config-imap-01.json], que los scripts anteriores. Es el siguiente:

<?php

declare(strict_types=1);

// cliente IMAP / POP3 usado para leer correos
// el análisis de los mensajes se confía a la biblioteca [zbateson/mail-mime-parser]
// disponible en la URL [https://github.com/zbateson/mail-mime-parser]

// dependencias
require_once __DIR__ . "/../../../vendor/autoload.php";
require_once __DIR__ . "/ImapClient.php";
require_once __DIR__ . "/Pop3Client.php";

use ZBateson\MailMimeParser\IMessage;
use ZBateson\MailMimeParser\Message;

// los parámetros para leer el correo
const CONFIG_FILE_NAME = "config-imap-01.json";

// recuperamos la configuración
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);

// lectura de los buzones
foreach ($mailboxes as $name => $info) {
    if (($info["enabled"] ?? true) === false) {
        continue;
    }
    print "------------Reading the mailbox [$name]\n";
    readmailbox($name, $info);
}
// fin
print "Done\n";

// --------------------------------------------------------------------------
function readmailbox(string $name, array $info): void
{
    // un cliente IMAP o POP3 según la configuración
    $client = match ($info["protocol"]) {
        "imap" => new ImapClient($info),
        "pop3" => new Pop3Client($info),
    };
    try {
        // conexión
        $nbmsg = $client->connect();
        print "Connection established with the server [$name].\n";
        print "There are [$nbmsg] messages in the mailbox [$name]\n";
        // mensajes no leídos
        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";
        }
        // recorremos la lista de mensajes no leídos
        foreach ($msgNumbers as $msgNumber) {
            print "---message no. [$msgNumber]\n";
            // recuperamos el texto completo del mensaje y lo analizamos
            getMailBody($client->message($msgNumber), "{$info["output-dir"]}/message-$msgNumber");
            // si el protocolo es POP3, eliminamos el mensaje después de recuperarlo
            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álisis del texto completo de un mensaje
function getMailBody(string $text, string $outputDir): void
{
    // la biblioteca analiza el texto del mensaje y lo convierte en un objeto [IMessage]
    // (false: el texto ya no se usa una vez construido el objeto)
    $message = Message::from($text, false);
    // guardamos las diferentes partes del mensaje en la carpeta [$outputDir]
    getParts($message, $outputDir);
}

// --------------------------------------------------------------------------
// guardado de las diferentes partes de un mensaje
function getParts(IMessage $message, string $outputDir): void
{
    // creamos la carpeta donde se guarda el mensaje si es necesario
    if (!is_dir($outputDir) && !mkdir($outputDir, recursive: true)) {
        print "The folder [$outputDir] could not be created\n";
        return;
    }
    // los encabezados del mensaje (from, to, subject...), decodificados
    $headers = [];
    foreach ($message->getAllHeaders() as $header) {
        $headers[] = "{$header->getName()}: {$header->getValue()}";
    }
    // guardamos los mensajes 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");
    }
    // guardamos los mensajes 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");
    }
    // recorremos la lista de adjuntos
    $iAttachment = 0;
    foreach ($message->getAllAttachmentParts() as $attachment) {
        // tipo y nombre del adjunto
        $fileType = $attachment->getContentType();
        $fileName = freeName($outputDir, $attachment->getFilename() ?? "attachment");
        print "-- Saving an attachment of type [$fileType] in the file [$fileName]\n";
        // guardamos el adjunto, decodificado
        $attachment->saveContent($fileName);
        // caso especial del tipo message/rfc822
        if ($fileType === "message/rfc822") {
            // el adjunto es en sí mismo un mensaje - lo analizamos recursivamente
            // en una subcarpeta [rfc822-1], [rfc822-2]...
            $iAttachment++;
            $attachedMessage = Message::from($attachment->getBinaryContentStream()->getContents(), false);
            getParts($attachedMessage, "$outputDir/rfc822-$iAttachment");
        }
    }
}

// --------------------------------------------------------------------------
// un nombre de archivo libre en la carpeta [$dir]: x.pdf; de lo contrario, 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;
}

// --------------------------------------------------------------------------
// guardado de un mensaje de texto precedido de los encabezados del mensaje
function saveMessage(string $text, bool $html, array $headers, string $filename): void
{
    // en HTML, cada encabezado termina con <br/> para quedar solo en su línea
    $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";
    }
}

Comentarios:

  • línea 10: el cargador de clases de Composer para la biblioteca [zbateson/mail-mime-parser];
  • líneas 14–15: los dos tipos de la biblioteca que utilizamos: la interfaz [IMessage] y la clase [Message] que la implementa;
  • línea 21: se comprueba que el archivo de configuración exista;
  • línea 39: la función [readmailbox] tiene la misma estructura que en [imap-01.php]. El cliente IMAP o POP3 se crea esta vez directamente mediante una expresión [match];
  • línea 61: el texto completo del mensaje se solicita a la función [getMailBody];
  • líneas 81–87: el método estático [Message::from] analiza el texto del mensaje y devuelve un objeto [IMessage]. La función [getParts] guarda entonces sus distintas partes;
  • línea 92: la función [getParts] recibe dos parámetros:
    • el mensaje [$message] que se va a analizar;
    • [$outputDir]: la carpeta en la que deben guardarse el texto y los adjuntos del mensaje;
  • líneas 101–102: se obtienen los encabezados del mensaje analizado (from, to, subject, etc.). El método [getValue] devuelve el valor decodificado de un encabezado;
  • líneas 105–107: un mensaje puede tener varias partes ([text/plain]). El método [getTextContent($i - 1)] devuelve el texto de la i-ésima parte (las partes se numeran a partir de 0), decodificado y convertido a UTF-8. Las guardamos todas, dándole a cada una un nombre de archivo diferente;
  • líneas 110–112: mismo procedimiento para las partes [text/html];
  • línea 116: se recorre la lista de adjuntos del mensaje;
  • líneas 118–119: el tipo del adjunto (encabezado Content-Type) y su nombre, decodificado por la biblioteca independientemente de cómo esté codificado. La función [freeName] devuelve un nombre de archivo que aún no existe en la carpeta;
  • línea 122: el método [saveContent] guarda en un archivo el contenido decodificado del adjunto;
  • líneas 124–129: si el adjunto es un correo, se analiza a su vez mediante una llamada recursiva a la función [getParts]. Su contenido decodificado se obtiene con el método [getBinaryContentStream], que devuelve un flujo; luego se lee todo el contenido de este flujo con el método [getContents]. Si el mensaje analizado tiene dos correos adjuntos, el primero se guardará en la carpeta [$outputDir/rfc822-1] y el segundo en la carpeta [$outputDir/rfc822-2];
  • línea 136: si el archivo [x.pdf] ya existe, la función [freeName] prueba con los nombres [x_1.pdf], [x_2.pdf]... hasta encontrar un nombre de archivo que no exista. La función [pathinfo] separa un nombre de archivo en nombre y extensión;
  • línea 149: la función [saveMessage] guarda el texto del mensaje precedido de sus encabezados. En el caso de un texto HTML, cada encabezado termina con la etiqueta [<br/>].

Enviamos el mensaje con el comando [php smtp-02.php config-smtp-03.json]. [Mailpit] lo almacena y también lo colocamos en el buzón INBOX del servidor IMAP. Luego ejecutamos el script [imap-03.php]. La salida de la consola es la siguiente:

> 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

El mensaje se leyó dos veces (primero por IMAP y luego por POP3) y sus partes se guardaron en cada ocasión. Esta es la estructura de directorios de la carpeta [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
  • en el nivel superior, el texto y los 5 adjuntos del correo recibido por [guest@localhost];
  • en la carpeta [rfc822-1], el texto del cuerpo y los 5 adjuntos del correo [test-localhost-2.eml];
  • en la carpeta [rfc822-1/rfc822-1], el texto y los 4 adjuntos del correo [test-localhost.eml].

Si se visualiza el archivo [rfc822-1/rfc822-1/message_1.html] en un navegador, se verá lo siguiente:

Image

Contiene los encabezados del correo [test-localhost.eml], seguidos de su texto del cuerpo, con los caracteres acentuados correctamente decodificados.

Utilizar la biblioteca [zbateson/mail-mime-parser] facilita mucho la escritura del script de lectura de correos.