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:
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("https://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:[email protected]/foo.txt");
/* Leer un archivo remoto desde ftp.example.com usando FTPS */
$archivo_ftps = file_get_contents("ftps://usuario:[email protected]/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);
?>
Table of Contents
- 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