CXXXII. Funciones de Secuencias

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:

void mi_notificador ( int codigo_notificacion, int severidad, string mensaje, int codigo_mensaje, int bytes_transferidos, int bytes_max )

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.

Constante	Descripción
`STREAM_FILTER_READ` *	Usada con stream_filter_append() y stream_filter_prepend() para indicar que el filtro especificado debería ser aplicado únicamente cuando se esté efectuando lectura.
`STREAM_FILTER_WRITE` *	Usada con stream_filter_append() y stream_filter_prepend() para indicar que el filtro especificado debería ser aplicado únicamente cuando se esté efectuando escritura.
`STREAM_FILTER_ALL` *	Esta constante es equivalente a `STREAM_FILTER_READ \| STREAM_FILTER_WRITE`.
`PSFS_PASS_ON` *	`Código de Retorno` que indica que el filtro de espacio de usuario devolvió paquetes en `$salida`.
`PSFS_FEED_ME` *	`Código de Retorno` que indica que el filtro de espacio de usuario no devolvió paquetes en `$salida` (lo que quiere decir que no hay datos disponibles).
`PSFS_ERR_FATAL` *	`Código de Retorno` que indica que el filtro de espacio de usuario encontró un error irrecuperable (esto quiere decir, se recibieron datos inválidos).
`STREAM_USE_PATH`	`Bandera` que indica si la `secuencia` usó la ruta de inclusión.
`STREAM_REPORT_ERRORS`	`Bandera` que indica si la `envoltura` es responsable de generar errores usando trigger_error() durante la apertura de la secuencia. Si esta bandera no está definida, usted no debería generar errores.
`STREAM_CLIENT_ASYNC_CONNECT` *	Abrir el socket de cliente asincrónicamente. Esta opción debe ser usada junto con la bandera `STREAM_CLIENT_CONNECT`. Constante usada con stream_socket_client().
`STREAM_CLIENT_CONNECT` *	Abrir una conexión de socket cliente. Los sockets cliente deberían incluir siempre esta bandera. Constante usada con stream_socket_client().
`STREAM_CLIENT_PERSISTENT` *	El socket de cliente abierto con stream_socket_client() debe permanecer persistente entre cargas de la página.
`STREAM_SERVER_BIND` *	Le dice a una secuencia creada con stream_socket_server() que se enlace con el destino especificado. Los sockets de servidor siempre deberían incluir ésta bandera.
`STREAM_SERVER_LISTEN` *	Le dice a una secuencia creada con stream_socket_server() y enlazada usando la bandera `STREAM_SERVER_BIND` que comience a escuchar en el socket. Los transportes orientados a conexiones (como TCP) deben usar esta bandera, de lo contrario el socket de servidor no será habilitado. Usar esta bandera con transportes sin conexión (como UDP) es un error.
`STREAM_NOTIFY_RESOLVE` *	Una dirección remota requerida para ésta secuencia ha sido resuelta, o la resolución falló. Vea `severidad` para contar con una indicación de lo que ha sucedido.
`STREAM_NOTIFY_CONNECT`	Se ha establecido una conexión con un recurso externo.
`STREAM_NOTIFY_AUTH_REQUIRED`	Se requiere de autorización adicional para acceder al recurso especificado. Típicamente se emite con un nivel de `severidad` de `STREAM_NOTIFY_SEVERITY_ERR`.
`STREAM_NOTIFY_MIME_TYPE_IS`	El `tipo-mime` del recurso ha sido identificado, refiérase a `mensaje` para una descripción del tipo descubierto.
`STREAM_NOTIFY_FILE_SIZE_IS`	El `tamaño` del recurso ha sido descubierto.
`STREAM_NOTIFY_REDIRECTED`	El recurso externo ha redireccionado la secuencia a una ubicación alternativa. Refiérase a `mensaje`.
`STREAM_NOTIFY_PROGRESS`	Indica el progreso actual de una transferencia de secuencia en `bytes_transferidos`, y posiblemente `bytes_max` también.
`STREAM_NOTIFY_COMPLETED` *	No hay más datos disponibles en la secuencia.
`STREAM_NOTIFY_FAILURE`	Un error genérico ocurrió en la secuencia, consulte `mensaje` y `codigo_mensaje` para más detalles.
`STREAM_NOTIFY_AUTH_RESULT`	La autorización se ha completado (con o sin éxito).
`STREAM_NOTIFY_SEVERITY_INFO`	Notificación normal, no relacionada con errores.
`STREAM_NOTIFY_SEVERITY_WARN`	Condición de error no-crítico. El procesamiento puede continuar.
`STREAM_NOTIFY_SEVERITY_ERR`	Un error crítico ha ocurrido. El procesamiento no puede continuar.
`STREAM_IPPROTO_ICMP` +	Ofrece un socket ICMP.
`STREAM_IPPROTO_IP` +	Ofrece un socket IP.
`STREAM_IPPROTO_RAW` +	Ofrece un socket RAW.
`STREAM_IPPROTO_TCP` +	Ofrece un socket TCP.
`STREAM_IPPROTO_UDP` +	Ofrece un socket UDP.
`STREAM_PF_INET` +	Protocolo de Internet Versión 4 (IPv4).
`STREAM_PF_INET6` +	Protocolo de Internet Versión 6 (IPv6).
`STREAM_PF_UNIX` +	Protocolos internos de sistema Unix.
`STREAM_SOCK_DGRAM` +	Ofrece datagramas, que son mensajes sin conexión (UDP, por ejemplo).
`STREAM_SOCK_RAW` +	Ofrece un socket puro, lo cual provee accesso a protocolos de red e interfaces internas. Por lo general, este tipo de sockets sólo están disponibles para el usuario administrador (root).
`STREAM_SOCK_RDM` +	Ofrece un socket RDM (mensajes entregados confiablemente).
`STREAM_SOCK_SEQPACKET` +	Ofrece un socket de secuencia de paquetes secuenciados.
`STREAM_SOCK_STREAM` +	Ofrece secuencias de bytes en doble-vía con un mecanismo de transmisión para datos fuera-de-banda (TCP, por ejemplo).

Nota: Las constantes marcadas con * se encuentran disponibles únicamente a partir de PHP 5.0.0.

Nota: Las constantes marcadas con + están disponibles desde PHP 5.1.0 y están diseñadas para ser usadas con stream_socket_pair(). Por favor note que algunas de estas constantes pueden no estar disponibles en su sistema.

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

Tabla de contenidos
stream_bucket_append -- Append bucket to brigade
stream_bucket_make_writeable -- Return a bucket object from the brigade for operating on
stream_bucket_new -- Create a new bucket for use on the current stream
stream_bucket_prepend -- Prepend bucket to brigade
stream_context_create -- Crear un contexto de secuencia
stream_context_get_default -- Retreive the default streams context
stream_context_get_options -- Recuperar las opciones para una secuencia/envoltura/contexto
stream_context_set_option -- Establece una opción para una secuencia/envoltura/contexto
stream_context_set_params -- Establecer parámetros para una secuencia/envoltura/contexto
stream_copy_to_stream -- Copia datos desde una secuencia a otra
stream_filter_append -- Adjuntar un filtro a una secuencia
stream_filter_prepend -- Adjuntar un filtro a una secuencia
stream_filter_register -- Registrar un filtro de secuencia implementado como una clase PHP derivada de php_user_filter
stream_filter_remove -- Remove a filter from a stream
stream_get_contents -- Lee el resto de una secuencia en una cadena
stream_get_filters -- Recuperar la lista de filtros registrados
stream_get_line -- Obtiene una línea desde un recurso de secuencia, hasta un delimitador dado
stream_get_meta_data -- Recupera meta datos/cabeceras desde apuntadores a secuencias/archivos
stream_get_transports -- Recuperar la lista de transportes de socket registrados
stream_get_wrappers -- Recuperar la lista de secuencias registradas
stream_register_wrapper -- Alias de stream_wrapper_register()
stream_select -- Ejecuta el equivalente al llamado de sistema select() en la matriz de secuencias dada, con un tiempo de espera especificado por tv_sec y tv_usec
stream_set_blocking -- Establecer modo de bloqueo/no-bloqueo sobre una secuencia
stream_set_timeout -- Establecer el periodo de espera de una secuencia
stream_set_write_buffer -- Establece el uso de búferes de archivo en la secuencia dada
stream_socket_accept -- Aceptar una conexión en un socket creado por stream_socket_server()
stream_socket_client -- Abrir una conexión de socket de dominio de Internet o Unix
stream_socket_enable_crypto -- Turns encryption on/off on an already connected socket
stream_socket_get_name -- Recuperar el nombre de los sockets locales o remotos
stream_socket_pair -- Creates a pair of connected, indistinguishable socket streams
stream_socket_recvfrom -- Recibe datos desde un socket, conectado o no
stream_socket_sendto -- Envía un mensaje a un socket, sin importar si está conectado o no
stream_socket_server -- Crear un socket de servidor de dominio de Internet o Unix
stream_wrapper_register -- Registrar una envoltura URL implementada como una clase PHP
stream_wrapper_restore -- Restores a previously unregistered built-in wrapper
stream_wrapper_unregister -- Unregister a URL wrapper