stream_filter_register

Descripción

bool stream_filter_register ( string nombre_filtro, string nombre_clase )

stream_filter_register() le permite implementar su propio filtro en cualquier secuencia registrada utilizada con todas los otras funciones de sistema de archivos (tales como fopen(), fread() etc.).

Para implementar un filtro, necesita definir una clase como una extensión de php_user_filter con un número de funciones miembro, tal y como se define más adelante. Cuando realice operaciones de lectura/escritura en la secuencia a la que se ha adjuntado su filtro, PHP pasará los datos a través de su filtro (y cualquier otro filtre adjunto a esa secuencia) de modo que los datos puedan ser modificados como lo desee. Debe implementar los métodos exactamente como se describe más adelante - hacerlo de otra forma llevará a comportamientos indefenidos.

stream_filter_register() devolverá FALSE si nombre_filtro ya se encuentra definido.

int filter ( resource entrada, resource salida, int &consumido, bool cerrando )

Este método es llamado siempre que se lean o escriban datos desde y hacia la secuencia adjunta (tal y como sucede con fread() o fwrite()). entrada es un recurso que apunta a una brigada de paquetes que contiene uno o más objetos de tipo paquete que contienen datos a ser filtrados. salida es un recurso que apunta a una segunda brigada de paquetes en la que deben ser colocados sus paquetes modificados. consumido, que debe declararse siempre por referencia, debe ser incrementado de acuerdo a la longitud de los datos que su filtro lee y altera. En la mayoría de casos esto quiere decir que usted incrementa consumido en $paquete->datalen para cada $paquete. Si la secuencia está en el proceso de ser cerrada (y por lo tanto este es el último paso por la cadena de filtros), el parámetro cerrando será definido como TRUE. El método filter debe devolver uno de tres valores cuando complete su ejecución.

bool onCreate ( void )

Este método es llamado durante la instanciación del objeto clase del filtro. Si su filtro ubica o inicializa cualquier otro tipo de recursos (como un búfer), éste es el lugar para hacerlo. Su implementación de este método debería devolver FALSE en caso de fallo, o TRUE si tiene éxito.

Cuando su filtro es instanciado por primera vez, y su_filtro->onCreate() es llamado, se colocarán a su disposición un número de propiedades, como lo muestra la siguiente tabla.

void onClose ( void )

Este método es llamado cuando se realiza la destrucción del filtro (por lo general, esto ocurre también durante la destrucción de la secuencia), y es ejecutado después de que el método flush es llamado. Si se ubicaron o inicializaron recursos durante onCreate, éste sería el momento para destruirlos o desecharlos.

El siguiente ejemplo implementa un filtro llamado strtoupper en la secuencia foo-bar.txt, el cual convierte a mayúsculas todos los caracteres alfabéticos escritos hacia/leidos desde esa secuencia.

Ejemplo 1. Filtro para convertir los caracteres a mayúsculas en la secuencia foo-bar.txt <?php /* Definicion de nuestra clase de filtro */ class strtoupper_filter extends php_user_filter {   function filter($entrada, $salida, &$consumido, $cerrando)   {     while ($paquete = stream_bucket_make_writeable($entrada)) {       $paquete->data = strtoupper($paquete->data);       $consumido += $paquete->datalen;       stream_bucket_append($salida, $paquete);     }     return PSFS_PASS_ON;   } } /* Registrar nuestro filtro con PHP */ stream_filter_register("strtoupper", "strtoupper_filter")     or die("Fall&oacute; el registro del filtro"); $da = fopen("foo-bar.txt", "w"); /* Adjuntar el filtro registrado a la secuencia que acabamos de abrir */ stream_filter_append($da, "strtoupper"); fwrite($da, "Linea1\n"); fwrite($da, "Palabra - 2\n"); fwrite($da, "Tan sencillo como 123\n"); fclose($da); /* Leer los contenidos de vuelta */ readfile("foo-bar.txt"); ?> El resultado del ejemplo seria: LINEA1 PALABRA - 2 TAN SENCILLO COMO 123

Ejemplo 2. Registro de una clase genérica de filtro para que coincida con múltiples nombres de filtro. <?php /* Definicion de nuestra clase de filtro */ class filtro_cadena extends php_user_filter {   var $modo;   function filter($entrada, $salida, &$consumido, $cerrando)   {     while ($paquete = stream_bucket_make_writeable($entrada)) {       if ($this->modo == 1) {         $paquete->data = strtoupper($paquete->data);       } elseif ($this->modo == 0) {         $paquete->data = strtolower($paquete->data);       }       $consumido += $paquete->datalen;       stream_bucket_append($salida, $paquete);     }     return PSFS_PASS_ON;   }   function onCreate()   {     if ($this->filtername == 'str.toupper') {       $this->modo = 1;     } elseif ($this->filtername == 'str.tolower') {       $this->modo = 0;     } else {       /* Se ha pedido otro filtro str.* , reportar un fallo de modo        * que PHP continue buscando */       return false;     }     return true;   } } /* Registrar nuestro filtro con PHP */ stream_filter_register("str.*", "filtro_cadena")     or die("Fall&oacute; el registro del filtro"); $da = fopen("foo-bar.txt", "w"); /* Adjuntar el filtro registrado a la secuencia recien * abierta. Alternativamente, aqui podemos enlazar str.tolower */ stream_filter_append($da, "str.toupper"); fwrite($da, "Linea1\n"); fwrite($da, "Palabra - 2\n"); fwrite($da, "Tan sencillo como 123\n"); fclose($da); /* Leer los contenidos de vuelta */ readfile("foo-bar.txt"); ?> El resultado del ejemplo seria: LINEA1 PALABRA - 2 TAN SENCILLO COMO 123

Vea también stream_wrapper_register(), stream_filter_prepend(), y stream_filter_append().