stream_filter_prepend
stream_filter_remove
Stream Functions
PHP Manual

# stream_filter_register

(PHP 5)

stream_filter_register — Registrar un filtro de secuencia implementado como una clase PHP derivada de php_user_filter

### 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.

Valor de Retorno | Significado
--- | ---
`PSFS_PASS_ON` | El filtro fue procesado satisfactoriamente con los datos disponibles en la brigada de paquetes `salida` .
`PSFS_FEED_ME` | El filtro fue procesado satisfactoriamente, sin embargo, no habían datos disponibles para devolver. Se requieren más datos desde la secuencia o desde el filtro anterior.
`PSFS_ERR_FATAL` (predeterminado) | El filtro experimentó un error irrecuperable y no puede continuar.

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.

Propiedad | Contenidos
--- | ---
ClaseFiltro->filtername | Una cadena que contiene el nombre con el que fue instanciado el filtro. Los filtros pueden ser registrados bajo múltiples nombres o bajo comodines. Use ésta propiedad para determinar el nombre que fue usado.
ClaseFiltro->params | Los contenidos del parámetro `parametros` pasado a stream_filter_append() o stream_filter_prepend().

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.

Example #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

Example #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().

stream_filter_prepend
stream_filter_remove
Stream Functions
PHP Manual