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

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

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

Hosting by: hurra.com
Generated: 2007-01-26 18:01:07