PHP Stream

PHP Streams

Un stream en PHP es una forma genérica de leer o escribir en un flujo de datos, independientemente de dónde residan esos datos. Un archivo en disco, un fragmento de memoria, un socket de red y el cuerpo de una respuesta HTTP son cosas muy diferentes, pero PHP permite manejarlas con el mismo conjunto de funciones. Esa uniformidad es precisamente el objetivo: una vez que sabes cómo leer un archivo con fopen()/fgets(), ya sabes cómo leer una página web o un buffer de memoria.

Esta página explica qué son los streams, las funciones que los impulsan, los wrappers que identifican la fuente de un stream y cómo trabajar con ellos de forma segura.

¿Qué problema resuelven los streams?

Sin streams necesitarías una API diferente para cada fuente de datos: una para archivos, otra para HTTP, otra para sockets. Los streams ofrecen una única abstracción:

• Wrapper — un prefijo como file://, php://, http:// o php://memory que le indica a PHP qué tipo de recurso se está direccionando.
• Manejador de recurso — el valor que devuelve fopen(); se pasa a todas las demás funciones de stream.
• Filtros y contextos — capas opcionales que transforman los datos (p. ej., gzip) o configuran la conexión (p. ej., cabeceras HTTP, tiempos de espera).

Gracias a este diseño, puedes sustituir una ruta local por una URL remota y la mayor parte del código permanece igual.

Funciones principales de stream

Estas funciones forman la base de la API de Streams:

El parámetro $mode controla el acceso: 'r' (lectura), 'w' (escritura, truncar), 'a' (añadir) y las variantes con '+' para lectura y escritura.

Para lecturas y escrituras puntuales normalmente no es necesario gestionar un manejador directamente: los helpers de alto nivel file_get_contents() y file_put_contents() abren, transfieren y cierran un stream en una sola llamada.

Wrappers y tipos de stream

El wrapper al inicio de la cadena de destino determina el tipo de stream:

• Streams de archivo (file://, o simplemente una ruta) — leen y escriben datos en el sistema de archivos. Consulta PHP File Handling y Open and Read a File.
• Streams de memoria (php://memory, php://temp) — un buffer de lectura/escritura que reside en RAM; ideal para construir datos en pruebas sin tocar el disco.
• Streams de E/S (php://stdin, php://stdout, php://input) — entrada/salida estándar y el cuerpo sin procesar de la petición.
• Streams de red / socket (tcp://, ssl://) — lectura y escritura a través de una conexión de red.
• Streams HTTP/FTP (http://, https://, ftp://) — recuperan documentos remotos como si fueran archivos (requiere que allow_url_fopen esté habilitado).

Leer un archivo línea por línea

Este ejemplo mínimo y autocontenido escribe un pequeño archivo, lo lee a través de un stream línea a línea y luego limpia:

<?php

$path = sys_get_temp_dir() . '/stream-demo.txt';

// Write three lines using the high-level helper.
file_put_contents($path, "alpha\nbeta\ngamma\n");

// Read them back through a stream handle.
$handle = fopen($path, 'r');
if ($handle === false) {
    exit("Could not open the stream.\n");
}

while (!feof($handle)) {
    $line = fgets($handle);
    if ($line !== false) {
        echo "Line: " . trim($line) . PHP_EOL;
    }
}

fclose($handle);
unlink($path);

Salida:

Line: alpha
Line: beta
Line: gamma

Abrimos el archivo en modo lectura, iteramos hasta que feof() indica el final y leemos cada línea con fgets(). Siempre verifica que fopen() no haya devuelto false antes de usar el manejador, y llama a fclose() cuando hayas terminado.

Usar un stream de memoria

Los streams de memoria se comportan como archivos pero nunca acceden al disco, lo que resulta útil para ensamblar salidas o para pruebas unitarias:

<?php

$handle = fopen('php://memory', 'r+');

fwrite($handle, "buffered data");

// Rewind to the start before reading what we wrote.
rewind($handle);

echo fread($handle, 1024);

fclose($handle);

Salida:

buffered data

Tras escribir, debes llamar a rewind() para volver al inicio antes de leer, ya que la posición interna se encuentra al final de lo que acabas de escribir.

Leer un stream remoto

Como HTTP es simplemente otro wrapper, el mismo bucle funciona contra una URL cuando allow_url_fopen está habilitado:

<?php

$handle = fopen('https://www.example.com', 'r');
if ($handle === false) {
    exit("Failed to open the remote stream.\n");
}

while (!feof($handle)) {
    echo fgets($handle);
}

fclose($handle);

Este ejemplo requiere acceso a la red y el ajuste allow_url_fopen activado, por lo que no se ejecutará en un entorno sin conexión. Para aplicaciones reales, un cliente HTTP dedicado como cURL ofrece un mayor control sobre las cabeceras, los tiempos de espera y los errores.

Manejo de errores

Las funciones de stream señalan los fallos devolviendo false en lugar de lanzar excepciones, así que protege cada llamada:

• Comprueba el valor de retorno de fopen() antes de leer o escribir.
• Envuelve las operaciones arriesgadas en bloques try/catch si conviertes las advertencias en excepciones; consulta PHP Exceptions.
• Siempre cierra con fclose() los manejadores que hayas abierto para liberar recursos.

Conclusión

Los streams proporcionan a PHP una interfaz única y coherente para todo tipo de flujos de datos: archivos, buffers de memoria, sockets y respuestas HTTP. Aprende el pequeño conjunto de funciones principales (fopen, fread/fgets, fwrite, feof, fclose), comprende los wrappers como file:// y php://memory, y apóyate en los helpers de alto nivel file_get_contents()/file_put_contents() para los casos sencillos. Para profundizar, explora cómo crear y escribir archivos y el manejo de errores adecuado.

Práctica