<HTML ><HEAD ><TITLE >stream_register_filter</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK REL="HOME" TITLE="Manual de PHP" HREF="index.html"><LINK REL="UP" TITLE="Stream functions" HREF="ref.stream.html"><LINK REL="PREVIOUS" TITLE="stream_get_wrappers" HREF="function.stream-get-wrappers.html"><LINK REL="NEXT" TITLE="stream_register_wrapper" HREF="function.stream-register-wrapper.html"><META HTTP-EQUIV="Content-type" CONTENT="text/html; charset=ISO-8859-1"></HEAD ><BODY CLASS="refentry" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#840084" ALINK="#0000FF" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="3" ALIGN="center" >Manual de PHP</TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="bottom" ><A HREF="function.stream-get-wrappers.html" ACCESSKEY="P" >Anterior</A ></TD ><TD WIDTH="80%" ALIGN="center" VALIGN="bottom" ></TD ><TD WIDTH="10%" ALIGN="right" VALIGN="bottom" ><A HREF="function.stream-register-wrapper.html" ACCESSKEY="N" >Siguiente</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><H1 ><A NAME="function.stream-register-filter" ></A >stream_register_filter</H1 ><DIV CLASS="refnamediv" ><A NAME="AEN73725" ></A ><P > (PHP 5 CVS only)</P >stream_register_filter -- Register a stream filter implemented as a PHP class derived from <TT CLASS="literal" >php_user_filter</TT ></DIV ><DIV CLASS="refsect1" ><A NAME="AEN73729" ></A ><H2 >Description</H2 >boolean <B CLASS="methodname" >stream_register_filter</B > ( string filtername, string classname)<BR ></BR ><P > <B CLASS="function" >stream_register_filter()</B > allows you to implement your own filter on any registered stream used with all the other filesystem functions (such as <A HREF="function.fopen.html" ><B CLASS="function" >fopen()</B ></A >, <A HREF="function.fread.html" ><B CLASS="function" >fread()</B ></A > etc.). </P ><P > To implement a filter, you need to define a class as an extension of <TT CLASS="literal" >php_user_fitler</TT > with a number of member functions as defined below. When performing read/write opperations on the stream to which your filter is attached, PHP will pass the data through your filter (and any other filters attached to that stream) so that the data may be modified as desired. You must implement the methods exactly as described below - doing otherwise will lead to undefined behaviour. </P ><P > <B CLASS="function" >stream_register_filter()</B > will return <TT CLASS="constant" ><B >FALSE</B ></TT > if the <TT CLASS="parameter" ><I >filtername</I ></TT > is already defined. </P >int <B CLASS="methodname" >write</B > ( string data)<BR ></BR ><P > This method is called whenever data is written to the attached stream (such as with <A HREF="function.fwrite.html" ><B CLASS="function" >fwrite()</B ></A >). After modifying <TT CLASS="parameter" ><I >data</I ></TT > as needed your filter should issue: <TT CLASS="literal" >return parent::write($data);</TT > so that the next filter in the chain can perform its filter. When no filters remain, the stream will write <TT CLASS="parameter" ><I >data</I ></TT > in its final form. <DIV CLASS="note" ><BLOCKQUOTE CLASS="note" ><P ><B >Nota: </B > If your filter alters the length of <TT CLASS="parameter" ><I >data</I ></TT >, for example by removing the first character, before passing onto <TT CLASS="literal" >parent::write($data);</TT > it must be certain to include that stolen character in the return count. </P ></BLOCKQUOTE ></DIV > <DIV CLASS="informalexample" ><A NAME="AEN73765" ></A ><P ></P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLPADDING="5" ><TR ><TD ><PRE CLASS="php" >class myfilter extends php_user_filter { function write($data) { $data = substr($data,1); $written_by_parent = parent::write($data); return ($written_by_parent + 1); } }</PRE ></TD ></TR ></TABLE ><P ></P ></DIV > </P >string <B CLASS="methodname" >read</B > ( int maxlength)<BR ></BR ><P > This method is called whenever data is read from the attached stream (such as with <A HREF="function.fread.html" ><B CLASS="function" >fread()</B ></A >). A filter should first call <TT CLASS="literal" >parent::read($maxlength);</TT > to retrieve the data from the previous filter who, ultimately, retrieved it from the stream. Your filter may then modify the data as needed and <TT CLASS="literal" >return</TT > it. Your filter should never return more than <TT CLASS="parameter" ><I >maxlength</I ></TT > bytes. Since <TT CLASS="literal" >parent::read($maxlength);</TT > will also not return more than <TT CLASS="parameter" ><I >maxlength</I ></TT > bytes this will ordinarily be a non-issue. However, if your filter increases the size of the data being returned, you should either call <TT CLASS="literal" >parent::read($maxlength-$x);</TT > where <TT CLASS="parameter" ><I >x</I ></TT > is the most your filter will grow the size of the data read. Alternatively, you can build a read-buffer into your class. </P >int <B CLASS="methodname" >flush</B > ( bool closing)<BR ></BR ><P > This method is called in response to a request to flush the attached stream (such as with <A HREF="function.fflush.html" ><B CLASS="function" >fflush()</B ></A > or <A HREF="function.fclose.html" ><B CLASS="function" >fclose()</B ></A >). The <TT CLASS="parameter" ><I >closing</I ></TT > parameter tells you whether the stream is, in fact, in the process of closing. The default action is to simply call: <TT CLASS="literal" >return parent::flush($closing);</TT > , your filter may wish to perform additional writes and/or cleanup calls prior to or directly after a successful flush. </P >void <B CLASS="methodname" >oncreate</B > ( void)<BR ></BR ><P > This method is called during instantiation of the filter class object. If your filter allocates or initializes any other resources (such as a buffer), this is the place to do it. </P >void <B CLASS="methodname" >onclose</B > ( void)<BR ></BR ><P > This method is called upon filter shutdown (typically, this is also during stream shutdown), and is executed <SPAN CLASS="emphasis" ><I CLASS="emphasis" >after</I ></SPAN > the <TT CLASS="literal" >flush</TT > method is called. If any resources were allocated or initialzed during <TT CLASS="literal" >oncreate</TT > this would be the time to destroy or dispose of them. </P ><P > The example below implements a filter named <TT CLASS="literal" >rot13</TT > on the <TT CLASS="literal" >foo-bar.txt</TT > stream which will perform ROT-13 encryption on all letter characters written to/read from that stream. <TABLE WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" CLASS="EXAMPLE" ><TR ><TD ><DIV CLASS="example" ><A NAME="AEN73809" ></A ><P ><B >Ejemplo 1. Filter for ROT13 encoding data on foo-bar.txt stream</B ></P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLPADDING="5" ><TR ><TD ><PRE CLASS="php" ><?php /* Define our filter class */ class rot13_filter extends php_user_filter { function read($length) { $tempstr = parent::read($length); for($i = 0; $i < strlen($tempstr); $i++) if (($tempstr[$i] >= 'A' AND $tempstr[$i] <= 'M') OR ($tempstr[$i] >= 'a' AND $tempstr[$i] <= 'm')) $tempstr[$i] = chr(ord($tempstr[$i]) + 13); else if (($tempstr[$i] >= 'N' AND $tempstr[$i] <= 'Z') OR ($tempstr[$i] >= 'n' AND $tempstr[$i] <= 'z')) $tempstr[$i] = chr(ord($tempstr[$i]) - 13); return $tempstr; } function write($data) { for($i = 0; $i < strlen($data); $i++) if (($data[$i] >= 'A' AND $data[$i] <= 'M') OR ($data[$i] >= 'a' AND $data[$i] <= 'm')) $data[$i] = chr(ord($data[$i]) + 13); else if (($data[$i] >= 'N' AND $data[$i] <= 'Z') OR ($data[$i] >= 'n' AND $data[$i] <= 'z')) $data[$i] = chr(ord($data[$i]) - 13); return parent::write($data); } } /* Register our filter with PHP */ stream_register_filter("rot13", "rot13_filter") or die("Failed to register filter"); $fp = fopen("foo-bar.txt", "w"); /* Attach the registered filter to the stream just opened */ stream_filter_append($fp, "rot13"); fwrite($fp, "Line1\n"); fwrite($fp, "Word - 2\n"); fwrite($fp, "Easy As 123\n"); fclose($fp); /* The filter only applies to the $fp stream * so this readfile will read -without- applying * a second pass of rot13 encoding */ readfile("foo-bar.txt"); /* Output * ------ Yvar1 Jbeq - 2 Rnfl Nf 123 */ ?></PRE ></TD ></TR ></TABLE ></DIV ></TD ></TR ></TABLE > </P ><P > See Also: <A HREF="function.stream-register-wrapper.html" ><B CLASS="function" >stream_register_wrapper()</B ></A >, <A HREF="function.stream-filter-prepend.html" ><B CLASS="function" >stream_filter_prepend()</B ></A >, and <A HREF="function.stream-filter-append.html" ><B CLASS="function" >stream_filter_append()</B ></A > </P ></DIV ><DIV CLASS="NAVFOOTER" ><HR ALIGN="LEFT" WIDTH="100%"><TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="function.stream-get-wrappers.html" ACCESSKEY="P" >Anterior</A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="index.html" ACCESSKEY="H" >Inicio</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><A HREF="function.stream-register-wrapper.html" ACCESSKEY="N" >Siguiente</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >stream_get_wrappers</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="ref.stream.html" ACCESSKEY="U" >Subir</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >stream_register_wrapper</TD ></TR ></TABLE ></DIV ></BODY ></HTML >