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 Lista de Protocolos/Envolturas Soportadas), 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 Working with streams. 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 Lista de Protocolos/Envolturas Soportadas 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, este 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 Lista de Protocolos/Envolturas Soportadas 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 Working with streams. 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 Lista de Protocolos/Envolturas Soportadas).

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 este 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 poblará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 esta 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 esta 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).
`STREAM_SHUT_RD`	Usada con stream_socket_shutdown() para deshabilitar futuras recepciones. Agregada en PHP 5.2.1.
`STREAM_SHUT_WR`	Usada con stream_socket_shutdown() para deshabilitar futuras transmisiones. Agregada en PHP 5.2.1.
`STREAM_SHUT_RDWR`	Usada con stream_socket_shutdown() para deshabilitar futuras recepciones y transmisiones. Agregada en PHP 5.2.1.

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

Note: 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

Example#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");

/* Idéntico al ejemplo anterior, indicando explícitamente 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");
?>

Example#2 Realizar una petición POST a un servidor https


<?php
/* Enviar una petición 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);
?>

Example#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 línea 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);
?>

stream_bucket_append — Anexar cubo a una brigada
stream_bucket_make_writeable — Devolver un objeto tipo cubo de una brigada para operar sobre él
stream_bucket_new — Crear un nuevo cubo para su uso en la secuencia actual
stream_bucket_prepend — Agregar un cubo al comienzo de una brigada
stream_context_create — Crear un contexto de secuencia
stream_context_get_default — Recuperar el contexto de secuencias predeterminado
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_encoding — Set character set for stream encoding
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 — Remover un filtro de una secuencia
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_resolve_include_path — Determine what file will be opened by calls to fopen with a relative path
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 — Habilita/deshabilita la encripción sobre un socket ya conectado
stream_socket_get_name — Recuperar el nombre de los sockets locales o remotos
stream_socket_pair — Crea un par de secuencias de socket conectados e indistinguibles
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_socket_shutdown — Shutdown a full-duplex connection
stream_wrapper_register — Registrar una envoltura URL implementada como una clase PHP
stream_wrapper_restore — Recupera una envoltura incorporada, previamente retirada del registro
stream_wrapper_unregister — Retirar del registro una envoltura de URL