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 44. 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 44. 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); ?>