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.
void
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ó 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");
?>
|
Salida
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ó 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");
/* Salida
* ------
LINEA1
PALABRA - 2
TAN SENCILLO COMO 123
*/
?>
|
|
Vea también
stream_wrapper_register(),
stream_filter_prepend(), y
stream_filter_append().
