Introducción

Las secuencias (streams) fueron introducidas con PHP 4.3.0 como un medio de generalizar el acceso a archivos, recursos de red, compresión de datos, y otras operaciones que comparten un juego común de funciones y usos. En su forma más simple, una secuencia es un objeto recurso que exhibe un comportamiento secuenciable. Esto quiere decir, pueden leerse datos desde la secuencia o escribir datos hacia ella en una forma lineal, y puede que sea posible efectuar búsquedas con fseek() de ubicaciones arbitrarias dentro de la secuencia.

Una envoltura (wrapper) es un código adicional que le dice a la secuencia cómo gestionar los protocolos y codificaciones específicas. Por ejemplo, la envoltura http sabe cómo traducir una URL a una petición HTTP/1.0 por un archivo en un servidor remoto. Existen varias envolturas incluidas con PHP por defecto (Vea Apéndice M), y envolturas adicionales, personalizadas, pueden agregarse ya sea dentro de un script PHP usando stream_wrapper_register(), o directamente desde una extensión usando la Referencia de API en Capítulo 63. Dado que cualquier tipo de envoltura puede ser agregada a PHP, no existe un límite impuesto en lo que se puede hacer con ellas. Para consultar la lista de envolturas soportadas actualmente, use stream_get_wrappers().

Una secuencia es referenciada como: esquema://destino

• esquema(cadena) - El nombre de la envoltura a ser usada. Algunos ejemplos: file, http, https, ftp, ftps, compress.zlib, compress.bz2, y php. Vea Apéndice M para consultar una lista de envolturas integradas con PHP. Si no se especifica una envoltura, es usada la envoltura predeterminada de la función (usualmente file://).

• destino - Depende en la envoltura usada. Para secuencias relacionadas con el sistema de archivos, éste parámetro es por lo general una ruta y un nombre de archivo que apunta al archivo deseado. Para secuencias de red, usualmente consiste de un nombre de host, por lo general con una ruta adicionada al final. Nuevamente, vea Apéndice M para encontrar una descripción de destinos para las secuencias integradas.

Filtros de Secuencia

Un filtro es una pieza final de código que puede efectuar operaciones sobre los datos a medida que éstos son leídos desde una secuencia o escritos hacia una. Puede apilarse cualquier cantidad de filtros sobre una secuencia. Pueden definirse filtros personalizados en un script PHP usando stream_filter_register() o en una extensión usando la Referencia API de Capítulo 63. Para consultar la lista de filtros registrados actualmente, use stream_get_filters().

Contextos de Secuencia

Un contexto es un conjunto de parámetros y opciones específicas de cada envoltura que modifican o mejoran el comportamiento de una secuencia. Los contextos son creados usando stream_context_create() y pueden ser pasados a la mayoría de funciones de creación de secuencias relacionadas con el sistema de archivos (esto es, fopen(), file(), file_get_contents(), etc...).

Pueden especificarse opciones cuando se hacen llamados a stream_context_create(), o más adelante usando stream_context_set_option(). Una lista de opciones específicas de envoltura puede encontrarse con la lista de envolturas integradas (Vea Apéndice M).

Adicionalmente, pueden definirse parámetros en un contexto usando stream_context_set_params(). Actualmente, el único parámetro de contexto soportado por PHP es notificación. El valor de éste parámetro debe ser el nombre de una función a ser llamada cuando un evento ocurre sobre una secuencia. La función de notificación llamada durante un evento debe aceptar los siguientes seis parámetros:

codigo_mensaje y severidad son valores numéricos que corresponden a las constantes STREAM_NOTIFY_* listadas más adelante. Si un mensaje descriptivo se encuentra disponible desde la secuencia, mensaje y codigo_mensaje se popularán con los valores apropiados. El significado de éstos valores depende de la envoltura específica en uso. bytes_transferidos y bytes_max se popularán cuando sea aplicable.

Instalación

Las secuencias son parte integral de PHP a partir de la versión 4.3.0. No se requiere de ningún paso adicional para habilitarlas.

Clases de Secuencia

Es posible registrar envolturas diseñadas por el usuario mediante stream_wrapper_register(), use la definición de clase expuesta en su respectiva página del manual.

La clase php_user_filter se encuentra predefinida y es una clase base abstracta para su uso con filtros definidos por el usuario. Vea la página del manual sobre stream_filter_register() para más detalles sobre la implementación de filtros definidos por el usuario.

Constantes predefinidas

Estas constantes están definidas por esta extensión y estarán disponibles solamente cuando la extensión ha sido o bien compilada dentro de PHP o grabada dinámicamente en tiempo de ejecución.

Errores de Secuencia

Al igual que con cualquier otra función relacionada con archivos o sockets, una operación sobre una secuencia puede fallar por una variedad de razones normales (esto es: Incapaz de conectarse con el servidor remoto, archivo no encontrado, etc...). Una llamada relacionada con una secuencia puede fallar también debido a que la secuencia deseada no está registrada en el sistema actual. Consulte la matriz devuelta por stream_get_wrappers() para ver una lista de secuencias soportadas en su instalación de PHP. Al igual que con la mayoría de funciones internas de PHP, si ocurre un fallo, se generará un mensaje E_WARNING que describe la naturaleza del error.

Ejemplos

Ejemplo 1. Uso de file_get_contents() para recuperar datos de múltiples fuentes <?php /* Leer archivo local desde /home/bar */ $archivo_local = file_get_contents("/home/bar/foo.txt"); /* Identico al ejemplo anterior, indicando explicitamente el esquema FILE */ $archivo_local = file_get_contents("file:///home/bar/foo.txt"); /* Leer un archivo remoto desde www.example.com usando HTTP */ $archivo_http  = file_get_contents("http://www.example.com/foo.txt"); /* Leer un archivo remoto desde www.example.com usando HTTPS */ $archivo_https = file_get_contents("https://www.example.com/foo.txt"); /* Leer un archivo remoto desde ftp.example.com usando FTP */ $archivo_ftp   = file_get_contents("ftp://usuario:contrasenya@ftp.example.com/foo.txt"); /* Leer un archivo remoto desde ftp.example.com usando FTPS */ $archivo_ftps  = file_get_contents("ftps://usuario:contrasenya@ftp.example.com/foo.txt"); ?>

Ejemplo 2. Realizar una petición POST a un servidor https <?php /* Enviar una peticion POST a https://seguro.example.com/formulario.php * Incluir elementos de formulario llamados "foo" y "bar" con valores * de prueba */ $sock = fsockopen("ssl://seguro.example.com", 443, $errno, $errstr, 30); if (!$sock) die("$errstr ($errno)\n"); $datos = "foo=" . urlencode("Valor para Foo") . "&bar=" . urlencode("Valor para Bar"); fwrite($sock, "POST /formulario.php HTTP/1.0\r\n"); fwrite($sock, "Host: seguro.example.com\r\n"); fwrite($sock, "Content-type: application/x-www-form-urlencoded\r\n"); fwrite($sock, "Content-length: " . strlen($datos) . "\r\n"); fwrite($sock, "Accept: */*\r\n"); fwrite($sock, "\r\n"); fwrite($sock, "$data\r\n"); fwrite($sock, "\r\n"); $cabeceras = ""; while ($cadena = trim(fgets($sock, 4096)))   $cabeceras .= "$cadena\n"; echo "\n"; $cuerpo = ""; while (!feof($sock))   $cuerpo .= fgets($sock, 4096); fclose($sock); ?>

Ejemplo 3. Escritura de datos a un archivo comprimido <?php /* Crear un archivo comprimido que contenga una cadena arbitraria * El archivo puede ser leido de vuelta usando una secuencia * compress.zlib o simplemente descomprimido desde la linea de comandos * usando 'gzip -d foo-bar.txt.gz' */ $da = fopen("compress.zlib://foo-bar.txt.gz", "wb"); if (!$da) die("No fue posible crear el archivo."); fwrite($da, "Esto es una prueba.\n"); fclose($da); ?>